MMP Integration Guide
Version: 1.0.0
Release Date: Nov 15th, 2024
1. Introduction 3
1.1. Purpose of Document 3
2. Getting Started 3
2.1. API Response Status Codes 3
2.2. HTTP APIs 4
2.2.1. Login 4
2.2.2. Deposit Amount 5
2.2.3. Get Receiver User Information 6
2.2.4. Get Transaction Status 6
1. Introduction
1.1. Purpose of Document
The purpose of this document is to provide API documentation as well as insight on how to
integrate with the SafariOne Mobile Money Platform.
2. Getting Started
To consume the MMP APIs you will need to have a session with the API Server. To obtain the
Auth Token, you can call the Login API with the provided credentials. On successful Login, you
will receive the token in the response body. This token will be sent inside the Authorization
HTTP header as a Bearer token.
You can send it like this:
Authorization: ‘Bearer {auth-token}’
2.1. API Response Status Codes
API responses currently return with the following HTTP status codes.
1- 200 OK
2- 400 Bad Request
3- 401 Unauthorized
4- 500 Internal Server Error
Furthermore, the response body also includes some result codes. These response
codes are as follows:
SUCCESS : 2001,
FAILURE : 8777,
TIMEOUT : 1002,
ERR_INVALID_FORMAT: 5983,
ERR_SERVICE_NOT_FOUND: 6050,
CHANNEL_NOT_ALLOWED:6018,
INVALID_CREDENTIALS: 6021
There are many such result codes each providing context on the error that was encountered.
We recommend that you use the HTTP status code in your HTTP client to determine success or
failure. When contacting support to resolve an error, you may communicate the resultCode that
is being returned.
2.2. HTTP APIs
2.2.1. Login
Description:
Login with the provided credentials to obtain the auth token
POST - /apiv1/partners/auth
Request Format:
Headers:
authorization: ZHN0djpQQGtpc3RhbjE= //Base64Encode(username:password)
apisecret: 1234567890 //your api secret key
timestamp: 172812389 // the current time as epoch value
requestId: 123123 //unique for each request,we recommend using UUIDv4
Body: null
200 Response Format:
Body:
{
"responseAttributes": {
"resultCode": 2001,
"replyMessage": "Success",
"token": "API_ff8020c7fe2c115e09d4",
"tokenExpiry": 1900 //expiry time in seconds
}
}
Note: The Authorization header must have the username and password concatenated with a ‘ : ’
And then base64encoded
Base64Encode(‘{username}:{password}’)
2.2.2. Deposit Amount
Description:
Disburse some amount into a receiver’s Wallet
POST - /apiv1/partners/disbursement/deposit
Request Format:
Headers:
authorization: Bearer {auth-token}
timestamp: 172812389 // the current time as epoch value
requestId: 123123 //unique for each request,we recommend using UUIDv4
content-type: application/json
Body:
{
"requestAttributes": {
"externalTransactionId": 90283,//unique
"amount": 1,
"currency": "USD", //ISO-4217 standard name
"sender": {
"msisdn": "0900 78601",
"name": "John Doe"
},
"receiver": {
"msisdn": "252615100002",
"name": "Neil Armstrong" // this is optional
}
}
}
200 Response Format:
Body:
{
"responseAttributes": {
"resultCode": 2001,
"replyMessage": "-> Transfer-Id: 1731665312074001, You have
successfully transferred $1.00 to Muhammad Barre (252615100002) at
15/11/24 15:08:32",
"transactionDetails": {
"transferId": "1731665312074001",
"transactionDate": "15/11/24 15:08:32",
"statusDescription": "SUCCESSFULL",
"transactionStatus": "Completed"
}
}
}
2.2.3. Get Receiver User Information
Description:
Get the Receiver’s information such as name and active status
GET - /apiv1/partners/user-info?msisdn={receiver-msisdn}
Request Format:
Headers:
authorization: Bearer {auth-token}
timestamp: 172812389 // the current time as epoch value
requestId: 123123 //unique for each request,we recommend using UUIDv4
200 Response Format:
Body:
{
"responseAttributes": {
"userInfo": {
"name": "John Doe",
"isActive": true
},
"resultCode": 2001,
"replyMessage": "Data fetched successfully"
}
}
2.2.4. Get Transaction Status
Description:
Query the status of a transaction using the externalTransactionId that was provided on the initial
deposit request
GET - apiv1/partners/disbursement/transfer?externalTransactionId={transaction-id}
Request Format:
Headers:
authorization: Bearer {auth-token}
timestamp: 172812389 // the current time as epoch value
requestId: 123123 //unique for each request,we recommend using UUIDv4
200 Response Format:
Body:
{
"responseAttributes": {
"transactionDetails": {
"transferId": "1731665312074001",
"transactionDate": "15/11/24 15:08:32",
"transactionStatus": "Completed",
"statusDescription": "SUCCESSFULL"
},
"resultCode": 2001,
"replyMessage": "Data fetched successfully"
}
}
