crukundo/Step 1: Create API User.MD

Forked from chaiwa-berian/Step 1: Create API User.MD

Created August 21, 2021 20:44

Star () You must be signed in to star a gist
Fork () You must be signed in to fork a gist

Learn more about clone URLs
Clone this repository at <script src="https://gist.github.com/crukundo/f9ec0f4426daedd46420bbad7b2da50d.js"></script>
Save crukundo/f9ec0f4426daedd46420bbad7b2da50d to your computer and use it in GitHub Desktop.

Download ZIP

Testing MTN MoMo Collection API in Sandbox using Postman

Raw

Step 1: Create API User.MD

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

Raw

Step 2: Create API Key.MD

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.

Raw

Step 3: Create Bearer Token.MD

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

Raw

Step 4: Request to Pay.MD

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:

Currency should be EUR, otherwise it will fail. Check MTN Documentation here: https://momodeveloper.mtn.com/api-documentation/testing/
External Id can be anything but CANNOT contain SPACES
PartyId, put any number or choose from the list of test numbers on MTN Documentation( https://momodeveloper.mtn.com/api-documentation/testing/) if you are interested in checking different response types

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

Raw

Step 5: Get Status For RequestToPay Transaction.MD

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/

Raw

Step 6: Bonus Notes.MD

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