API User and Key Management
Authentication

There are two credentials used in the Open API.

Subscription Key

API User and API Key

The subscription key is used to give access to APIs in the API Manager portal. A user is assigned a subscription Key as and when the user subscribes to products in the API Manager Portal.

The API User and API Key are used to grant access to the wallet system in a specific country. API user and Key are wholly managed by the user through Partner Portal.

Users are allowed to generate/revoke API Keys through the Partner Portal.

However, on Sandbox Environment a Provisioning API is exposed to enable users to generate their own API User and API Key for testing purposes only.

Subscription Key

The subscription key is part of the header of all requests sent to the API Manager. The subscription key can be found under user profile in the API Manager Portal.

The subscription key is assigned to the Ocp-Apim-Subscription-Key parameter of the header.

API User and API Key for Oauth 2.0

The API user and API key are provisioned differently in the sandbox and production environment.

In the Sandbox a provisioning API is used to create the API User and API Key, whereas in the production environment the provisioning is done through the User Portal.

The sections below describe the different steps required in creating API User and API key in Sandbox and Production Environments.

Create API User


The Provider sends a POST {baseURL}/apiuser request to Wallet platform.

The Provider specifies the UUID Reference ID in the request Header and the subscription Key

Reference ID will be used as the User ID for the API user to be created.

Wallet Platform creates the User and responds with 201

Example

Request
POST {baseURL}/apiuser HTTP/1.1

Host: momodeveloper.mtn.com

X-Reference-Id: c72025f5-5cd1-4630-99e4-8ba4722fad56

Ocp-Apim-Subscription-Key: d484a1f0d34f4301916d0f2c9e9106a2{"providerCallbackHost": "clinic.com"}

Response
201 Created

Create API Key


The Provider sends a POST {baseURL}/apiuser/{APIUser}/apikey request to Wallet platform.

The Provider specifies the API User in the URL and subscription Key in the header.

Wallet Platform creates the API Key and responds with 201 Created with the newly Created API Key in the Body.

Provider now has both API User and API Key created.

Example

Request
POST {baseURL}/apiuser/c72025f5-5cd1-4630-99e4-8ba4722fad56/apikey HTTP/1.1

Host: momodeveloper.mtn.com

Ocp-Apim-Subscription-Key: d484a1f0d34f4301916d0f2c9e9106a2

Response
HTTP/1.1 201 Created date: Wed, 10 Oct 2018 09:16:15 GMT content-type: application/json;charset=utf-8 content-length: 45 { "apiKey": "f1db798c98df4bcf83b538175893bbf0" }

GET API User Details

It is possible to fetch API user details such as Call Back Host. However, it is not possible to fetch the API key.Provider shall be required to generate a new Key should they lose the existing one.


The Provider sends a GET {baseURL}/apiuser/{APIUser} request to Wallet platform.

The Provider specifies the API User in the URL and subscription Key in the header.

Wallet Platform responds with 200 Ok and details of the user.

TargetEnvironment is preconfigured to sandbox in the Sandbox environment, therefore Providers will not have the option of setting it to a different parameter.

Example

Request
GET {baseURL}/apiuser/ c72025f5-5cd1-4630-99e4-8ba4722fad56

Host: momodeveloper.mtn.com

Ocp-Apim-Subscription-Key: d484a1f0d34f4301916d0f2c9e9106a2

Response
HTTP/1.1 200 Accepted date: Wed, 10 Oct 2018 09:16:15 GMT { "providerCallbackHost": "clinic.com", "targetEnvironment": "sandbox" }

Oauth 2.0

The Open API uses Oauth 2.0 token for authentication of request. User will request an access token using Client Credential Grant according to RFC 6749. The token received is according to RFC 6750 Bearer Token.

The API user and API key are used in the basic authentication header when requesting the access token. The API user and key are managed in the Partner GUI for the country where the account is located. The Partner can create and manage API user and key from the Partner GUI.

In the Sandbox, the API Key and API User are managed through the Provisioning API

The received token has an expiry time. The same token can be used for transactions until it expires. A new token is requested by using the POST /token service in the same way as the initial token. The new token can be requested for before the previous one has expired to avoid authentication failure due to expired token.

Important: The token must be treated as a credential and kept secret. The party that have access to the token will be authenticated as the user that requested the token. The below sequence describes the flow for requesting a token and using the token in a request.


Provider system requests an access token using the API Key and API user as authentication.

Wallet platform authenticates credentials and responds with the access token

Provider system will use the access token for any request that is sent to Wallet Platform, e.g. POST /requesttopay

Note: The same token shall be used if it is not expired.

API Methods

The API uses POST, GET, PUT methods. This section gives an overview of the interaction sequence used in the API and the usage of the methods.

POST
POST method is used for creating a resource in Wallet Platform. The request includes a reference id which is used to uniquely identify the specific resource that are created by the POST request. If a POST is using a reference id that is already used, then a duplication error response will be sent to the client.

Example

POST /requesttopay

The POST is an asynchronous method. The Wallet Platform will validate the request to ensure that it is correct according to the API specification and then answer with HTTP 202 Accepted. The created resource will get status PENDING. Once the request has been processed the status will be updated to SUCCESSFUL or FAILED. The requester may then be notified of the final status through callback.

GET
Example

GET is used for requesting information about a specific resource. The URL in the GET shall include the reference of the resource. If a resource was created with POST then the reference id that was provided in the request is used as the identity of the resource.

POST /requesttopay request is sent with X-Reference-Id = 11377cbe-374c-43f6-a019-4fb70e57b617

GET /requesttopay/11377cbe-374c-43f6-a019-4fb70e57b617 will return the status of the request.

PUT
The PUT method is used by the Open API when sending callbacks. Callback is sent if a callback URL is included in the POST request. The Wallet Platform will only send the callback once. There is no retry on the callback if the Partner system does not respond. If the callback is not received, then the Partner system can use GET to validate the status.



Use Cases
Select the product of interest and the use case

Follow the APIs as shown. Execute in sequential order.

Product Set: 
Select a Product
 Use Case: 

Request To Pay

Request to Pay service is used for requesting a payment from a customer (Payer). This can be used by e.g. an online web shop to request a payment for a customer. The customer is requested to approve the transaction on the customer client.


Customer (Payer) have selected product(s) in the merchant web shop and decided to check out. Customer select to pay with Mobile Money.

The provider system collects the account information for the customer e.g. mobile number and calculate the total amount of the products.

The provider system sends a request to pay (POST /requesttopay) operation to Wallet Platform. This request includes the amount and customer (Payer) account holder number.

Wallet Platform will respond with HTTP 202 Accepted to the provider system

Provider shall inform the customer that a payment needs to be approved, by giving information on the merchant web page. For example, the merchant could show information that payment is being processed and that customer needs to approve using the own client, e.g. USSD, mobile app.

Wallet Platform will process the request so that the customer can approve the payment. The request to pay will be in PENDING state until the customer have approved/Rejected the payment.

The Customer (Payer) will use his/her own client to review the payment. Customer can approve or reject the payment.

Wallet platform will transfer the funds if the customer approves the payment. Status of the payment is updated to SUCCESSFUL or FAILED.

If a callback URL was provided in the POST /requesttopay then a callback will be sent once the request to pay have reached a final state (SUCCESSFUL, FAILED). Note the callback will only be sent once. There is no retry.

GET request can be used for validating the status of the transaction. GET is used if the partner system has not requested a callback by providing a callback URL or if the callback was not received.

Pre-Approval

Pre-approval is used to setup an auto debit towards a customer. The Partner can request a pre-approval from the customer. Once the customer has approved then the partner can debit the customer account without authorization from the customer.

The call flow for setting up a pre-approval is like the request to pay use case. The following picture describes the sequence for pre-approval.


The Provider sends a POST /preapproval request to Wallet platform.

Provider shall inform the customer that pre-approval needs to be approved.

Customer (Payer) will use the own client to view the pre-approval request. Customer can approve or reject the request.

Callback will be sent if a callback URL was provided in the POST request. The callback is sent when the request has reach a final state (Successful, Failed).

The Provider can use the GET request to validate the status of the pre-approval.

Transfer

Transfer is used for transferring money from the provider account to a customer.

The below sequence gives an overview of the flow of the transfer use case.


The Provider sends a POST /transfer request to Wallet platform.

Wallet platform will directly respond to indicate that the request is received and will be processed.

Wallet platform will authorize the request to ensure that the transfer is allowed. The funds will be transferred from the provider account to the Payee account provided in the transfer request.

Callback will be sent if a callback URL was provided in the POST request. The callback is sent when the request has reach a final state (SUCCESSFUL, FAILED).

The Provider can use the GET request to validate the status of the transfer.

Validate Account Holder

Validate account holder can be used to do a validation if a customer is active and able to receive funds. The use case will only validate that the customer is available and active. It does not validate that a specific amount can be received.

The sequence for the validate account holder is described below.


The Partner can send a GET /accountholder request to validate is a customer is active. The Partner provides the id of that customer as part of the URL

Wallet platform will respond with HTTP 200 if the account holder is active.

Get Balance

Get balance request is used to check the balance on the default account connected to the API User. The following is the sequence flow for get balance use case.

Delivery Notification

This service is intended to provide an additional notification to a customer after the completion of a successful financial transaction, by SMS or by email.

Merchants and Service Providers using PGW (Partner gateway is an application responsible for connecting API manager to different Wallet instances across all the Opcos) to interact with the Wallet Platform have the capability to send a notification to their customers after completed transaction.

Additional information is sent via SMS and is free text that may contain information that a partner wants to communicate for example, delivery notification reference number, a lottery number, a booking number, ticket id etc.

The channel used to send the notification will be determined based on what identity was used to initiate original transaction/payment.

The time window during which partner can use additional notification is configured in Partner Gateway.


Validate Consumer Identity

The Validate Consumer Identity use case (KYC as a service) enables a partner to retrieve (limited) customer KYC information with their consent. Upon request by the service provider, the customer will authorize, authenticate and provide consent to get detailed information.

The Partner will receive a short-lived token to fetch detailed information of the customer from the wallet platform.

The basic information that can be retrieved by default is Profile: Name, Gender, Date of birth, locale etc.

API: GetBasicUserinfo can be used to either validate for example, Consumer's age or name.

The use case will return limited information about the Consumer that can be used to pre-populate fields, validate the Consumer's age or use it for remittance or sanctions screening purposes.


Get consumer information with consent

This use case (Authentication as a Service) is used to validate/authenticate customer information, by way of a service provider sending a request to the wallet platform, with or without customer consent. The consumer will authenticate via authorization service, and if required, the consumer will be required to provide consent. The scope is to validate or retrieve customer information.

This use case will also enable a partner to obtain consent, or digitally accept terms and conditions. This can be seen as a â€œdigital signatureâ€ (where a partner requires this).

A partner may also be able to fetch limited user info without requiring customer consent. This will also enable partners to record and review that a customer has accepted the terms of a contract (amongst other use cases).

This will be used as a base when any token based â€œas a serviceâ€ is required.

API: bc-authorize.

It provides the Partner with the ability to fetch detailed information about a Consumer, after the Consumer has given the Partner consent for the retrieval of said information:

 Token based API Authorization
Token based API authorization is required to support consent management for different services. The Partner will request consent from the consumer for certain financial and non-financial transactions, and this will remain valid until the account holder revokes the consent.

The functionalities that can be enhanced by using consent will be:

1. Transfer

2. Payment

3. Merchant payment

4. Transfer to any bank account

For partners, this will enable them to view the status of the transactions for which consent was given using the related parameters. For account holders, they can revoke the consent from any service at their will.

Business benefit of consent can be improved customer experience. Consent can be configured for a specific time and there will be no need to get consent for each transaction. Providing better control on what services are being allowed by the account holder for consent etc.

Transfer with consumer consent

Gives the partner the ability to transfer money on behalf of a consumer, after the consumer has given the partner consent to do so.


Merchant payment with consumer consent

Gives the Merchant System (partner) the possibility to perform a merchant payment on behalf of a consumer to any receiver. This will only be possible after the Consumer has given the Merchant System (partner) a consent for doing so.


Payment with consumer consent

Gives the Merchant System (partner) the possibility to perform a payment on behalf of a consumer to any receiver. This will only be possible after the Consumer has given the Merchant System (partner) a consent for doing so.

Payment with consent will be similar to Merchant Payment. For more details, Please refer above section- "Merchant Payment with Consumer Consent".

Bank transfer with consumer consent

Gives the Merchant System (partner) the possibility to perform a Bank Transfer on behalf of a consumer to any receiver. This will only be possible after the Consumer has given the Merchant System (partner) a consent for doing so.

Bank transfer with consent will be similar to Transfer with Consent. For more details, Please refer above section- "Transfer with Consumer Consent".

← API User & API Key Management


Sandbox Use Cases
To facilitate testing a set of predefined users and Test accounts are provided. These users and accounts have a predefined test scenario. A developer needs to Signup and Subscribe to a Product before accessing any of the APIs.

In order to test Sandbox Use cases, Merchants/Agents/Partners/Testers needs to use the Sandbox Provisioning Collection and generate the apiuser and apikey and the same needs to be used for testing any of the sandbox Use cases. Existing Partner Accounts created on Partner GUI can't be used for testing the sandbox usecases.

OAuth Token

OAuth Token is generated from the merchants' API Key and Secret. The API Key and API Secret can be obtained through the provisioning API in Sandbox, as described in the API User and API Key Management section.

Test Environment

The Target Environment used in Testing is 'Sandbox'

Test Currency

The currency used in Sandbox is EUR

Sandbox Use Case

The following Numbers are predefined with respective response for all Testcases.

Sandbox Use Case	Testing Values
AccountBalanceResponses	Success,AccountNotFound,ZeroBalance,
NegativeBalance,NotAllowed,
NotAllowedTargetEnvironment,
InternalProcessingError,ServiceUnavailable
AccountHolderActiveMsisdnNotFound	46733123450
AccountHolderActiveMsisdnNotActive	46733123451
AccountHolderActiveMsisdnNotAllowed	46733123452
AccountHolderActiveMsisdnNotAllowedTargetEnvironment	46733123453
AccountHolderActiveMsisdnInternalProcessingError	46733123454
AccountHolderActiveMsisdnServiceUnavailable	46733123455
AccountHolderActiveEmailNotFound	notfound@email.com
AccountHolderActiveEmailNotActive	notactive@email.com
AccountHolderActiveEmailNotAllowed	notallowed@email.com
AccountHolderActiveEmailNotAllowedTargetEnvironment	notallowedtargetenvironment@email.com
AccountHolderActiveEmailInternalProcessingError	internalprocessingerror@email.com
AccountHolderActiveEmailServiceUnavailable	serviceunavailable@email.com
AccountHolderActivePartyCodeNotFound	5cecb5a7-8bd0-4f49-87b1-8eb9ecc7b7bc
AccountHolderActivePartyCodeNotActive	b0040b3c-b426-4a90-af6e-673e65861cd7
AccountHolderActivePartyCodeNotAllowed	4d5f500f-c385-4901-9be5-25b6d36ad220
AccountHolderActivePartyCodeNotAllowedTargetEnvironment	d2265f9b-0c22-496d-908f-79a65ad66266
AccountHolderActivePartyCodeInternalProcessingError	8f548a78-ceb8-4d12-a243-5640b91e91a4
AccountHolderActivePartyCodeServiceUnavailable	585c07a4-2c80-42f7-9e73-e586b36dee68
RequestToPayPayerFailed	46733123450
RequestToPayPayerRejected	46733123451
RequestToPayPayerExpired	46733123452
RequestToPayPayerOngoing	46733123453
RequestToPayPayerDelayed	46733123454
RequestToPayPayerNotFound	46733123455
RequestToPayPayerPayeeNotAllowedToReceive	46733123456
RequestToPayPayerNotAllowed	46733123457
RequestToPayPayerNotAllowedTargetEnvironment	46733123458
RequestToPayPayerInvalidCallbackUrlHost	46733123459
RequestToPayPayerInvalidCurrency	46733123460
RequestToPayPayerInternalProcessingError	46733123461
RequestToPayPayerServiceUnavailable	46733123462
RequestToPayPayerCouldNotPerformTransaction	46733123463
PreApprovalPayerFailed	46733123450
PreApprovalPayerRejected	46733123451
PreApprovalPayerExpired	46733123452
PreApprovalPayerOngoing	46733123453
PreApprovalPayerDelayed	46733123454
PreApprovalPayerNotFound	46733123455
PreApprovalPayerNotAllowed	46733123456
PreApprovalPayerNotAllowedTargetEnvironment	46733123457
PreApprovalPayerInvalidCallbackUrlHost	46733123458
PreApprovalPayerInvalidCurrency	46733123459
PreApprovalPayerInternalProcessingError	46733123460
PreApprovalPayerServiceUnavailable	46733123461
RequestToWithdrawPayerFailed	46733123450
RequestToWithdrawPayerRejected	46733123451
RequestToWithdrawPayerExpired	46733123452
RequestToWithdrawPayerOngoing	46733123453
RequestToWithdrawPayerDelayed	46733123454
RequestToWithdrawPayerNotFound	46733123455
RequestToWithdrawPayerPayeeNotAllowedToReceive	46733123456
RequestToWithdrawPayerNotAllowed	46733123457
RequestToWithdrawPayerNotAllowedTargetEnvironment	46733123458
RequestToWithdrawPayerInvalidCallbackUrlHost	46733123459
RequestToWithdrawPayerInvalidCurrency	46733123460
RequestToWithdrawPayerInternalProcessingError	46733123461
RequestToWithdrawPayerServiceUnavailable	46733123462
RequestToWithdrawPayerCouldNotPerformTransaction	46733123463
RefundTransactionNotFound	1
RefundTransactionFailed	2
RefundTransactionRejected	3
RefundTransactionExpired	4
RefundTransactionOngoing	5
RefundTransactionDelayed	6
RefundTransactionNotAllowed	7
RefundTransactionNotAllowedTargetEnvironment	8
RefundTransactionInvalidCallbackUrlHost	9
RefundTransactionInvalidCurrency	10
RefundTransactionInternalProcessingError	11
RefundTransactionServiceUnavailable	12
RefundTransactionCouldNotPerformTransaction	13
DepositPayerFailed	46733123450
DepositPayerRejected	46733123451
DepositPayerExpired	46733123452
DepositPayerOngoing	46733123453
DepositPayerDelayed	46733123454
DepositPayerNotFound	46733123455
DepositPayerPayeeNotAllowedToReceive	46733123456
DepositPayerNotAllowed	46733123457
DepositPayerNotAllowedTargetEnvironment	46733123458
DepositPayerInvalidCallbackUrlHost	46733123459
DepositPayerInvalidCurrency	46733123460
DepositPayerInternalProcessingError	46733123461
DepositPayerServiceUnavailable	46733123462
DepositPayerCouldNotPerformTransaction	46733123463
TransferPayeeFailed	46733123450
TransferPayeeRejected	46733123451
TransferPayeeExpired	46733123452
TransferPayeeOngoing	46733123453
TransferPayeeDelayed	46733123454
TransferPayeeNotEnoughFunds	46733123455
TransferPayeePayerLimitReached	46733123456
TransferPayeeNotFound	46733123457
TransferPayeeNotAllowed	46733123458
TransferPayeeNotAllowedTargetEnvironment	46733123459
TransferPayeeInvalidCallbackUrlHost	46733123460
TransferPayeeInvalidCurrency	46733123461
TransferPayeeInternalProcessingError	46733123462
TransferPayeeServiceUnavailable	46733123463
Oauth2CustomScopes	all_info
Oauth2AccountHolderNotFound	46733123450
Oauth2ConsentRejected	46733123451
Oauth2ConsentPending	46733123452
Oauth2ConsentExpired	46733123453
Oauth2ConsentExpiredRefreshToken	46733123454
Oauth2ConsentRevoked	46733123455
Oauth2ConsentDeletedScope	46733123456
Oauth2ConsentAlreadyUsed	46733123457
Oauth2FinancialNoFunds	46733123458
Oauth2FinancialPayeeNotFound	46733123459
Oauth2FinancialConsentMismatch	46733123460
Oauth2FinancialPayerLimitReached	46733123461
Oauth2FinancialPayeeNotAllowedToReceive	46733123462
CashTransferTransactionNotFound	1
CashTransferTransactionFailed	2
CashTransferTransactionRejected	3
CashTransferTransactionExpired	4
CashTransferTransactionPayeeNotFound	5
CashTransferTransactionPayeeNotAllowedToReceive	6
CashTransferTransactionNotAllowed	7
CashTransferTransactionNotAllowedTargetEnvironment	8
CashTransferTransactionInvalidCallbackUrlHost	9
CashTransferTransactionInvalidCurrency	10
CashTransferTransactionInternalProcessingError	11
CashTransferTransactionServiceUnavailable	12
CashTransferTransactionCouldNotPerformTransaction	13
Any other number results in Success

← Use Cases


Common Error Codes
The complete definitions of error codes are found in the swagger documentation. Below is the list of error codes available.

Common Error Codes

HTTP Code	Error Response Code	Description	Action
409	RESOURCE_ALREADY_EXIST	Duplicated Reference ID. Every request must have a unique reference ID; using an ID of the previous request will result in this error response.	Check X-Reference ID used is unique and is in UUID V4 format
401	ACCESS DENIED DUE TO INVALID SUBSCRIPTION KEY	Authentication failed.Credentials invalid.Header Ocp-APIM-Subscription-Key value is incorrect.	Check the User Profile Section to verify the related product subscription key is used. Collection, Disbursement and Remittance have different subscription keys. If the primary key doesnâ€™t work, try the secondary key. Contact MTN support if both provided keys aren't working. Sandbox subscription key are located in https://momodeveloper.mtn.com/developer Production subscription key are located in https://momoapi.mtn.com/developer
404	RESOURCE NOT FOUND	Reference ID not found. Requested resource does not exist. Predominantly occurs with Get Status API and implies that the requested reference ID does not exist. This results in the Request to Debit or Transfer transaction being unsuccessful.	Check if the original request to pay or the transfer (disbursement) operation was successful with response code 202.
400	REQUEST REJECTED/ BAD REQUEST	Bad request. Request does not follow the specification.	This relates to any of the below scenarios:
- Incorrect/wrong values in the headers, and/or the X-ref ID does not meet UUID Version 4.
- Inputting a Body in an API that is not supported e.g. /Token API
- Having unsupported special characters in the Body request for example an apostrophe (').
- Invalid currency â€“ needs to match the target environment currency.
- More than 160 characters in the note and message; explore utilizing the notification API for increased number of characters.
- The URL posted to needs to reviewed e.g. incorrect number of forward slashes (///).
403	FORBIDDEN IP	Authorization failed. IP not authorized to utilize Disbursement API.	Share your originating Public IP from which the APIs are called with your MTN Account Manager.
500	NOT_ALLOWED	Authorization failed. User does not have permission.The account authenticated with the Request via Token is restricted.	Contact your MTN Account Manager.
500	NOT_ALLOWED_TARGET_ENVIRONMENT	Value passed in header X-Target-Environment is incorrect	Use the correct X-targetenvironment corresponding to below country:
- MTN Uganda= mtnuganda
- MTN Ghana= mtnghana
- MTN Ivory Coast= mtnivorycoast
- MTN Zambia= mtnzambia
- MTN Cameroon= mtncameroon
- MTN Benin= mtnbenin
- MTN Congo= mtncongo
- MTN Swaziland= mtnswaziland
- MTN GuineaConakry= mtnguineaconakry
- MTN SouthAfrica= mtnsouthafrica
- MTN Liberia= mtnliberia
For Test Environment = sandbox
500	INVALID_CALLBACK_URL_HOST	Callback URL with different host name to configured for API User.
Check the Host of the Call Back URL in the request header; this needs to match what was configured on the partner portal when creating the API user and Key.	Host needs to be configured using Hostname and not IP address.
500	INVALID_CURRENCY	Currency not supported on the requested account	Use Currency Code specific to the Country.
503	SERVICE_UNAVAILABLE	Service temporary unavailable, try again later	Enquire with MTN Support.
Common Error Responses with Action

Type	Description	Action
INTERNAL_PROCESSING_ERROR	Default or Generic error code used when there is no specific error mapping. This predominantly occurs due to insufficient customer funds to complete the transaction.
Also related to service denied or Wallet Platform is not reachable.	Advice customer to ensure they have sufficient funds to complete the transaction. Also request the customer to retry the transaction. If the problem still occurs with sufficient customer funds, please contact your MTN Account Manager for further investigation.
PAYEE_NOT_FOUND	The MSISDN being paid to is invalid.	MSISDN format must include country code. MSISDN is not registered for Mobile Money Service.
PAYER_NOT_FOUND	MSISDN of the number from whom the money was requested in invalid.	MSISDN format must include country code.MSISDN is not registered for Mobile Money Service.
COULD_NOT_PERFORM_TRANSACTION	This can be attributed to transaction timeout. This predominantly occurs with a delay to approve a transaction within the given time frame (5 minutes).	Advise customer to try again and approve transaction within 5 minutes.
← Sandbox Use Case


Callback
Setting up a callback URL

Transfer and RequestToPay APIs are Asynchronous in MTN MoMo API Platform

When a merchant system sends a POST of either /transfer, or /requesttopay APIs, the Gateway validates the request and then responds with '202 Accepted'

The transaction is then queued for processing.

Once processed, a callback with the final result of the transaction is sent to the merchant system

In order to receive the callback for your transactions, please consider the following:

a) On Sandbox

Register your callback host by specifying the domain as providerCallbackHost when creating your API Keys. On production this will be done via the Account Portal

Specify the callback URL in each of your /requesttopay or /tranfer POST

Use http and not https on sandbox

Allow PUT & POST on your callback listener host

a) On Production

After Go-live you will be provided a link to log on to your Accounts Portal

You will be required to register you callback host on the portal when creating your API keys as shown below

Only https is allowed on production

Allow PUT & POST on your callback listener host


The Wallet Platform will only send the callback once. There is no retry on the callback if the Partner system does not respond. A merchant system can, in cases where a callback was not received , poll for the transaction status as described in the GET method

Let's look at the Deposit API under the product set Disbursement for instance.

The are two Deposit APIs - Deposit-V1 and Deposit-V2.

The callback resuest for Deposit-V1 can be sent via

https://momodeveloper.mtn.com/API-collections#api=disbursement&operation=Deposit-V1

The callback received would be of the type POST.


Approved Intermediate CA's for Open API

For Open API callbacks to function, the 3PP Intermediate certificate chains must be imported on the PGâ€™s tls_keystore and callback URLâ€™s are required to use https L7 protocol:

CN â€“ Refers to the Common name of the immediate intermediate CA Chain

Alias â€“ Name that is used while storing the Certificate in PGâ€™s tls_keystore

Below is the list of Approved Intermediate CA's that's already available to use:

Alias	CN
GTS_CA_1C3	CN=GTS CA 1C3; O=Google Trust Services LLC; C=US
Go_Daddy_Secure_Certificate_Authority_-_G2	CN=Go Daddy Secure Certificate Authority - G2; OU=http://certs.godaddy.com/repository/; O=GoDaddy.com, Inc.; C=US
R3	CN=R3; O=Let's Encrypt; C=US
Sectigo_RSA_Domain_Validation_Secure_Server_CA	CN=Sectigo RSA Domain Validation Secure Server CA; O=Sectigo Limited; C=GB
AmazonRCA4	CN = Amazon Root CA 4,O = Amazon,C = US
AmazonCA1B	CN = Amazon,OU = Server CA 1B,O = Amazon,C = US
Encryption_Everywhere_DV_TLS_CA_-_G1	CN=Encryption Everywhere DV TLS CA - G1; OU=www.digicert.com; O=DigiCert Inc; C=US
cPanel,_Inc._Certification_Authority	CN=cPanel, Inc. Certification Authority; O=cPanel, Inc.; C=US
DigiCert_SHA2_Secure_Server_CA	CN=DigiCert SHA2 Secure Server CA; O=DigiCert Inc; C=US
GTS_CA_1D4	CN=GTS CA 1D4; O=Google Trust Services LLC; C=US
Cloudflare_Inc_ECC_CA-3	CN=Cloudflare Inc ECC CA-3; O=Cloudflare, Inc.; C=US
DigiCert_SHA2_High_Assurance_Server_CA	CN=DigiCert SHA2 High Assurance Server CA; OU=www.digicert.com; O=DigiCert Inc; C=US
ZeroSSL_RSA_Domain_Secure_Site_CA	CN=ZeroSSL RSA Domain Secure Site CA; O=ZeroSSL; C=AT
AlphaSSL_CA_-_SHA256_-_G2	CN=AlphaSSL CA - SHA256 - G2; O=GlobalSign nv-sa; C=BE
RapidSSL_TLS_DV_RSA_Mixed_SHA256_2020_CA-1	CN=RapidSSL TLS DV RSA Mixed SHA256 2020 CA-1; O=DigiCert Inc; C=US
Thawte_RSA_CA_2018	CN=Thawte RSA CA 2018; OU=www.digicert.com; O=DigiCert Inc; C=US
GoGetSSL_RSA_DV_CA	CN=GoGetSSL RSA DV CA; O=GoGetSSL; C=LV
Gandi_Standard_SSL_CA_2	CN=Gandi Standard SSL CA 2; O=Gandi; C=FR
GlobalSign_RSA_OV_SSL_CA_2018	CN=GlobalSign RSA OV SSL CA 2018; O=GlobalSign nv-sa; C=BE
DigiCert_TLS_RSA_SHA256_2020_CA1	CN=DigiCert TLS RSA SHA256 2020 CA1; O=DigiCert Inc; C=US
GeoTrust_RSA_CA_2018	CN=GeoTrust RSA CA 2018; OU=www.digicert.com; O=DigiCert Inc; C=US
Microsoft_RSA_TLS_CA_02	CN=Microsoft RSA TLS CA 02; O=Microsoft Corporation; C=US
SSL.com_RSA_SSL_subCA	CN=SSL.com RSA SSL subCA; O=SSL Corporation; C=US
RapidSSL_TLS_RSA_CA_G1	CN=RapidSSL TLS RSA CA G1; OU=www.digicert.com; O=DigiCert Inc; C=US
Thawte_EV_RSA_CA_2018	CN=Thawte EV RSA CA 2018; OU=www.digicert.com; O=DigiCert Inc; C=US
Microsoft_Azure_TLS_Issuing_CA_05	CN=Microsoft Azure TLS Issuing CA 05; O=Microsoft Corporation; C=US
GeoTrust_TLS_DV_RSA_Mixed_SHA256_2020_CA-1	CN=GeoTrust TLS DV RSA Mixed SHA256 2020 CA-1; O=DigiCert Inc; C=US
E1	CN=E1; O=Let's Encrypt; C=US
Sectigo_ECC_Domain_Validation_Secure_Server_CA	CN=Sectigo ECC Domain Validation Secure Server CA; O=Sectigo Limited; C=GB
COMODO_RSA_Domain_Validation_Secure_Server_CA	CN=COMODO RSA Domain Validation Secure Server CA; O=COMODO CA Limited; C=GB
entrustl1k_.entrustrootca-g2	CN = Entrust Certification Authority - L1K,OU = (c) 2012 Entrust\, Inc. - for authorized use only,OU = See www.entrust.net/legal-terms,O = Entrust\, Inc.,C = US
NOTE: Incase any Partner's callback URL is not part of the Approved Intermediate CA's, callbacks might not work for the said Partners.


Brand Guidelines
MoMo LogoMoMo Logo
The MTN MoMo logo will only be used at the payment stage of your customer journey. Below are the brand guidelines for use of the MTN MoMo Brand:

When used, the logo sits in the bottom right hand corner of the messaging, against a white or MoMo Blue background

The distance between the logo and the border to the right and border to the bottom is always equal and equivalent size to the blue bulb that forms the MTN logo

The size of the logo will occupy the rectangle space of the ad where it features, scaled to feature prominently relative to all the other content in the ad

Color Palette
Reference to or usage of the MTN MoMo logo in other instances other than at the payment stage in the customer journey, will be restricted a statement of endorsement i.e. Supported by MTN MoMo. The use of the MTN MoMo in these instances is prohibited.







bc-authorize
Try it 
This operation is used to claim a consent by the account holder for the requested scopes.

Request
https://sandbox.momodeveloper.mtn.com/collection/v1_0/bc-authorize
Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Token. Replace with a valid oauth2 token received from oauth2 token endpoint in Wallet Platform.

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

X-Callback-Url
false
string
URL to the server where the callback should be sent.

Response: 200 OK
OK


application/json
bcauthorizeResponse


Name
Required
Type
Description
auth_req_id
false
string
Authentication request ID as an UUID.

interval
false
number
Indicates how long time the client should wait between retries towards the endpoint /oauth2/token.

expires_in
false
number
Shows when the authentication request ID expires, in seconds.

default
default - json
 Copy
{
    "auth_req_id": "string",
    "interval": 0,
    "expires_in": 0
}
Definitions
Name
Description
bcauthorizeResponse
bcauthorizeResponse


Name
Required
Type
Description
auth_req_id
false
string
Authentication request ID as an UUID.

interval
false
number
Indicates how long time the client should wait between retries towards the endpoint /oauth2/token.

expires_in
false
number
Shows when the authentication request ID expires, in seconds.



CancelInvoice
Try it 
This operation is used to delete an invoice. The ReferenceId is associated with the invoice to be cancelled

Request
https://sandbox.momodeveloper.mtn.com/collection/v2_0/invoice/{referenceId}
Request parameters
Name
In
Required
Type
Description
referenceId
template
true
string
UUID of transaction to get result. An id to uniquely identify the cancelling an Invoice

Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. The desired target environment to use that is allowed for the API user.

X-Reference-Id
true
string
Format - UUID. Recource ID of the created request to pay transaction. This ID is used, for example, validating the status of the request. ‘Universal Unique ID’ for the transaction generated using UUID version 4.

X-Callback-Url
false
string
PUT Callback URL to send callback to once the invoice is completed.

Request body
application/json
V2_0Invoice-referenceId-DeleteRequest-5


Name
Required
Type
Description
externalId
false
string
default
default - json
 Copy
{
    "externalId": "string"
}
Response: 200 OK
OK. Note that a failed CreateInvoice will be returned with this status too. The 'status' of the CreateInvoice can be used to determine the outcome of the request. The 'errorReason' field can be used to retrieve a cause in case of failure.


Successful Invoice Deleted
V2_0Invoice-referenceId-Delete200Successful-Invoice-DeletedResponse


Name
Required
Type
Description
externalId
false
string
An external transaction id to tie to the cancelling of an invoice.

Payer not found
application/json
Response: 400 Bad Request
Bad request, e.g. an incorrectly formatted reference id was provided.


application/json
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default - json
 Copy
{
    "code": "PAYEE_NOT_FOUND",
    "message": "string"
}
Response: 404 Not Found
Resource not found.


application/json
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default - json
 Copy
{
    "code": "PAYEE_NOT_FOUND",
    "message": "string"
}
Unspecified internal error
Response: 500 Internal Server Error
Internal Error. Note that if the retrieved request to pay has failed, it will not cause this status to be returned. This status is only returned if the GET request itself fails.


Unspecified internal error
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
Definitions
Name
Description
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

InvoiceResult
ErrorReason
V2_0Invoice-referenceId-DeleteRequest-5
V2_0Invoice-referenceId-Delete200Successful-Invoice-DeletedResponse
V2_0Invoice-referenceId-Delete200ApplicationJsonResponse
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid




Name
Required
Type
Description
partyIdType
false
string
partyId
false
string
InvoiceResult


Name
Required
Type
Description
referenceId
false
string
The reference id for this invoice.

externalId
false
string
An external transaction id to tie to the payment.

amount
false
string
A positive amount for this invoice.

currency
false
string
ISO4217 Currency - The currency used in this invoice.

status
false
string
paymentReference
false
string
A unique id that identifies a pending invoice.

invoiceId
false
string
An id for the invoice.

expiryDateTime
false
string
DateTime for when invoice expires, in YYYY-MM-DD:THH:mm:ss format.

payeeFirstName
false
string
First name of the payee in this invoice.

payeeLastName
false
string
Surname of the payee in this invoice

errorReason
false
ErrorReason
intendedPayer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

description
false
string
An optional description of the invoice.

ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
V2_0Invoice-referenceId-DeleteRequest-5


Name
Required
Type
Description
externalId
false
string
V2_0Invoice-referenceId-Delete200Successful-Invoice-DeletedResponse


Name
Required
Type
Description
externalId
false
string
An external transaction id to tie to the cancelling of an invoice.

V2_0Invoice-referenceId-Delete200ApplicationJsonResponse


Name
Required
Type
Description
externalId
false
string
An external transaction id to tie to the cancelling of an invoice.


CancelPreApproval
Try it 
This operation is used to cancel a pre-approval. It is possible to cancel only that preapproval which is in approved state and the requesting Account Holder (Service Provider or Merchant) is the payee

Request
https://sandbox.momodeveloper.mtn.com/collection/v1_0/preapproval/{preapprovalid}
Request parameters
Name
In
Required
Type
Description
preapprovalid
template
true
string
UUID of transaction to get result. Reference id used when creating the PreApproval.

Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Response: 200 OK
OK.


Response: 400 Bad Request
Bad request, e.g. an incorrectly formatted reference id was provided.


Response: 404 Not Found
Resource not found.


Response: 500 Internal Server Error
Internal Error. Note that if the retrieved request to pay has failed, it will not cause this status to be returned. This status is only returned if the GET request itself fails.


Unspecified internal error
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
Successful request to pay
Payer not found
application/json
Request to pay not found
Definitions
Name
Description
ErrorReason
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string

CreateAccessToken
Try it 
This operation is used to create an access token which can then be used to authorize and authenticate towards the other end-points of the API.

Request
https://sandbox.momodeveloper.mtn.com/collection/token/
Request headers
Name
Required
Type
Description
Authorization
true
string
Basic authentication header containing API user ID and API key. Should be sent in as B64 encoded.

Response: 200 OK
OK


application/json
TokenPost200ApplicationJsonResponse


Name
Required
Type
Description
access_token
false
string
A JWT token which can be used to authrize against the other API end-points. The format of the token follows the JWT standard format (see jwt.io for an example). This is the token that should be sent in in the Authorization header when calling the other API end-points.

token_type
false
string
The token type.

expires_in
false
integer
The validity time in seconds of the token.

default
default - json
 Copy
{
    "access_token": "string",
    "token_type": "string",
    "expires_in": 0
}
Response: 401 Unauthorized
Unauthorized


application/json
TokenPost401ApplicationJsonResponse


Name
Required
Type
Description
error
false
string
An error code.

default
default - json
 Copy
{
    "error": "string"
}
Response: 500 Internal Server Error
Error


Definitions
Name
Description
TokenPost200ApplicationJsonResponse
TokenPost401ApplicationJsonResponse
TokenPost200ApplicationJsonResponse


Name
Required
Type
Description
access_token
false
string
A JWT token which can be used to authrize against the other API end-points. The format of the token follows the JWT standard format (see jwt.io for an example). This is the token that should be sent in in the Authorization header when calling the other API end-points.

token_type
false
string
The token type.

expires_in
false
integer
The validity time in seconds of the token.

TokenPost401ApplicationJsonResponse


Name
Required
Type
Description
error
false
string
An error code.

CreateInvoice
Try it 
A merchant may use this in order to create an invoice that can be paid by an intended payer via any channel at a later stage.

Request
https://sandbox.momodeveloper.mtn.com/collection/v2_0/invoice
Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Callback-Url
false
string
PUT Callback URL to send callback to once the invoice is completed.

X-Reference-Id
true
string
Format - UUID. An id to uniquely identify the making of an invoice

X-Target-Environment
true
string
The desired target environment to use that is allowed for the API user.

Request body
application/json
CreateInvoice


Name
Required
Type
Description
externalId
false
string
External id is used as a reference to the transaction. External id is used for reconciliation. The external id will be included in transaction history report.
External id is not required to be unique.

amount
false
string
Amount that will be debited from the payer account.

currency
false
string
ISO4217 Currency

validityDuration
false
string
ValidityTime - The duration that the invoice is valid in seconds.

intendedPayer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payee
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

description
false
string
Message that will be written in the payer transaction history message field.

default
default - json
 Copy
{
    "externalId": "string (An external transaction id to tie to the payment.)",
    "amount": "string",
    "currency": "string",
    "validityDuration": "string(The duration that the invoice is valid in seconds.)",
    "intendedPayer": {
        "partyIdType": "MSISDN",
        "partyId": "string"
    },
    "payee": {
        "partyIdType": "MSISDN",
        "partyId": "string"
    },
    "description": "string (An optional description of the invoice.)"
}
Response: 202 Accepted
Accepted


Response: 400 Bad Request
Bad request, e.g. invalid data was sent in the request.


Response: 409 Conflict
Conflict, duplicated reference id


ReferenceId already in use
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
Unspecified internal error
Response: 500 Internal Server Error
Internal Error.


Unspecified internal error
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
ReferenceId already in use
Definitions
Name
Description
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

CreateInvoice
ErrorReason
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid




Name
Required
Type
Description
partyIdType
false
string
partyId
false
string
CreateInvoice


Name
Required
Type
Description
externalId
false
string
External id is used as a reference to the transaction. External id is used for reconciliation. The external id will be included in transaction history report.
External id is not required to be unique.

amount
false
string
Amount that will be debited from the payer account.

currency
false
string
ISO4217 Currency

validityDuration
false
string
ValidityTime - The duration that the invoice is valid in seconds.

intendedPayer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payee
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

description
false
string
Message that will be written in the payer transaction history message field.

ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string


CreateOauth2Token
Try it 
This operation is used to claim a consent by the account holder for the requested scopes.

Request
https://sandbox.momodeveloper.mtn.com/collection/oauth2/token/
Request headers
Name
Required
Type
Description
Authorization
true
string
Basic authentication header containing API user ID and API key. Should be sent in as B64 encoded.

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Response: 200 OK
OK


application/json
oauth2TokenResponse


Name
Required
Type
Description
access_token
false
string
Oauth2 JWT access token.The generated token is valid 3600 seconds as default.

token_type
false
string
Value is Bearer

expires_in
false
number
Shows when the authentication request ID expires, in seconds.

scope
false
string
List of scopes that belongs to the authentication request ID.

refresh_token
false
string
UUID of the refresh_token

refresh_token_expired_in
false
integer
The time in seconds until the consent can no longer be refreshed. Based on the default value for consent validity, or the value set to parameter consent_valid_in sent in the bc-authorize request.

default
default - json
 Copy
{
    "access_token": "string",
    "token_type": "string",
    "expires_in": 0,
    "scope": "string",
    "refresh_token": "string",
    "refresh_token_expired_in": 0
}
Definitions
Name
Description
oauth2TokenResponse
oauth2TokenResponse


Name
Required
Type
Description
access_token
false
string
Oauth2 JWT access token.The generated token is valid 3600 seconds as default.

token_type
false
string
Value is Bearer

expires_in
false
number
Shows when the authentication request ID expires, in seconds.

scope
false
string
List of scopes that belongs to the authentication request ID.

refresh_token
false
string
UUID of the refresh_token

refresh_token_expired_in
false
integer
The time in seconds until the consent can no longer be refreshed. Based on the default value for consent validity, or the value set to parameter consent_valid_in sent in the bc-authorize request.


CreatePayments
Try it 
Making it possible to perform payments via the partner gateway. This may be used to pay for external bills or to perform air-time top-ups.

Request
https://sandbox.momodeveloper.mtn.com/collection/v2_0/payment
Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Callback-Url
false
string
PUT Callback URL to send callback to once the invoice is completed.

X-Reference-Id
true
string
Format - UUID. An id to uniquely identify the making of an invoice

X-Target-Environment
true
string
The desired target environment to use that is allowed for the API user.

Request body
application/json
CreatePayments


Name
Required
Type
Description
externalTransactionId
false
string
An external transaction id to tie to the payment.

money
false
Money
customerReference
false
string
A customer reference for a provider. Example: +46070911111

serviceProviderUserName
false
string
A service provider name. Example: Electricity Inc.

couponId
false
string
A coupon the user would like to redeem and use the reward as part of this payment.

productId
false
string
Optional id of a product, used if paying for a product.

productOfferingId
false
string
Optional id of a product offering, used when paying for a particular offering of a product.

receiverMessage
false
string
A descriptive note for receiver transaction history.

senderNote
false
string
A descriptive note for sender transaction history.

maxNumberOfRetries
false
integer
maxNumberOfRetries

includeSenderCharges
false
boolean
Specifies if sender charges, this is, fee and tax paid by the sender, should be included in the specified transaction amount. This means that the charges will be deducted from the transaction amount before the remaining amount is transferred to the receiver.True indicates that charges shall be included in the specified transaction amount. The default value is false, meaning that sender charges are charged on top of the transaction amount.

default
default - json
 Copy
{
    "externalTransactionId": "string (An external transaction id to tie to the payment.)",
    "money": {
        "amount": "string",
        "currency": "string"
    },
    "customerReference": "String(661551442)",
    "serviceProviderUserName": "String"
}
Response: 202 Accepted
Accepted


Response: 400 Bad Request
Bad request, e.g. invalid data was sent in the request.


Response: 409 Conflict
Conflict, duplicated reference id


ReferenceId already in use
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
Unspecified internal error
Response: 500 Internal Server Error
Internal Error.


Unspecified internal error
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
ReferenceId already in use
Definitions
Name
Description
Money
CreatePayments
ErrorReason
Money


Name
Required
Type
Description
amount
false
string
A positive amount

currency
false
string
Currency in ISO4217 format

CreatePayments


Name
Required
Type
Description
externalTransactionId
false
string
An external transaction id to tie to the payment.

money
false
Money
customerReference
false
string
A customer reference for a provider. Example: +46070911111

serviceProviderUserName
false
string
A service provider name. Example: Electricity Inc.

couponId
false
string
A coupon the user would like to redeem and use the reward as part of this payment.

productId
false
string
Optional id of a product, used if paying for a product.

productOfferingId
false
string
Optional id of a product offering, used when paying for a particular offering of a product.

receiverMessage
false
string
A descriptive note for receiver transaction history.

senderNote
false
string
A descriptive note for sender transaction history.

maxNumberOfRetries
false
integer
maxNumberOfRetries

includeSenderCharges
false
boolean
Specifies if sender charges, this is, fee and tax paid by the sender, should be included in the specified transaction amount. This means that the charges will be deducted from the transaction amount before the remaining amount is transferred to the receiver.True indicates that charges shall be included in the specified transaction amount. The default value is false, meaning that sender charges are charged on top of the transaction amount.

ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string

GetAccountBalance
Try it 
Get the balance of own account.

Request
https://sandbox.momodeveloper.mtn.com/collection/v1_0/account/balance
Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Response: 200 OK
Ok


application/json
Balance
The available balance of the account




Name
Required
Type
Description
availableBalance
false
string
The available balance of the account

currency
false
string
ISO4217 Currency

default
default - json
 Copy
{
    "availableBalance": "string",
    "currency": "string"
}
Incorrect target environment
Response: 400 Bad Request
Bad request, e.g. invalid data was sent in the request.


Response: 500 Internal Server Error
Internal error. The returned response contains details.


Incorrect target environment
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
Definitions
Name
Description
Balance
The available balance of the account

ErrorReason
Balance
The available balance of the account




Name
Required
Type
Description
availableBalance
false
string
The available balance of the account

currency
false
string
ISO4217 Currency

ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string

GetAccountBalanceInSpecificCurrency
Try it 
Get the balance of own account. Currency parameter passed in GET

Request
https://sandbox.momodeveloper.mtn.com/collection/v1_0/account/balance/{currency}
Request parameters
Name
In
Required
Type
Description
currency
template
true
string
Should be in ISO4217 Currency

Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Response: 200 OK
Ok


application/json
Balance
The available balance of the account




Name
Required
Type
Description
availableBalance
false
string
The available balance of the account

currency
false
string
ISO4217 Currency

default
default - json
 Copy
{
    "availableBalance": "string",
    "currency": "string"
}
Incorrect target environment
Response: 400 Bad Request
Bad request, e.g. invalid data was sent in the request.


Response: 500 Internal Server Error
Internal error. The returned response contains details.


Incorrect target environment
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
Definitions
Name
Description
Balance
The available balance of the account

ErrorReason
Balance
The available balance of the account




Name
Required
Type
Description
availableBalance
false
string
The available balance of the account

currency
false
string
ISO4217 Currency

ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string

GetApprovedPreApprovals
Try it 
This operation is used to get approved pre-approvals of an account holder. Only those pre-approvals of account holder, where requesting Account Holder (Service Provider or Merchant) is the payee, are returned.

Request
https://sandbox.momodeveloper.mtn.com/collection/v1_0/preapprovals/{accountHolderIdType}/{accountHolderId}
Request parameters
Name
In
Required
Type
Description
accountHolderIdType
template
true
string
Specifies the type of the accountHolderId.

Allowed values: msisdn email id alias

accountHolderId
template
true
string
The AccountHolderId .

Validated according to the accountHolderIdType: msisdn - Mobile Number. Validated with IsMSISDN. email - E-mail. Validated with IsEmail. id - Internal Id of Account Holder. Validated with IsLongString. alias - Alias of the party. Validated with IsAlias.

Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Response: 200 OK
OK. Note that a failed CreateInvoice will be returned with this status too. The 'status' of the CreateInvoice can be used to determine the outcome of the request. The 'errorReason' field can be used to retrieve a cause in case of failure.


application/json
V1_0Preapprovals-accountHolderIdType-accountHolderId-Get200ApplicationJsonResponse


Name
Required
Type
Description
[]
true
PreApprovalDetails[]
default
default - json
 Copy
[{
    "preApprovalId": "string",
    "toFri": "string",
    "fromFri": "string",
    "fromCurrency": "string",
    "createdTime": "string",
    "approvedTime": "string",
    "expiryTime": "string",
    "status": "string",
    "message": "string",
    "frequency": "string",
    "startDate": "string",
    "lastUsedDate": "string",
    "offer": "string",
    "externalId": "string",
    "maxDebitAmount": "string"
}]
Response: 400 Bad Request
Bad request, e.g. an incorrectly formatted reference id was provided.


Response: 404 Not Found
Resource not found.


Response: 500 Internal Server Error
Internal Error. Note that if the retrieved request to pay has failed, it will not cause this status to be returned. This status is only returned if the GET request itself fails.


Unspecified internal error
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
Definitions
Name
Description
PreApprovalDetails
ErrorReason
V1_0Preapprovals-accountHolderIdType-accountHolderId-Get200ApplicationJsonResponse
PreApprovalDetails


Name
Required
Type
Description
preApprovalId
true
string
The ID of the pre-approval. Parameter cannot be NULL.

toFri
true
string
The Financial Resource Identifier of the receiving account.

fromFri
true
string
The Financial Resource Identifier of the sending account.

fromCurrency
true
string
The currency of the account holder from where the debit happens. ISO4217 Currency

createdTime
true
string
The date and time at which the pre-approval was created. Validated with IsIso8601DateTime. Parameter can not be NULL

approvedTime
false
string
The date and time at which the pre-approval was approved. Validated with IsIso8601DateTime. Parameter can not be NULL.

expiryTime
false
string
The date and time at which the pre-approval expires. Validated with IsIso8601DateTime. Parameter can not be NULL.

status
true
string
message
true
string
Message. Validated with IsRestirctedString. Parameter can not be NULL.

frequency
false
string
startDate
false
string
The start date of the pre-approval. Validated with IsDateString. Parameter can not be NULL.

lastUsedDate
false
string
The date pre-approval was used last. Validated with IsIso8601DateTime. Parameter can not be NULL.

offer
false
string
The offer description. Validated with IsRestrictedString. Parameter can not be NULL.

externalId
false
string
The external reference id. Validated with IsExternalReferenceString. Parameter can not be NULL.

maxDebitAmount
false
string
The max debit amount allowed. Contains a non-negative amount. Validated with IsAmount.

ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
V1_0Preapprovals-accountHolderIdType-accountHolderId-Get200ApplicationJsonResponse


Name
Required
Type
Description
[]
true
PreApprovalDetails[]


GetBasicUserinfo
Try it 
This operation returns personal information of the account holder. The operation does not need any consent by the account holder.

Request
https://sandbox.momodeveloper.mtn.com/collection/v1_0/accountholder/{accountHolderIdType}/{accountHolderId}/basicuserinfo
Request parameters
Name
In
Required
Type
Description
accountHolderIdType
template
true
string
Type of account holder identity passed in accountHolderId path param.

Possible values: MSISDN

Email

Alias

ID (account ID)

accountHolderId
template
true
string
ID of the account holder.

Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Response: 200 OK
OK


application/json
BasicUserInfoJsonResponse


Name
Required
Type
Description
given_name
false
string
Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

family_name
false
string
Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

birthdate
false
string
Account holder birth date.

locale
false
string
End-User's locale, represented as a BCP47 [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 [ISO639�|�1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166�|�1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compatibility note, some implementations have used an underscore as the separator rather than a dash, for example, en_US; Relying Parties may choose to accept this locale syntax as well.

gender
false
string
End-User's gender. Values defined by this specification are female and male. Other values may be used when neither of the defined values are applicable.

status
false
string
Accountholder status.

default
default - json
 Copy
{
    "given_name": "string",
    "family_name": "string",
    "birthdate": "string",
    "locale": "string",
    "gender": "string",
    "status": "string"
}
Response: 401 Unauthorized
Unauthorized


application/json
TokenPost401ApplicationJsonResponse


Name
Required
Type
Description
error
false
string
An error code.

default
default - json
 Copy
{
    "error": "string"
}
Response: 500 Internal Server Error
Error


Definitions
Name
Description
BasicUserInfoJsonResponse
TokenPost401ApplicationJsonResponse
BasicUserInfoJsonResponse


Name
Required
Type
Description
given_name
false
string
Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

family_name
false
string
Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

birthdate
false
string
Account holder birth date.

locale
false
string
End-User's locale, represented as a BCP47 [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 [ISO639�|�1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166�|�1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compatibility note, some implementations have used an underscore as the separator rather than a dash, for example, en_US; Relying Parties may choose to accept this locale syntax as well.

gender
false
string
End-User's gender. Values defined by this specification are female and male. Other values may be used when neither of the defined values are applicable.

status
false
string
Accountholder status.

TokenPost401ApplicationJsonResponse


Name
Required
Type
Description
error
false
string
An error code.

GetInvoiceStatus
Try it 
This operation is used to get the status of an invoice. X-Reference-Id that was passed in the post is used as reference to the request

Request
https://sandbox.momodeveloper.mtn.com/collection/v2_0/invoice/{x-referenceId}
Request parameters
Name
In
Required
Type
Description
x-referenceId
template
true
string
UUID of transaction to get result. Reference id used when creating the Invoice.

Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Response: 200 OK
OK. Note that a failed CreateInvoice will be returned with this status too. The 'status' of the CreateInvoice can be used to determine the outcome of the request. The 'errorReason' field can be used to retrieve a cause in case of failure.


Successful Invoice Created
InvoiceResult


Name
Required
Type
Description
referenceId
false
string
The reference id for this invoice.

externalId
false
string
An external transaction id to tie to the payment.

amount
false
string
A positive amount for this invoice.

currency
false
string
ISO4217 Currency - The currency used in this invoice.

status
false
string
paymentReference
false
string
A unique id that identifies a pending invoice.

invoiceId
false
string
An id for the invoice.

expiryDateTime
false
string
DateTime for when invoice expires, in YYYY-MM-DD:THH:mm:ss format.

payeeFirstName
false
string
First name of the payee in this invoice.

payeeLastName
false
string
Surname of the payee in this invoice

errorReason
false
ErrorReason
intendedPayer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

description
false
string
An optional description of the invoice.

Payer not found
application/json
Request to pay not found
Unspecified internal error
Response: 400 Bad Request
Bad request, e.g. an incorrectly formatted reference id was provided.


Response: 404 Not Found
Resource not found.


Request to pay not found
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
Successful request to pay
Payer not found
application/json
Unspecified internal error
Response: 500 Internal Server Error
Internal Error


Unspecified internal error
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
Request to pay not found
Definitions
Name
Description
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

InvoiceResult
ErrorReason
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid




Name
Required
Type
Description
partyIdType
false
string
partyId
false
string
InvoiceResult


Name
Required
Type
Description
referenceId
false
string
The reference id for this invoice.

externalId
false
string
An external transaction id to tie to the payment.

amount
false
string
A positive amount for this invoice.

currency
false
string
ISO4217 Currency - The currency used in this invoice.

status
false
string
paymentReference
false
string
A unique id that identifies a pending invoice.

invoiceId
false
string
An id for the invoice.

expiryDateTime
false
string
DateTime for when invoice expires, in YYYY-MM-DD:THH:mm:ss format.

payeeFirstName
false
string
First name of the payee in this invoice.

payeeLastName
false
string
Surname of the payee in this invoice

errorReason
false
ErrorReason
intendedPayer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

description
false
string
An optional description of the invoice.

ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string

GetPaymentStatus
Try it 
This operation is used to get the status of a Payment. X-Reference-Id that was passed in the post is used as reference to the request

Request
https://sandbox.momodeveloper.mtn.com/collection/v2_0/payment/{x-referenceId}
Request parameters
Name
In
Required
Type
Description
x-referenceId
template
true
string
UUID of transaction to get result. Reference id used when creating the Payment.

Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Response: 200 OK
OK. Note that a failed CreateInvoice will be returned with this status too. The 'status' of the CreateInvoice can be used to determine the outcome of the request. The 'errorReason' field can be used to retrieve a cause in case of failure.


Successful Payment Created
PaymentResult


Name
Required
Type
Description
referenceId
false
string
The reference id for this Payment.

status
false
string
financialTransactionId
false
string
A transaction id associated with this payment.

reason
false
ErrorReason
Payer not found
application/json
Payment not found
Unspecified internal error
Response: 400 Bad Request
Bad request, e.g. an incorrectly formatted reference id was provided.


Response: 404 Not Found
Resource not found.


Request to pay not found
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
Successful request to pay
Payer not found
application/json
Unspecified internal error
Response: 500 Internal Server Error
Internal Error. Note that if the retrieved request to pay has failed, it will not cause this status to be returned. This status is only returned if the GET request itself fails.


Unspecified internal error
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
Successful request to pay
Payer not found
application/json
Request to pay not found
Definitions
Name
Description
PaymentResult
ErrorReason
PaymentResult


Name
Required
Type
Description
referenceId
false
string
The reference id for this Payment.

status
false
string
financialTransactionId
false
string
A transaction id associated with this payment.

reason
false
ErrorReason
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string

GetPreApprovalStatus
Try it 
This operation is used to get the status of a pre-approval. X-Reference-Id that was passed in the post is used as reference to the request.

Request
https://sandbox.momodeveloper.mtn.com/collection/v2_0/preapproval/{referenceId}
Request parameters
Name
In
Required
Type
Description
referenceId
template
true
string
UUID of transaction to get result. Reference id used when creating the PreApproval.

Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Response: 200 OK
OK. Note that a failed CreateInvoice will be returned with this status too. The 'status' of the CreateInvoice can be used to determine the outcome of the request. The 'errorReason' field can be used to retrieve a cause in case of failure.


Successful Invoice Created
PreApprovalResult


Name
Required
Type
Description
payer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payerCurrency
false
string
ISO4217 Currency

payerMessage
false
string
The mesage that is shown to the approver.

status
false
string
expirationDateTime
false
integer
The expiry date +time of the preapproval, in YYYY-MM-DDTHH:mm:SS format

reason
false
ErrorReason
Payer not found
application/json
Response: 400 Bad Request
Bad request, e.g. an incorrectly formatted reference id was provided.


application/json
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default - json
 Copy
{
    "code": "PAYEE_NOT_FOUND",
    "message": "string"
}
Response: 404 Not Found
Resource not found.


application/json
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default - json
 Copy
{
    "code": "PAYEE_NOT_FOUND",
    "message": "string"
}
Unspecified internal error
Response: 500 Internal Server Error
Internal Error. Note that if the retrieved request to pay has failed, it will not cause this status to be returned. This status is only returned if the GET request itself fails.


Unspecified internal error
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
Definitions
Name
Description
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

PreApprovalResult
ErrorReason
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid




Name
Required
Type
Description
partyIdType
false
string
partyId
false
string
PreApprovalResult


Name
Required
Type
Description
payer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payerCurrency
false
string
ISO4217 Currency

payerMessage
false
string
The mesage that is shown to the approver.

status
false
string
expirationDateTime
false
integer
The expiry date +time of the preapproval, in YYYY-MM-DDTHH:mm:SS format

reason
false
ErrorReason
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string



GetUserInfoWithConsent
Try it 
This operation is used to claim a consent by the account holder for the requested scopes.

Request
https://sandbox.momodeveloper.mtn.com/collection/oauth2/v1_0/userinfo
Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Token. Replace with a valid oauth2 token received from oauth2 token endpoint in Wallet Platform.

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Response: 200 OK
OK


application/json
consentkycResponse


Name
Required
Type
Description
sub
false
string
Subject - Identifier for the End-User at the Issuer.

name
false
string
End-User's full name in displayable form including all name parts.

given_name
false
string
Given name(s) or first name(s) of the End-User.

family_name
false
string
Surname(s) or last name(s) of the End-User.

middle_name
false
string
Middle name(s) of the End-User.

email
false
string
End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] address specification syntax.

email_verified
false
boolean
The response value is True if the End-User's e-mail address has been verified;otherwise false.

gender
false
string
End-User's gender.

locale
false
string
Preffered language.

phone_number
false
string
End-User's preferred telephone number

phone_number_verified
false
boolean
The response value is True if the End-User's phone number has been verified; otherwise false.

address
false
string
User Address

updated_at
false
number
The time the End-User's information was last updated.

status
false
string
Account holder status.

birthdate
false
string
The birth date of the account holder.

credit_score
false
string
The credit score of the account holder.

active
false
boolean
The status of the account holder.

country_of_birth
false
string
Account holder country of birth.

region_of_birth
false
string
The birth region of the account holder.

city_of_birth
false
string
The city of birth for the account holder.

occupation
false
string
Occupation of the account holder.

employer_name
false
string
The name of the employer.

identification_type
false
string
Type of identification.The first non-expired identification is always chosen.

identification_value
false
string
The value of the identification.

default
default - json
 Copy
{
    "sub": "string",
    "name": "string",
    "given_name": "string",
    "family_name": "string",
    "middle_name": "string",
    "email": "string",
    "email_verified": true,
    "gender": "string",
    "locale": "string",
    "phone_number": "string",
    "phone_number_verified": true,
    "address": "string",
    "updated_at": 0,
    "status": "string",
    "birthdate": "string",
    "credit_score": "string",
    "active": true,
    "country_of_birth": "string",
    "region_of_birth": "string",
    "city_of_birth": "string",
    "occupation": "string",
    "employer_name": "string",
    "identification_type": "string",
    "identification_value": "string"
}
Definitions
Name
Description
consentkycResponse
consentkycResponse


Name
Required
Type
Description
sub
false
string
Subject - Identifier for the End-User at the Issuer.

name
false
string
End-User's full name in displayable form including all name parts.

given_name
false
string
Given name(s) or first name(s) of the End-User.

family_name
false
string
Surname(s) or last name(s) of the End-User.

middle_name
false
string
Middle name(s) of the End-User.

email
false
string
End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] address specification syntax.

email_verified
false
boolean
The response value is True if the End-User's e-mail address has been verified;otherwise false.

gender
false
string
End-User's gender.

locale
false
string
Preffered language.

phone_number
false
string
End-User's preferred telephone number

phone_number_verified
false
boolean
The response value is True if the End-User's phone number has been verified; otherwise false.

address
false
string
User Address

updated_at
false
number
The time the End-User's information was last updated.

status
false
string
Account holder status.

birthdate
false
string
The birth date of the account holder.

credit_score
false
string
The credit score of the account holder.

active
false
boolean
The status of the account holder.

country_of_birth
false
string
Account holder country of birth.

region_of_birth
false
string
The birth region of the account holder.

city_of_birth
false
string
The city of birth for the account holder.

occupation
false
string
Occupation of the account holder.

employer_name
false
string
The name of the employer.

identification_type
false
string
Type of identification.The first non-expired identification is always chosen.

identification_value
false
string
The value of the identification.

PreApproval
Try it 
Preapproval operation is used to create a pre-approval.

Request
https://sandbox.momodeveloper.mtn.com/collection/v2_0/preapproval
Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Callback-Url
false
string
PUT Callback URL to send callback to once the invoice is completed.

X-Reference-Id
true
string
Format - UUID. An id to uniquely identify the making of an invoice

X-Target-Environment
true
string
The desired target environment to use that is allowed for the API user.

Request body
application/json
PreApproval


Name
Required
Type
Description
payer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payerCurrency
false
string
ISO4217 Currency

payerMessage
false
string
The mesage that is shown to the approver.

validityTime
false
integer
The request validity time of the pre-approval

default
default - json
 Copy
{
    "payer": {
        "partyIdType": "MSISDN",
        "partyId": "string"
    },
    "payerCurrency": "string(The currency code of the sending account. Amount to be paid.)",
    "payerMessage": "string (Message to the end user.)",
    "validityTime": "integer (The time duration in seconds that the pre-approval is valid once it is accepted.)"
}
Response: 202 Accepted
Accepted


Response: 400 Bad Request
Bad request, e.g. invalid data was sent in the request.


application/json
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default - json
 Copy
{
    "code": "PAYEE_NOT_FOUND",
    "message": "string"
}
Response: 409 Conflict
Conflict, duplicated reference id


ReferenceId already in use
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
Unspecified internal error
Response: 500 Internal Server Error
Internal Error.


application/json
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default - json
 Copy
{
    "code": "PAYEE_NOT_FOUND",
    "message": "string"
}
Definitions
Name
Description
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

PreApproval
ErrorReason
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid




Name
Required
Type
Description
partyIdType
false
string
partyId
false
string
PreApproval


Name
Required
Type
Description
payer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payerCurrency
false
string
ISO4217 Currency

payerMessage
false
string
The mesage that is shown to the approver.

validityTime
false
integer
The request validity time of the pre-approval

ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string


RequesttoPay
Try it 
This operation is used to request a payment from a consumer (Payer). The payer will be asked to authorize the payment. The transaction will be executed once the payer has authorized the payment. The requesttopay will be in status PENDING until the transaction is authorized or declined by the payer or it is timed out by the system. Status of the transaction can be validated by using the GET /requesttopay/<resourceId>

Request
https://sandbox.momodeveloper.mtn.com/collection/v1_0/requesttopay
Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Callback-Url
false
string
URL to the server where the callback should be sent.

X-Reference-Id
true
string
Format - UUID. Recource ID of the created request to pay transaction. This ID is used, for example, validating the status of the request. ‘Universal Unique ID’ for the transaction generated using UUID version 4.

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Request body
application/json
RequestToPay


Name
Required
Type
Description
amount
false
string
Amount that will be debited from the payer account.

currency
false
string
ISO4217 Currency

externalId
false
string
External id is used as a reference to the transaction. External id is used for reconciliation. The external id will be included in transaction history report.
External id is not required to be unique.

payer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payerMessage
false
string
Message that will be written in the payer transaction history message field.

payeeNote
false
string
Message that will be written in the payee transaction history note field.

default
default - json
 Copy
{
    "amount": "string",
    "currency": "string",
    "externalId": "string",
    "payer": {
        "partyIdType": "MSISDN",
        "partyId": "string"
    },
    "payerMessage": "string",
    "payeeNote": "string"
}
Response: 202 Accepted
Accepted


Response: 400 Bad Request
Bad request, e.g. invalid data was sent in the request.


Response: 409 Conflict
Conflict, duplicated reference id


ReferenceId already in use
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
Unspecified internal error
Response: 500 Internal Server Error
Internal Error.


Unspecified internal error
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
ReferenceId already in use
Definitions
Name
Description
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

RequestToPay
ErrorReason
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid




Name
Required
Type
Description
partyIdType
false
string
partyId
false
string
RequestToPay


Name
Required
Type
Description
amount
false
string
Amount that will be debited from the payer account.

currency
false
string
ISO4217 Currency

externalId
false
string
External id is used as a reference to the transaction. External id is used for reconciliation. The external id will be included in transaction history report.
External id is not required to be unique.

payer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payerMessage
false
string
Message that will be written in the payer transaction history message field.

payeeNote
false
string
Message that will be written in the payee transaction history note field.

ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string


RequesttoPayDeliveryNotification
Try it 
This operation is used to send additional Notification to an End User.

Request
https://sandbox.momodeveloper.mtn.com/collection/v1_0/requesttopay/{referenceId}/deliverynotification
Request parameters
Name
In
Required
Type
Description
referenceId
template
true
string
UUID of transaction to get result. Reference id used when creating the RequesttoPay.

Request headers
Name
Required
Type
Description
notificationMessage
true
string
The message to send in the delivery notification. Max length 160.

Language
false
string
An ISO 639-1 or ISO 639-3 language code. The language is used to select the best matching notification template when sending the delivery notification to the end-user. A default value is used if not specified.

Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Request body
application/json
deliverynotification


Name
Required
Type
Description
notificationMessage
false
string
default
default - json
 Copy
{
    "notificationMessage": "string"
}
Response: 200 OK
OK. Notification successfully enqueued.


Response: 400 Bad Request
Bad request. Invalid data was sent in the request.


Response: 404 Not Found
Resource not found. The reference ID does not exist, or the calling user is not the owner of the financial transaction.


Response: 409 Conflict
Conflict. The transaction is not successfully completed.


Response: 410 Gone
Gone. The delivery notification opportunity has expired.


Response: 429 Too many requests
Too many requests. Too many attempts for the same ID has been made recently. This will only occur if a successful attempt has previously been performed.


Response: 500 Internal Server Error
Internal server error. An unexpected error occurred.


Definitions
Name
Description
deliverynotification
deliverynotification


Name
Required
Type
Description
notificationMessage
false
string


RequesttoPayTransactionStatus
Try it 
This operation is used to get the status of a request to pay. X-Reference-Id that was passed in the post is used as reference to the request.

Request
https://sandbox.momodeveloper.mtn.com/collection/v1_0/requesttopay/{referenceId}
Request parameters
Name
In
Required
Type
Description
referenceId
template
true
string
UUID of transaction to get result. Reference id used when creating the request to pay.

Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Response: 200 OK
OK. Note that a failed request to pay will be returned with this status too. The 'status' of the RequestToPayResult can be used to determine the outcome of the request. The 'reason' field can be used to retrieve a cause in case of failure.


Successful request to pay
RequestToPayResult


Name
Required
Type
Description
amount
false
string
Amount that will be debited from the payer account.

currency
false
string
ISO4217 Currency

financialTransactionId
false
string
Financial transactionIdd from mobile money manager.
Used to connect to the specific financial transaction made in the account

externalId
false
string
External id provided in the creation of the requestToPay transaction.

payer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payerMessage
false
string
Message that will be written in the payer transaction history message field.

payeeNote
false
string
Message that will be written in the payee transaction history note field.

status
false
string
reason
false
ErrorReason
default
default
 Copy
[object Object]
Payer not found
application/json
Request to pay not found
Unspecified internal error
Response: 400 Bad Request
Bad request, e.g. an incorrectly formatted reference id was provided.


Response: 404 Not Found
Resource not found.


Request to pay not found
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
Successful request to pay
Payer not found
application/json
Unspecified internal error
Response: 500 Internal Server Error
Internal Error. Note that if the retrieved request to pay has failed, it will not cause this status to be returned. This status is only returned if the GET request itself fails.


Unspecified internal error
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
Successful request to pay
Payer not found
application/json
Request to pay not found
Definitions
Name
Description
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

RequestToPayResult
ErrorReason
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid




Name
Required
Type
Description
partyIdType
false
string
partyId
false
string
RequestToPayResult


Name
Required
Type
Description
amount
false
string
Amount that will be debited from the payer account.

currency
false
string
ISO4217 Currency

financialTransactionId
false
string
Financial transactionIdd from mobile money manager.
Used to connect to the specific financial transaction made in the account

externalId
false
string
External id provided in the creation of the requestToPay transaction.

payer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payerMessage
false
string
Message that will be written in the payer transaction history message field.

payeeNote
false
string
Message that will be written in the payee transaction history note field.

status
false
string
reason
false
ErrorReason
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string

RequestToWithdrawTransactionStatus
Try it 
This operation is used to get the status of a request to withdraw. X-Reference-Id that was passed in the post is used as reference to the request.

Request
https://sandbox.momodeveloper.mtn.com/collection/v1_0/requesttowithdraw/{referenceId}
Request parameters
Name
In
Required
Type
Description
referenceId
template
true
string
UUID of transaction to get result. Reference id used when creating the RequestToWithdraw.

Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Response: 200 OK
OK. Note that a failed request to pay will be returned with this status too. The 'status' of the RequestToPayResult can be used to determine the outcome of the request. The 'reason' field can be used to retrieve a cause in case of failure.


Successful request to pay
RequestToPayResult


Name
Required
Type
Description
amount
false
string
Amount that will be debited from the payer account.

currency
false
string
ISO4217 Currency

financialTransactionId
false
string
Financial transactionIdd from mobile money manager.
Used to connect to the specific financial transaction made in the account

externalId
false
string
External id provided in the creation of the requestToPay transaction.

payer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payerMessage
false
string
Message that will be written in the payer transaction history message field.

payeeNote
false
string
Message that will be written in the payee transaction history note field.

status
false
string
reason
false
ErrorReason
default
default
 Copy
[object Object]
Payer not found
application/json
Request to pay not found
Unspecified internal error
Response: 400 Bad Request
Bad request, e.g. an incorrectly formatted reference id was provided.


Response: 404 Not Found
Resource not found.


Request to pay not found
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
Successful request to pay
Payer not found
application/json
Unspecified internal error
Response: 500 Internal Server Error
Internal Error. Note that if the retrieved request to pay has failed, it will not cause this status to be returned. This status is only returned if the GET request itself fails.


Unspecified internal error
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
Successful request to pay
Payer not found
application/json
Request to pay not found
Definitions
Name
Description
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

RequestToPayResult
ErrorReason
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid




Name
Required
Type
Description
partyIdType
false
string
partyId
false
string
RequestToPayResult


Name
Required
Type
Description
amount
false
string
Amount that will be debited from the payer account.

currency
false
string
ISO4217 Currency

financialTransactionId
false
string
Financial transactionIdd from mobile money manager.
Used to connect to the specific financial transaction made in the account

externalId
false
string
External id provided in the creation of the requestToPay transaction.

payer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payerMessage
false
string
Message that will be written in the payer transaction history message field.

payeeNote
false
string
Message that will be written in the payee transaction history note field.

status
false
string
reason
false
ErrorReason
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string


RequestToWithdraw-V1
Try it 
This operation is used to request a withdrawal (cash-out) from a consumer (Payer). The payer will be asked to authorize the withdrawal. The transaction will be executed once the payer has authorized the withdrawal

Request
https://sandbox.momodeveloper.mtn.com/collection/v1_0/requesttowithdraw
Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Callback-Url
false
string
POST Callback URL to the server where the callback should be sent.

X-Reference-Id
true
string
Format - UUID. Recource ID of the created request to pay transaction. This ID is used, for example, validating the status of the request. ‘Universal Unique ID’ for the transaction generated using UUID version 4.

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Request body
application/json
RequestToPay


Name
Required
Type
Description
amount
false
string
Amount that will be debited from the payer account.

currency
false
string
ISO4217 Currency

externalId
false
string
External id is used as a reference to the transaction. External id is used for reconciliation. The external id will be included in transaction history report.
External id is not required to be unique.

payer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payerMessage
false
string
Message that will be written in the payer transaction history message field.

payeeNote
false
string
Message that will be written in the payee transaction history note field.

default
default - json
 Copy
{
    "payeeNote": "string",
    "externalId": "string",
    "amount": "string",
    "currency": "string",
    "payer": {
        "partyIdType": "MSISDN",
        "partyId": "string"
    },
    "payerMessage": "string"
}
Response: 202 Accepted
Accepted


Response: 400 Bad Request
Bad request, e.g. invalid data was sent in the request.


Response: 409 Conflict
Conflict, duplicated reference id


ReferenceId already in use
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
Unspecified internal error
Response: 500 Internal Server Error
Internal Error.


Unspecified internal error
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
ReferenceId already in use
Definitions
Name
Description
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

RequestToPay
ErrorReason
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid




Name
Required
Type
Description
partyIdType
false
string
partyId
false
string
RequestToPay


Name
Required
Type
Description
amount
false
string
Amount that will be debited from the payer account.

currency
false
string
ISO4217 Currency

externalId
false
string
External id is used as a reference to the transaction. External id is used for reconciliation. The external id will be included in transaction history report.
External id is not required to be unique.

payer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payerMessage
false
string
Message that will be written in the payer transaction history message field.

payeeNote
false
string
Message that will be written in the payee transaction history note field.

ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string


RequestToWithdraw-V2
Try it 
This operation is used to request a withdrawal (cash-out) from a consumer (Payer). The payer will be asked to authorize the withdrawal. The transaction will be executed once the payer has authorized the withdrawal

Request
https://sandbox.momodeveloper.mtn.com/collection/v2_0/requesttowithdraw
Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Callback-Url
false
string
PUT Callback URL to the server where the callback should be sent.

X-Reference-Id
true
string
Format - UUID. Recource ID of the created request to pay transaction. This ID is used, for example, validating the status of the request. ‘Universal Unique ID’ for the transaction generated using UUID version 4.

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Request body
application/json
RequestToPay


Name
Required
Type
Description
amount
false
string
Amount that will be debited from the payer account.

currency
false
string
ISO4217 Currency

externalId
false
string
External id is used as a reference to the transaction. External id is used for reconciliation. The external id will be included in transaction history report.
External id is not required to be unique.

payer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payerMessage
false
string
Message that will be written in the payer transaction history message field.

payeeNote
false
string
Message that will be written in the payee transaction history note field.

default
default - json
 Copy
{
    "payeeNote": "string",
    "externalId": "string",
    "amount": "string",
    "currency": "string",
    "payer": {
        "partyIdType": "MSISDN",
        "partyId": "string"
    },
    "payerMessage": "string"
}
Response: 202 Accepted
Accepted


Response: 400 Bad Request
Bad request, e.g. invalid data was sent in the request.


Response: 409 Conflict
Conflict, duplicated reference id


ReferenceId already in use
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
Unspecified internal error
Response: 500 Internal Server Error
Internal Error.


Unspecified internal error
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
application/json
ReferenceId already in use
Definitions
Name
Description
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

RequestToPay
ErrorReason
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid




Name
Required
Type
Description
partyIdType
false
string
partyId
false
string
RequestToPay


Name
Required
Type
Description
amount
false
string
Amount that will be debited from the payer account.

currency
false
string
ISO4217 Currency

externalId
false
string
External id is used as a reference to the transaction. External id is used for reconciliation. The external id will be included in transaction history report.
External id is not required to be unique.

payer
false
Party
Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid

payerMessage
false
string
Message that will be written in the payer transaction history message field.

payeeNote
false
string
Message that will be written in the payee transaction history note field.

ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string

alidateAccountHolderStatus
Try it 
Operation is used to check if an account holder is registered and active in the system.

Request
https://sandbox.momodeveloper.mtn.com/collection/v1_0/accountholder/{accountHolderIdType}/{accountHolderId}/active
Request parameters
Name
In
Required
Type
Description
accountHolderId
template
true
string
The AccountHolder number. Validated according to the AccountHolder ID type (case Sensitive).
msisdn - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
email - Validated to be a valid e-mail format. Validated with IsEmail

accountHolderIdType
template
true
string
Specifies the type of the AccountHolder ID. Allowed values [msisdn, email].
accountHolderId should explicitly be in small letters.

Request headers
Name
Required
Type
Description
Authorization
true
string
Bearer Authentication Token generated using CreateAccessToken API Call

X-Target-Environment
true
string
The identifier of the Wallet Platform system where the transaction shall be processed. This parameter is used to route the request to the Wallet Platform system that will initiate the transaction.

Response: 200 OK
Ok. True if account holder is registered and active, false if the account holder is not active or not found


Response: 400 Bad Request
Bad request, e.g. invalid data was sent in the request.


Response: 500 Internal Server Error
Internal error. The returned response contains details.


Incorrect target environment
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string
default
default
 Copy
[object Object]
Definitions
Name
Description
ErrorReason
ErrorReason


Name
Required
Type
Description
code
false
string
message
false
string


Error Codes
MoMo OpenAPI Team is thrilled to announce that we've been listening to your feedback, and as a result, we've made significant updates to improve the failure handling with MoMoOpenAPI experience for developers, businesses, and customers.

Improved Failure Reasons and Error Codes

In our ongoing effort to provide a seamless and intuitive experience, we've revamped our failure reasons and error codes. These updates ensure that error messages are clearer, more concise, and provide actionable insights. This enhancement enables developers and businesses to quickly identify and resolve issues, reducing friction and improving overall efficiency.

Benefits for all

These updates bring numerous benefits to the MoMoOpenAPI ecosystem, including:

Enhanced Customer Experience: Improved failure reasons and new actions lead to better, more seamless customer experiences.

Increased Efficiency: Developers and businesses can now manage MoMo customer experiences more efficiently, reducing time and resources spent on issue resolution.

Reduced Friction: Updated error codes and messages reduce friction, making it easier to resolve issues and get back to business as usual.

Common Error Codes

Error	Description	Action
NOT ENOUGH_FUNDS	The payer does not have enough funds.	Notify the payer of the total amount with fees before initiating debit, and also to ensure availability of the MoMo funds
PAYER_NOT_FOUND	Payer does not exist	Before initiating debit, use the Get accountholder Status to confirm the payer has an active MoMo Wallet
TRANSACTION_NOT_FOUND	The transaction could not be found	The transaction could not be found
PAYEE_NOT_ALLOWED_TO_RECEIVE	The payee is unable to receive funds.	The payee is unable to receive funds, due to a non active wallet status. If encountered request customer for an alternative MoMo number.
SENDER_ACCOUNT_NOT_ACTIVE	SENDER ACCOUNT NOT ACTIVE	The MoMo wallet used for the transfer has not been activated. Please contact your account manager in your respective country to activate the wallet for transactions
COULD_NOT_PERFORM_TRANSACTION	Transaction Not Completed	Debit transactions have a 5-minute approval window. If the transaction times out, please retry the transaction to complete the debit
PAYER_LIMIT_REACHED	The payer's limit has been breached.	Customer's wallet has reached its set limits for debits, which vary by country. To resolve this, the customer must either reduce the debit amount or use another MoMo wallet
PAYEE LIMIT_REACHED	The payee's limit has been breached.	Customer's wallet has reached its set limits for transfers, which vary by country. To resolve this, the customer must either reduce the transfer amount or share another MoMo wallet
RESOURCE_ALREADY_EXIST	Duplicated reference id. Creation of resource failed.	Error implies that the X-Reference-Id header in your financial API POST request is duplicated

To resolve this issue, you need to ensure that each financial API POST request has a unique X-Reference-Id header in UUID Version 4 format.
PAYEE_NOT_FOUND	Payee does not active	Error generated for Debit requests when the business account is blocked
VALIDATION_ERROR	Request failing Validation	Validation failures can occur due to incorrect data types, unsupported decimals, empty fields, incorrect field lengths, unsupported currencies, and invalid payer messages or notes (which cannot be null and must be within 128 characters).