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
X-CorrelationID
request in client side.

UserLanguage FR or MG

Format msisdn;{{partnerND}}
UserAccountIdentifier
Ex: msisdn;0340017983

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

INITIATE TRANSACTION

amount Amount of transaction without decimals

Body
urlencoded currency Currency code of the transaction -

Possible Values - Ar

descriptionText Description on transaction. At most 50

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

requestDate Transaction requested date by client -

yyyy-MM-dd'T'HH:mm:ss.SSSZ format

debitParty/msisdn MSISDN of subscriber

creditParty/msisdn MSISDN of merchant

metadata/partnerName Name of the Partner. At most 50

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

requestingOrganisation Transaction ID of client side.

TransactionReference

3
 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

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

INITIATE TRANSACTION
Upon successful request THREE (3) outputs will be return

Response
status Static value “pending”
Success
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": [
{
"key": "msisdn",

4
 "value": "33555123456"
}
],
"creditParty": [
{
"key": "msisdn",
"value": "33555123456"
}
],
"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": "33555123456"
}
],
"creditParty": [
{
"key": "msisdn",
"value": "33555123456"
}
],
"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
Headers Version 1.0

ID from client to uniquely identify the

X-CorrelationID
request in client side.

UserLanguage FR or MG

Format msisdn;{{partnerND}}
UserAccountIdentifier
Ex: msisdn;0340017983

partnerName The name of the company

Content-Type application/json

Cache-Control no-cache

TRANSACTION DETAILS

Request Input transid MVola transaction ID

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;{{partnerMSISDN}} \
--header 'partnerName: {{partnerName}} \
--header 'Authorization: Bearer <ACCESS_TOKEN>\
--header 'Cache-Control: no-cache’ \
--data-raw ''

6
 TRANSACTION DETAILS
amount amount

Response currency Ar
Success
transactionReference transid

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
Request using API Authenticate>

Headers Version 1.0

ID from client to uniquely identify the

X-CorrelationID
request in client side.

UserLanguage FR or MG

Format msisdn;{{partnerND}}
UserAccountIdentifier
Ex: msisdn;0340017983

partnerName The name of the company

Content-Type application/json

Cache-Control no-cache

TRANSACTION STATUS

Request Input serverCorrelationId in Merchant Pay API

serverCorrelationId
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;{{partnerMSISDN}} \
--header 'partnerName: {{partnerName}} \
--header 'Authorization: Bearer <ACCESS_TOKEN> \
--header 'Cache-Control: no-cache’ \
--data-raw ''

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

serverCorrelationId serverCorrelationId in Merchant Pay API

Response

notificationMethod Notification method of the transaction -

polling or callback

objectReference Transaction reference of actual transaction