Introduction Last updated: 17-02-2023

This document is intended to provide a guide for third parties who want to use the Orchard platform for various transactional services.

Overview

This document is intended to provide a guide for third parties who want to use the Airtel Mobile Money platform for various transactional services.

Prerequisite

Any external service provider who needs access to the Airtel Mobile Money Platform must first of all complete all necessary merchant registration procedures required by Airtel. Upon successful registration as a Merchant, the following are provided to the third party:

  1. Merchant subscriber number
  2. Merchant Nickname
In addition
  1. SLA between appsNmobile Solutions Limited and third party must be signed
  2. External service provider must be provisioned on the Payalert platform
  3. A private key and public token would be generated and assigned to the client

Connection Procedure


"URL": "https://payalert-api.anmgw.com/{endpoint}"
"Method": POST
"Data format": JSON
"Content Type": application/json

Authentication

All third party clients are authenticated using IP-based authentication. In addition, all incoming requests are authenticated using HMAC authentication. An HMAC is the product of a hash function applied to the body of a message along with a secret key..


"BODY": "JSON DATA"
"URI": "/{endpoint}"
"CLIENT_kEY": client-key
"CLIENT_SECRET": secret-key
"SIGNATURE": HMAC(sha256, URI+BODY, CLIENT_SECRET)
"HEADER": Authorization: CLIENT_KEY:SIGNATURE


HEADER EXAMPLE
Authorization:"YMMTCfHPFx8hjxg5sdB7aRS98l3ykPzjiNCAr3qJ9NktvyP1jljL9Nfab9VKZn5Q+nBgrgnyVVdCQ==:78fa43ced1aa58a4d721dcf002759c5ccf6e73d2e87fc8a22ff9504af2d50ae0"

Take Note:

  • Generate a hex-encoded hash value, referred to as signature in this document, by running the JSON-encoded payload, which constitute the body of the request, through your preferred programming language’s HMAC function, using sha-256 hashing algorithm
  • The signature and the client key are stored in the HTTP Authorization header, which is part of the HTTP specification.This is done by adding the signature to the end of the client key, with a colon as the separator, and then assigning the resulting string to the HTTP Authorization header

API Details

Debit Customer Wallet

This API, when implemented on a merchant platform allows for payment of goods/services by customers, with Airtel Money.

The table below presents the list of parameters that must be used in forming a Transaction Request for Debit Customer Wallet to Orchard.

Fields Description Example O/M
customer_number Payer MSISDN without Country Code. M
merchant_number Payee MSISDN without Country Code. M
amount Amount to credit/debit, without currency and format. Plain digit like 1000 or 10.20 M
exttrid Unique external transaction reference number. M
reference Reference for service/goods purchased. M
nickname Merchant nickname that would appear on the Push USSD to the customer making the payment. M
ts Current timestamp at the time of sending the request.
Format: YYYY-MM-DD HH:MI:SS
Example: 2015-01-01 23:20:50
Note that Timezone must be set to UTC 		M 
Sample Resquest
curl https://payalert-api.anmgw.com/debitCustomerWallet
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"customer_number":"540343072","merchant_number": "540343075", "amount":"1000","exttrid":"XXXX","reference":"342","nickname":"sconty,"ts":"2022-01-01 23:20:50"}'


Sample Response
{
  "message": "Success",
  "trans_status": "200",
  "trans_id": "MP151224.1621.C00005",
  "trans_ref": "1512241630284"
}
How it Works:
  • Depending on the merchant platform, the subscriber will choose option to pay by Airtel Money
  • Merchant platform will send the request to AppsNMobile
  • AppsNMobile will send the merchant-initiated payment request to the Airtel Money platform
  • The Airtel Money platform will validate the request and send a USSD push to the subscriber’s mobile phone to confirm the transaction by entering their Airtel Money PIN
  • Subscriber will enter the Airtel Money PIN
  • Airtel Money platform will validate the transaction and process it by debiting the subscriber’s wallet and crediting the merchant’s wallet
  • AppsNMobile will forward the resulting transaction details to the third-party platform for processing, via a callback url provided by the third-party
The response to a request is sent back to the third-party platform via a callback URL that must be provided by the third-party prior to integration.

Credit Customer Wallet

This API, when implemented, allows merchants to move funds into customer wallets on Airtel Money. It is, for instance, relevant in a situation where a merchant needs to pay money to a customer registered with that merchant, for a service being offered to the customer.

The table below presents the list of parameters that must be used in forming a Transaction Request for Credit Customer Wallet to Orchard.

Fields Description Example O/M
customer_number Payer MSISDN without Country Code. M
merchant_number Payee MSISDN without Country Code. M
amount Amount to credit/debit, without currency and format. Plain digit like 1000 or 10.20 M
exttrid Unique external transaction reference number. M
reference Reference for service/goods purchased. M
nickname Merchant nickname that would appear on the Push USSD to the customer making the payment. M
ts Current timestamp at the time of sending the request.
Format: YYYY-MM-DD HH:MI:SS
Example: 2015-01-01 23:20:50
Note that Timezone must be set to UTC 		M 
Sample Resquest
curl https://payalert-api.anmgw.com/creditCustomerWallet
-H  'Authorization: CLIENT_ID:SIGNATURE'
-H  'Content-Type: application/json'
-X  POST
-d  '{"customer_number":"540343072","merchant_number": "540343075", "amount":"1000","exttrid":"XXXX","reference":"342","nickname":"sconty,"ts":"2022-01-01 23:20:50"}'


Sample Response
{
  "message": "Success",
  "trans_status": "200",
  "trans_id": "CI151223.1601.C00003",
  "trans_ref": "WDR1234"
}
How it Works:
  • Merchant platform will send the request to AppsNMobile
  • AppsNMobile will send the request to the Airtel Money platform
  • Airtel Money platform will validate the request and process it by debiting the merchant’s wallet and crediting the customer’s wallet
  • AppsNMobile will forward the resulting transaction details to the merchant platform for processing
The response to a request is sent back to the third-party platform via a callback URL that must be provided by the third-party prior to integration.

Merchant Customer Collections

AM-Initiated USSD Payment (Merchant Collections)

The AM USSD on short code *500# is used by AM customers for various third party payments, usually called merchant collections, such as ECG, DSTv and many more.

Real time transaction details can be passed to third-parties whose customers use the *500# short code for payment.

A third-party is required to provide a callback URL for integration.

The appsNmobile platform will pass any transaction that hits the platform to the appropriate third-party system, via the third-party callback url, with transaction details as described in the table below.

A response is expected from the third-party system, with a response code and a corresponding response description, indicating the success or otherwise of the transaction.

Based on the response from third-party platform, the actual debit/credit would be applied to the transaction on the Airtel Money platform.

Take Note:

A callback url is a web service on the third-party system that receives transactions from the appsNmobile platform. The transaction is sent using the POST method and data type is JSON 

Sample Request
{
  "transid": "MP151223.1516.C00001",
  "amount": "1000",
  "reference_field": "REFERENCE:ami|MERCHANT_MOBILE_NO:261054672",
  "msisdn":"540343075"
}

Sample success response
{
  "resp_code": "00",
  "resp_desc": "Successful"
}

Sample failure response
{
  "resp_code": "01",
  "resp_desc": "Failure"
}

How it Works:
  • Subscriber dials the Airtel Money USSD Menu and selects Buy Goods option followed by the required merchant.
  • System will prompt for amount
  • System will prompt for reference number
  • System will display the transaction details and prompt for the subscriber’s Airtel Money PIN
  • Airtel Money platform will validate the transaction and process it by debiting the subscriber’s wallet and crediting merchant’s wallet
  • AppsNMobile will forward the resulting transaction details to the merchant platform for processing
  • Merchant platform will respond back to AppsNMobile with status of processing, for onward delivery to Airtel Money system
  • Transaction SMS will finally be sent to the subscriber
The response to a request is sent back to the third-party platform via a callback URL that must be provided by the third-party prior to integration.