Mobile Money API
1. Principles
Bizao gateway gives you access to a large panel of services through REST APIs.
Mobile Money is one of these services.
This service is based on a <mobilemoney> northbound API that aggregates and covers
multiple countries, operators, and payment channels.
Right now, our API manages the payment channels below :
• Web : channel dedicated to all payment traffic using our PopUp UI
• TPE : channel dedicated to all payment traffic coming from integrated merchant-
TPE devices.
• USSD : channel dedicated to all payment traffic coming from USSD channel
This API lets you target the right country, operator, and channel by using the dedicated
Header for that.
To grant access to the service, our Integration team will onboard you on this service/API and
send you your dedicate credentials/access-Token.
So far, only Orange Money web-payment page is available for testing via a sandbox.
You can start your implementation based on this Sandbox.
Note :
Please note that is necessary to book a slot for an end-to-end test on our sandbox. Our
Integration team (integration@bizao.com) will help you during the testing step by providing
you a PIN and a dumb number to validate each payment test.
Each PIN is valid during 15 mns.
Mobile money API payment
This API allows you to create payment transaction on Bizao Hub based on the information
provided in your request.
This API manages three categories of parameters:
1. Headers: contains information letting Bizao to route your traffic by : country,
operator and channel targeted.
2. Body-parameters: contains detail on your payment transaction: order-id, amount,
currency, …
3. Static-parameters: this category of parameter cover all parameter that are static
per merchant for all its payment traffic (Notification-URL,…). These parameters will
be provisioned in Bizao Hub (in SignUP step) per Merchant and will be used by Bizao-
Hub in the payment traffic.
2. Description
Bizao <mobileoney> API is a one-time API. Below the syntax and description :
a. Api-name : “mobilemoney/v1”
b. Based URL : https://api.bizao.com/
c. Method : POST
- “mobilemoney” API query syntax
Your query will contain the following Headers :
| Header | Description/Content | Usage |
| Authorization | YOUR_ACCESS_TOKEN | Mandatory |
| mno-name | (string) the name of the operator. example : orange, mtn. Bizao will update you regarding the new mno set in the hub | Mandatory |
| country-code | (string)2 characters code of the country. Use this norme : ISO 3166 alpha 2 country code, url to get the all country-code list: https://www.iban.com/country-codes (for instance : is the country-code for ivory Coast. | Mandatory |
| channel | The type of targeted channel using one of keyword: <web>: to target the Bizao payment PopUp <type>: to target the Bizao TPE payment flow <ussd>: to target the Bizao USSD payment flow | Mandatory |
| lang | the abbreviation in 2 characters of targeted language for the PopUp, In ISO 639 (alpha-2) format | Mandatory |
| content-type | application/json | Mandatory |
The body of your query will manage parameters below :
| Parameter name | Description | Usage |
| currency | (string) currency identifier as defined in [ISO4217]. you can use this site to know the currency-code by country: https://fr.iban.com/currency-codes.html | Mandatory |
| order_id | (string) unique identifier of the payment request. IT MUST BE UNIQUE FOR THE SYSTEM and must follow the following format: “MyMerchantNAme_ID” where: ID : is a unique number identifier of transaction. | Mandatory 30 char max |
| amount | (decimal) amount to be charged. | Mandatory |
| return_url | The URL of the web site where the customer returns when the payment is completed | Mandatory |
| cancel_url | The URL of the web site where the customer returns when the payment is canceled by the customer | Mandatory |
| notif_url | Offline setup: to be provided by the merchant during the onboarding step. The notification URL is used by Bizao to update the merchant about the transaction status. | Mandatory |
| reference | Reference to the Merchant Name. | Mandatory 30 char max |
| user_msisdn | The MSISDN of the User/purchaser. To use only in : TPE and USSD channels. | Optional in case of WEB channel |
| otp_code | When applicable, the OTP Code is the one generated by the User to approve the transaction. To use only in : TPE and USSD channels | Optional / Mandatory based on the operator |
| state | Parameter up to merchant to set within any value he wants to keep over all payment transaction processing. This field must be in Encodeded-URL (Bizao do not alternate/update this value and send it back within payment response/notification) | Mandatory |
Payment query sample :
Note: for each new payment-query you have to provide a new value for “order_id” .
Parameter :
curl --location --request POST 'https://api.bizao.com/mobilemoney/v1' \
--header 'Authorization: Bearer 483a05b2-25e8-314f-8db3-dc8081547458' \
--header 'country-code: sn' \
--header 'mno-name: orange' \
--header 'lang: fr' \
--header 'channel: web' \
--header 'Content-Type: application/json' \
--header 'Cookie: SERVERID=s0' \
--data-raw '{
"currency": "XOF",
"order_id": "Merchant_Order_id_4",
"amount": 10,
"state": "param1%3Dvalue1%26param2%3Dvalue2",
"return_url": "https://callback.bizao.com/MM/return.html",
"cancel_url": "https://callback.bizao.com/MM/cancel.html",
"reference": "Your-reference"
}
- “mobilemoney” API response
Bizao “mobilemoney” payment API will response in Json format.
This Json format/response has two different body according to targeted payment channel:
1. <web> channel:
In case the merchant targets the <web> channel, the payment API will send/response with the URL of Bizao PopUP as below.
Success query response sample :
Content-Type: application/json
{
"status": 201,
"message": "OK",
"pay_token": "v1sqjbl4cahdoonenvedipechroz9yz1agvhxoxblnvyl2kngd4dcua4qyyma2kk",
"payment_url": "https://webpayment.orange-
money.com/ci/mpayment/abstract/v1sqjbl4cahdoonenvedipechroz9yz1agvhxoxblnvyl2kngd4d
cua4qyyma2kk",
"notif_token": "ibcukkpd2mgmahli4qgpig0w0hmhwbgi",
“state": "param1%3Dvalue1%26param2%3Dvalue2”
}
o pay_token: uniquely identifies the payment page/PopUp.
o payment_url : URL of the Bizao PopUp payment where the user will process the
o payment (to display in the User device)
2. <ussd and tpe> channel:
In case the channel is one of value: <ussd> or <tpe> .
The Bizao Hub response will be json format/content below:
{
"meta": {
"type":"payment",
"source": "orange"
"channel":tpe
}
{
“status” : “pending”,
“amount” : “xxxxxx”,
“order-id” : “xxxxxx”,
“currency”: “xxxxx”,
“reference” : “xxxx”,
“country-code”: “xxxxx”,
“state”: ”xxxxxxxxxxx”,
“user_msisdn”:”22575338226 “,
“otp_code”:”123467”,
“Transaction-id” : ”xxxxxxxxxxx”
}
}
3.Notification flow
Bizao “mobilemoney” API also manages a Notification flow. For each user payment
transaction, Bizao makes two type of notification:
o B2C-Notif: this category of notification is for the User/purchaser. For each successful
payment, Bizao will send him a SMS. The format and wording of this SMS message
depends on the Southbound/operator backend that Bizao uses.
o B2B-Notif: this category of notification is for the merchant backend. For each
payment transaction, Bizao will notify the merchant backend (using the merchant-
Callback) with the final status of the payment transaction.
Note: In case of timeout or any technical issues, “getStatus” API is another alternative
to get the transaction details.
Below a sample of notification content:
{
"meta": {
"type":"payment-notif",
"source": "orange",
"channel": "web"
}
{
“status” : “successful”,
“amount” : “xxxxxx”,
“order-id” : “xxxxxx”,
“currency”: “xxxxx”,
“reference” : “xxxx”,
“country-code”: “xxxxx”,
“state”: ”xxxxxxxxxxx”,
“user_msisdn”:”22575338226 “,
“Transaction-id” : ”xxxxxxxxxxx”
}
}