DOCUMENTATION

API Merchant Pay

Version : 1.0

SANDBOX https://devapi.mvola.mg
URL
PRODUCTION https://api.mvola.mg

This API present THREE (3) resources

POST Initiate /mvola/mm/transactions/type/merchantpay/1.0.0/

Transaction

GET Transaction Details /mvola/mm/transactions/type/merchantpay/1.0.0/{{transID}}

GET Transaction
/mvola/mm/transactions/type/merchantpay/1.0.0/status/{{serverCorrelationId}}
Status

Overview Merchant Pay API allow a tiers party to initiate a payment to a customer
and either get notified using a Callback Url or send a polling request to
view transaction status.

APIs The API is organized around REST

With JSON -encoded request body
Reference Return JSON-encoded responses and HTTP response code

1
 standard HTTP response code is used to indicate whether the
ERROR transaction is a success or a failure.

200 - OK Everything worked as expected.

The request was unacceptable, often due to

400 - Bad Request
missing a required parameter.

401 - Unauthorized No valid API key provided.

The parameters were valid but the request

402 - Request Failed
failed.

The API key doesn't have permissions to

403 - Forbidden
perform the request.

404 - Not Found The requested resource doesn't exist.

The request conflicts with another request

409 - Conflict (perhaps due to using the same idempotent
key).

Too many requests hit the API too quickly. We

429 - Too Many
recommend an exponential backoff of your
Requests
requests.

500, 502, 503, 504 -

Something went wrong on the server
Server Errors

Failed Due to internal or transactions issue

Failed transactions

ErrorCategory Error category

ErrorCode Error Code

ErrorDescription description on the error

ErrorDateTime Date and time when the error occurred

Key/value which add more details on the

ErrorParameters
nature of the error

Failed
If invalid credentials
Credentials issue

{
"fault": {
"code": 900901,
"message": "Invalid Credentials",
"description": "Invalid Credentials. Make sure you
have given the correct access token"
}
}

2
 INITIATE TRANSACTION

POST /mvola/mm/transactions/type/merchantpay/1.0.0/

Bearer <ACCESS_TOKEN initially

INITIATE TRANSACTION * Authorization
generated using API Authenticate>

Request * Version 1.0

Headers ID from client to uniquely identify the
request in client side. At most 40
* X-CorrelationID characters. Must be UUID format.

Ex: 123e4567-e89b-12d3-a456-426614174000

* UserLanguage FR or MG

Format msisdn;{{MerchantNumber}}
* UserAccountIdentifier MerchantNumber: the company phone number

Ex: msisdn;0343500004

partnerName The name of the company

* Content-Type application/json

In case client needs MVola to invoke

X-Callback-URL
client’s API once transaction is completed

* Cache-Control no-cache
* Mandatory

INITIATE TRANSACTION
* amount Amount of transaction without decimals
Body
* currency Currency code of the transaction -
urlencoded
Possible Values - Ar

* descriptionText Description on transaction. At most 50

characters long without special character
except : “-”, “.”, “_”, “,”

* requestDate Transaction requested date by client -

yyyy-MM-ddTHH:mm:ss.SSSZ format

* debitParty/msisdn Phone number of subscriber

In preprod it’s fixed: 0343500003 or 0343500004

* creditParty/msisdn Phone number of merchant

In preprod it’s fixed: 0343500003 or 0343500004

3
 * metadata Name of the Partner. At most 50
/partnerName characters long without special character
except : “-”, “.”, “_”, “,”

* Transaction ID of client side.

requestingOrganisation
TransactionReference At most 50 characters long without special
character except : “-”, “.”, “_”, “,”

originalTransaction Reference number related to the original

Reference transaction.

metadata/fc Foreign currency (euro, dollar, …)

metadata/amountFc The amount based of Foreign currency

* Mandatory

INITIATE TRANSACTION
curl --location --
request POST 'https://devapi.mvola.mg/mvola/mm/transactions/type/merchantpay/1.0.0
CURL /' \
Command --header 'Version: 1.0' \
--header 'X-CorrelationID: {{XCorrelationID}}' \
--header 'UserLanguage: mg' \
--header 'UserAccountIdentifier: msisdn;{{merchantNumber}} \
--header 'partnerName: {{companyName}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN> \
--header 'Cache-Control: no-cache’ \
--data-raw '{ "amount": "{{amount}}", "currency": "Ar", "descriptionText": "{{description}}",
"requestingOrganisationTransactionReference": "{{partnerTransid}}", "requestDate":
"{{requestDate}}", "originalTransactionReference": "{{originalTxRef}}", "debitParty": [ {
"key": "msisdn", "value": "{{customerNumber}}" } ], "creditParty": [ { "key": "msisdn", "value":
"{{MerchantNumber}}" } ], "metadata": [ { "key": "partnerName", "value":
"{{companyName}}" }, { "key": "fc", "value": "USD" }, { "key": "amountFc", "value": "1" } ] }'

INITIATE TRANSACTION
Upon successful request THREE (3) outputs will be returned
Response
Success status Static value “pending”

serverCorrelationId Reference value to correlate transaction in

client side

notificationMethod callback or polling

INITIATE TRANSACTION Success: PUT <third party url>

Success {
Callback "transactionStatus": "completed",
"serverCorrelationId": "421a22a2-ef1d-42bc-9452-f4939a3d5cdf",
Sample "transactionReference": "641235",
"requestDate": "2021-02-24T03:28:00.567Z",
"debitParty": [
{
4
 "key": "msisdn",
"value": "0343500003"
}
],
"creditParty": [
{
"key": "msisdn",
"value": "0343500004"
}
],
"fees": [
{
"feeAmount": "5.46"
}
],
"metadata": [
{
"key": "string",
"value": "string"
}
]
}

INITIATE TRANSACTION
Failed: PUT <third party url>
Failed
{
Callback "transactionStatus": "failed",
Sample "serverCorrelationId": "421a22a2-ef1d-42bc-9452-f4939a3d5cdf",
"transactionReference": "641235",
"requestDate": "2021-02-24T03:28:00.567Z",
"debitParty": [
{
"key": "msisdn",
"value": "0343500003"
}
],
"creditParty": [
{
"key": "msisdn",
"value": "0343500004"
}
],
"metadata": [
{
"key": "string",
"value": "string"
}
]
}

5
 TRANSACTION DETAILS

GET
/mvola/mm/transactions/type/merchantpay/1.0.0/{{transID}}

TRANSACTION DETAILS Bearer <ACCESS_TOKEN initially generated

* Authorization
using API Authenticate>
Request
* Version 1.0
Headers
ID from client to uniquely identify the
request in client side. At most 40
* X-CorrelationID characters. Must be UUID format.

Ex: 123e4567-e89b-12d3-a456-426614174000

UserLanguage FR or MG

Format msisdn;{{merchantNumber}}
* UserAccountIdentifier
Ex: msisdn;0343500004

* partnerName The name of the company

* Content-Type application/json

* Cache-Control no-cache
* Mandatory

TRANSACTION DETAILS
MVola transaction ID
Request Input transID
Retrieved from API Get transaction status response:
objectReference

curl --location --
TRANSACTION DETAILS request GET 'https://devapi.mvola.mg/mvola/mm/transactions/type/merchantpa
y/1.0.0/{{transID}}\
CURL --header 'Version: 1.0' \
--header 'X-CorrelationID: {{XCorrelationID}}' \
Command --header 'UserLanguage: FR' \
--header 'UserAccountIdentifier: msisdn;{{merchantNumber}} \
--header 'partnerName: {{companyName}} \
--header 'Authorization: Bearer <ACCESS_TOKEN>\
--header 'Cache-Control: no-cache’ \
--data-raw ''

6
 TRANSACTION DETAILS

amount amount
Response
Success currency Ar

transactionReference Transaction reference related to query

transactionStatus trans_result (if 0 “completed”, else “failed”)

createDate date - convert to standard format

debitParty/msisdn debtor

creditParty/msisdn creditor

metadata/originalTran result
sactionResult

metadata/originalTran Mapped value of “result” from error code

sactionResultDesc table

fee/feeAmount amount_fee

7
 TRANSACTION STATUS

GET /mvola/mm/transactions/type/merchantpay/1.0.0/status/{{serverCorrelationId}}

TRANSACTION STATUS Bearer <ACCESS_TOKEN initially generated

* Authorization
using API Authenticate>
Request * Version 1.0
Headers
ID from client to uniquely identify the
request in client side. At most 40
* X-CorrelationID characters. Must be UUID format.

Ex : 123e4567-e89b-12d3-a456-426614174000

* UserLanguage FR or MG

* Format msisdn;{{merchantNumber}}
UserAccountIdentifier
Ex: msisdn;0343500004

* partnerName The name of the company

* Content-Type application/json

* Cache-Control no-cache
* Mandatory

TRANSACTION STATUS
serverCorrelationId in Merchant Pay API
serverCorrelationId
Request Input Response

curl --location --
TRANSACTION STATUS request GET 'https://devapi.mvola.mg/mvola/mm/transactions/type/merchantpa
y/1.0.0/{{serverCorrelationId}}\
CURL --header 'Version: 1.0' \
--header 'X-CorrelationID: {{XCorrelationID}}' \
Command --header 'UserLanguage: FR' \
--header 'UserAccountIdentifier: msisdn;{{merchantNumber}} \
--header 'partnerName: {{companyName}} \
--header 'Authorization: Bearer <ACCESS_TOKEN> \
--header 'Cache-Control: no-cache’ \
--data-raw ''

8
 TRANSACTION STATUS
status Status of the transaction. Possible values:
Response • pending
• completed
• failed

serverCorrelationId serverCorrelationId in Merchant Pay API

Response

notificationMethod Notification method of the transaction -

polling or callback

objectReference transid - Transaction reference of actual

transaction