Payment APi
1. Service Providers access to Bizao APIs
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 <mobilemoney> 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.
Below diagram call flow:
Please note that is necessary to book a slot for an end-to-end test on our Preprod Environment.
Our Integration team is reachable : [email protected]
Once your integration finished, BIZAO will generate your production access and our support team [email protected] will take the over.
Your ACCESS_TOKEN
The ACCESS_TOKEN is generated and must be present in the header of all your calls to our APIs.
Sample of ACCESS_TOKEN:“4qa1bae4-3f9b-346-9t8b-c0e4d4ef”
You will find more information about how to generate and how to use your ACCESS_TOKEN here: https://dev.www.bizao.com/#/get_access_token
< mobilemoney > API
2.1 Principles
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:
• Headers: contains information letting Bizao to route your traffic by : country, operator and channel targeted.
• Body-parameters: contains detail on your payment transaction: order-id, amount, currency, …
• 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.2 Description
Bizao <mobilemoney> is a one-time API. Below the syntax and description:
• Api-name: “mobilemoney/v1”
• Based URL PREPROD: https://preproduction-gateway.www.bizao.com
• Based URL PROD: ‘https://api.www.bizao.com
• Method: POST
To call the “mobilemoney” service, below is the syntax:
PREPROD : https://preproduction-gateway.www.bizao.com/mobilemoney/v1
2.2.1 “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 : <ci> 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 <tpe>: 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: “MyMerchantNAmeID” where: ID : is a unique number identifier of transaction PS: special characters should be avoided, order_id should contain only letters and numbers. | 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 |
| 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 Encoded-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://preproduction-gateway.www.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’ \
–data-raw ‘{
« currency »: « XOF »,
« order_id »: « MerchantOrderid4 », « amount »: 10,
« state »: « param1%3Dvalue1%26param2%3Dvalue2 », « return_url »: « https://callback.www.bizao.com/MM/return.html », « cancel_url »: « https://callback.www.bizao.com/MM/return.html », « reference »: « Your-reference »,
“user_msisdn”:””:: it’s optional
}’
2.2.1 “mobilemoney” API query syntax
Bizao “mobilemoney” payment API will response in Json format.
This Json format/response has two different body according to targeted payment channel:
• <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”, « user_msisdn »: » «
}
• pay_token: uniquely identifies the payment page/PopUp.
• payment_url : URL of the Bizao PopUp payment where the user will process the payment (to display in the User device)
• <ussd & 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”,
» intTransaction-id »: « 1601372072771 », « extTransaction-id « : « MP200929.0935.A64320 »
}
2.3 Notification flow
Bizao “mobilemoney” API also manages a Notification flow. For each user payment transaction, Bizao makes two type of notification:
• 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.
• 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 “,
» intTransaction-id »: « 1601372072771 », « extTransaction-id « : « MP200929.0935.A64320 »
}
}
Getstatuts APi
“getstatus” API
Principales
The merchant can check any transaction details via the “getStatus” service. “getstatus” API
2.4 Description
Bizao <getStatus> is a one-time API. Below syntax and description
• Api-name: “mobilemoney/v1/getStatus/’”
• Order-id: the order-id from the merchant.
• Based URL PREPROD: ‘https://preproduction-gateway.www.bizao.com
• Based URL PROD: ‘https://api.www.bizao.com
• Method: GET
3.2.1 “getstatus” API query syntax :
To call the “getstatus” service, below is the syntax:
PREPROD : https://preproduction-gateway.www.bizao.com/mobilemoney/v1/getStatus/Order-id
PROD : https://api.www.bizao.com/mobilemoney/v1/getStatus/Order-id
“getStatus” sample query :
curl –location –request GET ‘https://preproduction- gateway.www.bizao.com/mobilemoney/v1/getStatus/MerchantOrderid4’ \
–header ‘Authorization: Bearer 483a05b2-25e8-314f-8db3-dc8081547458’ \
–header ‘Accept: application/json’ \
–header ‘Content-Type: application/json’ \
–header ‘country-code: sn’ \
–header ‘mno-name: orange’ \
–header ‘channel: web’ \
–header ‘Cookie: SERVERID=s1’
3.2.2 Getstatus API response
Bizao <getStatus> API will response in Json format.
This Json format/response has the same format as for notification
{
« meta »: {
« type »: « payment », « source »: « sn_orange_mm », « channel »: « web »
},
« status »: « Successful », « amount »: « 10 »,
« order-id »: « MerchantOrderid4 », « currency »: « XOF »,
« reference »: « Your-reference », « date »: « 2020-09-29 09:34:32.0 »,
« state »: « param1%3Dvalue1%26param2%3Dvalue2 », « country-code »: « sn »,
“user_msisdn”:”22575338226 “,
« intTransaction-id »: « 1601372072771 », « extTransaction-id « : « MP200929.0935.A64320 »
}