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:

mobile-monney-payment

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

PROD : https://api.www.bizao.com/mobilemoney/v1

2.2.1 “mobilemoney” API query syntax

Your query will contain the following Headers:

HeaderDescription/ContentUsage
AuthorizationYOUR_ACCESS_TOKENMandatory
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
channelThe 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
langthe abbreviation in 2 characters of targeted
language for the PopUp, In ISO 639 (alpha-2) format
Mandatory
content-typeapplication/jsonMandatory

The body of your query will manage parameters below:

Parameter nameDescriptionUsage
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.htmlMandatory
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_urlThe URL of the web site where the customer returns when the payment is completedMandatory
cancel_urlThe URL of the web site where the customer returns when the payment is canceled by the customerMandatory
referenceReference to the Merchant Name.Mandatory 30 char max
user_msisdnThe MSISDN of the User/purchaser.
To use only in : TPE and USSD channels.
Optional in case of WEB channel
otp_codeWhen applicable, the OTP Code is the one generated by the User to approve the transaction. To use only in : TPE and USSD channelsOptional / Mandatory based on the operator
stateParameter 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 »
}

format/content below:
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 »
}

Retour en haut