Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Save crukundo/f9ec0f4426daedd46420bbad7b2da50d to your computer and use it in GitHub Desktop.
Save crukundo/f9ec0f4426daedd46420bbad7b2da50d to your computer and use it in GitHub Desktop.
Testing MTN MoMo Collection API in Sandbox using Postman

A. Checklist

  • To create an API User, you need the following things in place: X-Reference-Id and Ocp-Apim-Subscription-Key

1. X-Reference-Id

  • This is used as User ID since the Sandbox is a Mock Environment so we kinda create our own ids and send them over to the sandbox so it can uniquely identify the user
  • Get the value for this here: https://www.uuidgenerator.net/api/version4
  • Remember to keep this safely as we will use it when configuring our POST request
  • Lets say you have your X-Reference-Id as: 9f92971b-cd2e-4feb-9053-0b14d53ac4f5

2. Ocp-Apim-Subscription-Key

  • Get this from the Primary or Secondary Key of your Collections | Enable remote collection of bills, fees or taxes subscription.
  • You can find this on your profile page here: https://momodeveloper.mtn.com/developer
  • Lets assume your Primary or Secondary Key for your subscription is : b44728c249c24d8bb11d8b8592f4f5a7

B. Configure Postman

1. URL

  • POST https://sandbox.momodeveloper.mtn.com/v1_0/apiuser

2. Params

  • DO NOT PUT ANYTHING HERE

3. Authorization

  • Select "No Auth" as Type

4. Headers

  • Leave the defaults as they are and ONLY add the below headers:
  X-Reference-Id: 9f92971b-cd2e-4feb-9053-0b14d53ac4f5
  Ocp-Apim-Subscription-Key: b44728c249c24d8bb11d8b8592f4f5a7

4. Body

  • The callback is only relevant when you go live, so for now just put any callback hook
  • Put the below json object in the body of the request:
{
  "providerCallbackHost": "https://webhook.site/de55348f-c6e2-4518-bc48-1661f1efeec9"
}

C. Send the Request

  • If all went well, you should get the response with "Status: 201 Created"
  • You will not see any other additional content in the response body, just that message is good enough!
  • So this means you have created an API User with an ID: 9f92971b-cd2e-4feb-9053-0b14d53ac4f5 (this is the same id you supplied, nothing special about it)
  • Take note of this ID as it will be used to create the API Key in step 2 and API Bearer Token in step 3

A. Checklist

  • To create an API Key, you need the following things in place: X-Reference-Id and Ocp-Apim-Subscription-Key

1. X-Reference-Id

  • Use the same X-Reference-Id as the one used in Step 1: Create API User
  • In our example we used 9f92971b-cd2e-4feb-9053-0b14d53ac4f5 so we will use this same value here too!
  • Remember, this is treated as User ID

2. Ocp-Apim-Subscription-Key

  • Use the same Primary or Secondary Subscription Key you used during Step 1: Create API User
  • In our example we used b44728c249c24d8bb11d8b8592f4f5a7 so we will use this same value here too!

B. Configure Postman

1. URL

  • The URL will contain the User ID(same as X-Reference-id) as shown below
  • POST https://sandbox.momodeveloper.mtn.com/v1_0/apiuser/9f92971b-cd2e-4feb-9053-0b14d53ac4f5/apikey

2. Params

  • DO NOT PUT ANYTHING HERE

3. Authorization

  • Select "No Auth" as Type

4. Headers

  • Leave the defaults as they are and ONLY add the below header:
    Ocp-Apim-Subscription-Key: b44728c249c24d8bb11d8b8592f4f5a7
    

5. Body

  • LEAVE THE BODY UNTOUCHED! LIKE REALLY BLANK!!!

C. Send the Request

  • If all went well, you should get the response with "Status: 201 Created"
  • You will also see additional content in the response body, as shown below:
{
    "apiKey": "1e89774dabd944b4b112c30aaef5b9c8"
}
  • So this means you have created an API Key with value: 1e89774dabd944b4b112c30aaef5b9c8
  • Take note of this API Key value(1e89774dabd944b4b112c30aaef5b9c8) as it will be used as PASSWORD, while the User ID/X-Reference-Id(9f92971b-cd2e-4feb-9053-0b14d53ac4f5) will be used as USERNAME when creating the Bearer Token in Step 3.

A. Checklist

  • To create a Bearer Token, you need the following things in place: X-Reference-Id, Ocp-Apim-Subscription-Key and the API Key

1. User ID(X-Reference-Id)

  • Use the same X-Reference-Id as the one used in Step 1: Create API User
  • In our example we used 9f92971b-cd2e-4feb-9053-0b14d53ac4f5 so we will use this same value here too!
  • Remember, this is treated as User ID

2. Ocp-Apim-Subscription-Key

  • Use the same Primary or Secondary Subscription Key you used during Step 1: Create API User
  • In our example we used b44728c249c24d8bb11d8b8592f4f5a7 so we will use this same value here too!

3. API Key

  • Use the API Key created in Step 2: Create API Key
  • In our example, the API Key is : 1e89774dabd944b4b112c30aaef5b9c8

B. Configure Postman

1. URL

  • POST https://sandbox.momodeveloper.mtn.com/collection/token/

2. Params

  • DO NOT PUT ANYTHING HERE

3. Authorization

  • Select "Basic Auth" as Type
  • In the Username field, put the X-Reference-id(User ID). In our example, it should be Username: 9f92971b-cd2e-4feb-9053-0b14d53ac4f5
  • In the Password field, put the API Key(generated in Step 2). In our example, it should be Password: 1e89774dabd944b4b112c30aaef5b9c8

4. Headers

  • Leave the defaults as they are and ONLY add the below headers:
  Ocp-Apim-Subscription-Key: b44728c249c24d8bb11d8b8592f4f5a7
  X-Target-Environment: sandbox

5. Body

  • LEAVE THE BODY UNTOUCHED! LIKE REALLY BLANK!!!

C. Send the Request

  • If all went well, you should get the response with "Status: 201 Created"
  • You will also see additional content in the response body, like shown below:
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSMjU2In0.eyJjbGllbnRJZCI6ImM0ZjZkMzNkLWVhNzYtNDYwOS1iODE2LWE5OWRjODAxYjUzMiIsImV4cGlyZXMiOiIyMDIwLTA2LTA5VDIwOjMyOjQyLjIwMSIsInNlc3Npb25JZCI6IjZkYjg0MjIxLWM4ZWQtNGZhZC1hMDM5LWYzZDY3YzNjMzMwMiJ9.FUhqzW_HhXlOIsYu3YQMWsfpBujSktAldnnh70De8uKuuPGGlgIEmIrakQ91klV8rNeD2g_tq9nOR748j8O-vp5oNKDmmt5ANo2qUoYZTaiwSthev6DQ2TLvxr45w4QCX0YmPTDtkue_9R7ZpnEhud51XlKfEOEMAZhdWoVDvL08xrwrL-yP2yfLGRZVtZfpaqrx7CxgUO3MT_zXy8QuvHAvlwlgxIvkZhILdTbycyZHAtvRCeoMJ0G7REsQQYHfNNm87aXg9vwcjDu-YZGVaA27jHP2z-l4gbeg-sluoqafcQ8YwqPZ4nGcAMoMCTU6wtUICDMNw-qWpZwlHEixaw",
    "token_type": "access_token",
    "expires_in": 3600
}
  • So this means you have created a Bearer Token(Access Token) with value: eyJ0eXAiOiJKV1QiLCJhbGciOiJSMjU2In0.eyJjbGllbnRJZCI6ImM0ZjZkMzNkLWVhNzYtNDYwOS1iODE2LWE5OWRjODAxYjUzMiIsImV4cGlyZXMiOiIyMDIwLTA2LTA5VDIwOjMyOjQyLjIwMSIsInNlc3Npb25JZCI6IjZkYjg0MjIxLWM4ZWQtNGZhZC1hMDM5LWYzZDY3YzNjMzMwMiJ9.FUhqzW_HhXlOIsYu3YQMWsfpBujSktAldnnh70De8uKuuPGGlgIEmIrakQ91klV8rNeD2g_tq9nOR748j8O-vp5oNKDmmt5ANo2qUoYZTaiwSthev6DQ2TLvxr45w4QCX0YmPTDtkue_9R7ZpnEhud51XlKfEOEMAZhdWoVDvL08xrwrL-yP2yfLGRZVtZfpaqrx7CxgUO3MT_zXy8QuvHAvlwlgxIvkZhILdTbycyZHAtvRCeoMJ0G7REsQQYHfNNm87aXg9vwcjDu-YZGVaA27jHP2z-l4gbeg-sluoqafcQ8YwqPZ4nGcAMoMCTU6wtUICDMNw-qWpZwlHEixaw
  • Take note that this token expires in 1 hour. So it means you will need to send this request every after 1 hour to get a fresh token, if you have to continue testing api calls on the rest of the endpoints.
  • Take note of this value as it will be used in subsequent api calls in Step 4 and Step 5

A. Checklist

  • To successfully send this POST RequestToPay request, you need the following things in place: X-Reference-Id, Ocp-Apim-Subscription-Key, X-Target-Environment and the Bearer Token

1. X-Reference-Id(Transaction ID)

  • Note that the X-Reference-id used here should not be the same as one used in Step 1 to 3.
  • The X-Reference-Id used here represents the Transaction ID for our request to pay, in the Mock Environment(Sandbox)
  • So we will need to GENERATE a NEW ID for this transaction
  • Get the new value for this here: https://www.uuidgenerator.net/api/version4
  • In our example we will use b988a090-bbeb-46af-806c-db7fd8aeca7e
  • Remember, this is treated as Transaction ID

2. Ocp-Apim-Subscription-Key

  • Get the Primary or Secondary Subscription Key of the Collections Subscription from your Profile
  • In our example we used b44728c249c24d8bb11d8b8592f4f5a7 so we will use this same value here too!

3. X-Target-Environment

-Put the value as "sandbox"

4. Bearer Token

  • Use the Bearer Token we created in Step 3: Create Bearer Token
  • In our example, the Bearer Token is : eyJ0eXAiOiJKV1QiLCJhbGciOiJSMjU2In0.eyJjbGllbnRJZCI6ImM0ZjZkMzNkLWVhNzYtNDYwOS1iODE2LWE5OWRjODAxYjUzMiIsImV4cGlyZXMiOiIyMDIwLTA2LTA5VDIwOjMyOjQyLjIwMSIsInNlc3Npb25JZCI6IjZkYjg0MjIxLWM4ZWQtNGZhZC1hMDM5LWYzZDY3YzNjMzMwMiJ9.FUhqzW_HhXlOIsYu3YQMWsfpBujSktAldnnh70De8uKuuPGGlgIEmIrakQ91klV8rNeD2g_tq9nOR748j8O-vp5oNKDmmt5ANo2qUoYZTaiwSthev6DQ2TLvxr45w4QCX0YmPTDtkue_9R7ZpnEhud51XlKfEOEMAZhdWoVDvL08xrwrL-yP2yfLGRZVtZfpaqrx7CxgUO3MT_zXy8QuvHAvlwlgxIvkZhILdTbycyZHAtvRCeoMJ0G7REsQQYHfNNm87aXg9vwcjDu-YZGVaA27jHP2z-l4gbeg-sluoqafcQ8YwqPZ4nGcAMoMCTU6wtUICDMNw-qWpZwlHEixaw

B. Configure Postman

1. URL

  • POST https://sandbox.momodeveloper.mtn.com/collection/v1_0/requesttopay

2. Params

  • DO NOT PUT ANYTHING HERE

3. Authorization

  • Select "Bearer Token" as Type
  • In the Token field, put the Bearer Token created in Step 3
  • In our example, configuration for this should look like below:
  Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJSMjU2In0.eyJjbGllbnRJZCI6ImM0ZjZkMzNkLWVhNzYtNDYwOS1iODE2LWE5OWRjODAxYjUzMiIsImV4cGlyZXMiOiIyMDIwLTA2LTA5VDIwOjMyOjQyLjIwMSIsInNlc3Npb25JZCI6IjZkYjg0MjIxLWM4ZWQtNGZhZC1hMDM5LWYzZDY3YzNjMzMwMiJ9.FUhqzW_HhXlOIsYu3YQMWsfpBujSktAldnnh70De8uKuuPGGlgIEmIrakQ91klV8rNeD2g_tq9nOR748j8O-vp5oNKDmmt5ANo2qUoYZTaiwSthev6DQ2TLvxr45w4QCX0YmPTDtkue_9R7ZpnEhud51XlKfEOEMAZhdWoVDvL08xrwrL-yP2yfLGRZVtZfpaqrx7CxgUO3MT_zXy8QuvHAvlwlgxIvkZhILdTbycyZHAtvRCeoMJ0G7REsQQYHfNNm87aXg9vwcjDu-YZGVaA27jHP2z-l4gbeg-sluoqafcQ8YwqPZ4nGcAMoMCTU6wtUICDMNw-qWpZwlHEixaw

4. Headers

  • Leave the defaults as they are and ONLY add the below headers:
  Ocp-Apim-Subscription-Key: b44728c249c24d8bb11d8b8592f4f5a7
  X-Target-Environment: sandbox
  X-Reference-Id: b988a090-bbeb-46af-806c-db7fd8aeca7e

5. Body

  • Configure the Body as below:
{
  "amount": "900.0",
  "currency": "EUR",
  "externalId": "097411065",
  "payer": {
    "partyIdType": "MSISDN",
    "partyId": "260962217114"
  },
  "payerMessage": "Sure thing!",
  "payeeNote": "Payback my money bro!"
}

NOTE:

C. Send the Request

  • If all went well, you should get the response with "Status: 202 Accepted"
  • You will not see additional content in the response body
  • So this means you have created a RequestToPay Transaction with transaction ID: b988a090-bbeb-46af-806c-db7fd8aeca7e
  • Take note of this Transaction ID as it will be used as ReferenceID in the get status request for this transaction in step 5

A. Checklist

  • To successfully send this GET RequestToPay request, you need the following things in place: X-Reference-Id, Ocp-Apim-Subscription-Key, X-Target-Environment and the Bearer Token

1. X-Reference-Id(Transaction ID)

  • Use the X-Reference-id used in step 4 when creating the RequestToPay Trasaction
  • In our example we used b988a090-bbeb-46af-806c-db7fd8aeca7e so we will use the same id here too!
  • Remember, this is treated as Transaction ID

2. Ocp-Apim-Subscription-Key

  • Use the same Primary or Secondary Subscription Key you used during Step 1: Create API User
  • In our example we used b44728c249c24d8bb11d8b8592f4f5a7 so we will use this same value here too!

3. X-Target-Environment

  • Put the value as "sandbox"

4. Bearer Token

  • Use the Bearer Token we created in Step 3: Create Bearer Token
  • In our example, the Bearer Token is : eyJ0eXAiOiJKV1QiLCJhbGciOiJSMjU2In0.eyJjbGllbnRJZCI6ImM0ZjZkMzNkLWVhNzYtNDYwOS1iODE2LWE5OWRjODAxYjUzMiIsImV4cGlyZXMiOiIyMDIwLTA2LTA5VDIwOjMyOjQyLjIwMSIsInNlc3Npb25JZCI6IjZkYjg0MjIxLWM4ZWQtNGZhZC1hMDM5LWYzZDY3YzNjMzMwMiJ9.FUhqzW_HhXlOIsYu3YQMWsfpBujSktAldnnh70De8uKuuPGGlgIEmIrakQ91klV8rNeD2g_tq9nOR748j8O-vp5oNKDmmt5ANo2qUoYZTaiwSthev6DQ2TLvxr45w4QCX0YmPTDtkue_9R7ZpnEhud51XlKfEOEMAZhdWoVDvL08xrwrL-yP2yfLGRZVtZfpaqrx7CxgUO3MT_zXy8QuvHAvlwlgxIvkZhILdTbycyZHAtvRCeoMJ0G7REsQQYHfNNm87aXg9vwcjDu-YZGVaA27jHP2z-l4gbeg-sluoqafcQ8YwqPZ4nGcAMoMCTU6wtUICDMNw-qWpZwlHEixaw

B. Configure Postman

1. URL

  • GET https://sandbox.momodeveloper.mtn.com/collection/v1_0/requesttopay/b988a090-bbeb-46af-806c-db7fd8aeca7e

2. Params

  • DO NOT PUT ANYTHING HERE

3. Authorization

  • Select "Bearer Token" as Type
  • In the Token field, put the Bearer Token created in Step 3
  • In our example, configuration for this should look like below:
  Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJSMjU2In0.eyJjbGllbnRJZCI6ImM0ZjZkMzNkLWVhNzYtNDYwOS1iODE2LWE5OWRjODAxYjUzMiIsImV4cGlyZXMiOiIyMDIwLTA2LTA5VDIwOjMyOjQyLjIwMSIsInNlc3Npb25JZCI6IjZkYjg0MjIxLWM4ZWQtNGZhZC1hMDM5LWYzZDY3YzNjMzMwMiJ9.FUhqzW_HhXlOIsYu3YQMWsfpBujSktAldnnh70De8uKuuPGGlgIEmIrakQ91klV8rNeD2g_tq9nOR748j8O-vp5oNKDmmt5ANo2qUoYZTaiwSthev6DQ2TLvxr45w4QCX0YmPTDtkue_9R7ZpnEhud51XlKfEOEMAZhdWoVDvL08xrwrL-yP2yfLGRZVtZfpaqrx7CxgUO3MT_zXy8QuvHAvlwlgxIvkZhILdTbycyZHAtvRCeoMJ0G7REsQQYHfNNm87aXg9vwcjDu-YZGVaA27jHP2z-l4gbeg-sluoqafcQ8YwqPZ4nGcAMoMCTU6wtUICDMNw-qWpZwlHEixaw

4. Headers

  • Leave the defaults as they are and ONLY add the below headers:
  Ocp-Apim-Subscription-Key: b44728c249c24d8bb11d8b8592f4f5a7
  X-Target-Environment: sandbox
  X-Reference-Id: b988a090-bbeb-46af-806c-db7fd8aeca7e

5. Body

  • LEAVE THE BODY UNTOUCHED! LIKE REALLY BLANK!!!

C. Send the Request

  • If all went well, you should get the response with "Status: 200 OK"
  • You will also see additional content in the response body, like shown below:
{
    "financialTransactionId": "1432942836",
    "externalId": "097411065",
    "amount": "900.0",
    "currency": "EUR",
    "payer": {
        "partyIdType": "MSISDN",
        "partyId": "260962217114"
    },
    "payerMessage": "Sure thing!",
    "payeeNote": "Payback my money bro",
    "status": "SUCCESSFUL"
}
  • So this means your RequestToPay Transaction was approved by the Payer

NOTE: -If the phone number used as PartyId, during the POST requesttopay, is any number other than the ones from the list of test numbers on MTN Documentation( https://momodeveloper.mtn.com/api-documentation/testing/), then the response returned will ALWAYS be SUCCESSFUL! If you want to see a response with Status: PENDING or FAILED, then you need to use a test number from MTN's MoMo Documentation Website: https://momodeveloper.mtn.com/api-documentation/testing/

Notes

  • You are expected to have, at least, one Product Subscription before attempting to provision an API User
  • Once you provision an API User(in the Sandbox) and the API Key, the two can then be used to create a Bearer Token(Access Token)
  • The Bearer Token can then be used to make api calls for any of the Product Subscriptions. It will be sent as part of the Authorization Header of every api call.
  • Note that each Bearer Token issued has an expiry, usually 3600 seconds
  • So renew the Token when it expires by simply running the POST https://sandbox.momodeveloper.mtn.com/collection/token/ request again, passing it the same API User ID and API Key
  • The value for Ocp-Apim-Subscription-Key header will ALWAYS be the SAME for ALL Endpoints in a given Product Subscription
  • The value for X-Reference-Id header should ALWAYS be UNIQUE/DIFFERENT for each POST Request where the X-Reference-Id is expected to be in the header
  • Whenever the X-Reference-Id is expected to be passed as a Request Parameter (either in a POST or GET request), use an existing X-Reference-Id corresponding to the referenced resource
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment