Authentication
1. What credentials do I need once I have subscribed to a product?
- Subscription Key – received upon subscription to a product. It is used for authenticating the number of API calls. For information about subscription keys, refer to point 2
- API User and API Key for bearer Oauth 2.0 token. In the sandbox they are self-generated from the APIs. In production these are generated from the partner portal (part of onboarding)
2. What is a subscription Key?
- This Key is used to authenticate and limit the number of calls that can be made
- The subscription key is assigned to the Ocp-Apim-Subscription-Key parameter of the header
- The Subscription Key can be found in your user profile
- Developers – can use either the Primary Key or Secondary Key for every product they subscribe to allow access to the API
- A developer cannot access or utilize any of the respective APIs without a Subscription Key
- Different subscription keys can be used for different product APIs; please check in your user profile
3. What is the API User and API Key for Oauth 2.0?
- The API User and API Key are used together with your subscription key to grant access to the -wallet system and is applicable to a specific country
- The API User and API Key are generated using respective APIs in the sandbox
- API user and Key are wholly managed by the merchant through Partner Portal for PRODUCTION setups
- Merchants can generate/revoke/refresh API Keys through the Partner Portal
- For Sandbox API User and Key is generated using an API
4. How do I generate an Oauth 2.0 token?
- You require an API User and API Key in format APIUSER: APIKey e16510xx-7282-4a39-xx8b-da054889a33a:xx1894d23a8d4xxdadaf62f39dae99xx
- Convert the concatenation of APIUser: APIKey into Base64 format
- Use the Base64 format to generate the authorization token, the result will look similar to this string ZTE2NTEwY2xtNzI4Mi00YTx5LTg5OGItZGEwNTQ4ODlhMzNhOjg1MTg5NGQyM2E4ZDQxMW RhZGFmNxJmMzlkYWU5OcY4
5. How do I create, provision and manage the API user and API key?
- Please review Sandbox provisioning process under API Sandbox
- The API User and API Key are used to grant access to the wallet system applicable to a specific country
- API user and Key are wholly managed by the merchant through Partner Portal in production
- Developers can generate or revoke API Keys through the Partner Portal in production
6. How do I generate a UUID for my transactions?
- This ID is used, for example, validating the status of the request. ‘Universal Unique ID’ for the transaction generated using UUID version 4
- Example of Version 4 UUID: - ca58fd96-2478-4624-b663-bdacd5f914ca
Callback
7. I am not getting any callbacks. How do I verify or configure my callback URL?
Check that you have
- Registered a ProviderCallbackHost when creating your API User
- You have specified a callback URL in the Request
- The Callback URL MUST belong to the same domain as the ProvideCallbackHost. Subdomains are not allowed.
Example:
- If you have specified your ProviderCallbackHost as mycallback.com then the callback URL shall be specified as https://mycallback.com/
- Using https://subdomain.mycallback.com/ as callback URL will not work
- Callbacks in the sandbox are set by setting the callback host when creating an API user, if my callback URL for traffic is https://testsite.test.com:1313/api/callback, the callback host is testsite.test.com and the callback host is what is set with the user, but the call back URL is used in every request where a callback is expected
- In the production environment, the callback is set in the merchant portal and instructions are sent as part of the onboarding documentation
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
b) 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
Error Code
Transfer is used for transferring money from the provider account to a customer.
8. What are the common error codes you may expect?
- The error codes are categorized as follows (Common Error Codes, Preapproval Error Codes, RequestToPay Error Codes, Transfer Error Codes and Validate Account Holder Error Codes)
- The API User and API Key are used to grant access to the wallet system applicable to a specific country
- More information on error codes can be found under the documentation section
Support
9. How do I get support and join the developer community?
- Select the “contact support” button
- Select a country from the drop-down list
- Choose WhatsApp and join the developer group – start chatting
- Or connect via Skype
On-Boarding
10. What steps do I need to follow go live?
- Select the “Go-Live” option on portal
- Select Operating country from predefined list to take products Live in that Operating country
- Choose a Package and Product set
- Provide KYC Information for business owner and business details
- Download, complete and submit KYC documents as well as signed contract
- Submit documents through the Sandbox Portal for Vetting and Approval
- Access to the partner portal granted for you to create the API User and API Key