Money Transfer API

Bizao gateway gives you access to a large panel of services through REST APIs. Money Transfer is one of these services.

This service is based on a northbound API that aggregates and covers multiple countries, operators, and payment type.

Right now, our money transfer API manages and covers below transfer types:

• Cash: dedicated to a classical remittance like Western Union, Wari, RIA, MoneyGram etc. (Remittance).
• Wallet: dedicated to all Wallet deposit (Cashin).
• Bank: dedicated to bank deposit

This API lets you target the right country, operator, channel, et type by using the dedicated Header for that.

The onboarding process of partners (IRT) is out of the scope of this this document. Our integration will be in charge to manage this step offline.

For this version, only the type Wallet is covered. Other types will be covered in further versions.

1. Your ACCESS_TOKEN

The ACCESS_TOKEN is generated thanks to your CLIENT_ID and CLIENT_SECRET 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/docs/getting-started/generate-a-bizao-access_token/

2. Partner onboarding:

The partner onboarding is set offline. After the onboarding, the partner will have a virtual account in BIZAO system and credentials are sent by the most suitable channel(email, SMS, etc.).

3 < moneytransfer > API

3.1 Principles

This API allows you to do Cashin through 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, channel and type you target.
• Body-parameters contains detail on your transfer: sender details, beneficiary details, amount, currency, the country where the transaction was originated, the destination country, destination wallet, etc…
• Static-parameters: this category of parameter cover all parameter that are static per merchant for all its remittance transactions (Notification-Fees rules, …). These parameters will be provisioned in Bizao Hub (in SignUP step) per partner and will be used by Bizao-Hub in the transfer process.

3.2 Description

Bizao <moneyTransfer> is a JSON/Rest based API.

Below the syntax and descriptive:

• Api-name: “moneyTransfer”
• Based URL: https://api.www.bizao.com/
• Method: POST

4.2.1 moneyTransfer API query syntax

Your query will contain the following Headers:

HeaderDescription/ContentUsage
AuthorizationYOUR_ACCESS_TOKENMandatory
mno-name(string) the name of operator you target example : orange, mtn. Bizao will update you regarding the new mno set in the hubMandatory
country-code(string)2 characters code of the country you target ( 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 flow
<tpe>: to target the Bizao TPE payment flow
<Ussd>: to target the Bizao USSD payment flow
Mandatory
typeThe type of the transfer (Wallet, cash or bank)Mandatory
langthe abbreviation in 2 characters of targeted language for the PopUp, In ISO 639 (alpha-2) formatMandatory
content-typeapplication/jsonMandatory

The body of your query will manage parameters below:

Parameter nameDescriptionUsage
currency(string) currency identifier as defined in [ISO4217]. Note (as described for the amount parameter) that either currency and amount or code must be specified. you can use this site to know the currency-code by country:
https://fr.iban.com/currency-codes.html
Note: for Sandbox testing use “OUV’ as currency.
Mandatory
order_id(string) identifies this create payment request. This field SHOULD be present. 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(integer) amount to be charged. Cents are not acceptedMandatory
referenceReference to the Merchant NameMandatory 30 char max
senderObject <customer>Mandatory, it is an object
beneficiaryObject <customer>Mandatory, it is an object
stateParameter 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

Customer object

<<customer ::Object>>
_FirstName //customer first name
_LastName //customer last name
_Msisdn //customer msisdn
_Address //customer address

Note: replace the signe (_) by sender or beneficiary like this one: senderFirstName
transfer query sample:
Note : for each new transfer query you have to provide a new value for “order_id” Parameter.

POST moneyTransfer/v1 HTTP/1.1 Host: api.www.bizao.com
Authorization: Bearer cb422427-1wo6-3be2-b15b-sff651s7bs4e
country-code: sn mno-name: free lang:fr channel:web type: wallet

-d ‘{
//sender details
« senderFirstName »: « A sender name », « senderLastName »: « A sender last name », « senderAddress »: “A sender address”,
“senderMobileNumber »: « 33612345678, //The international mobile number without 00 or +
“fromCountry”: “fr”

//beneficiary details « beneficiaryFirstName »: « Ibou », « beneficiaryLastName »: « Fall »,
« beneficiaryAddress »: “Rue 10 angle 20, Medina, Dakar”,
« beneficiaryMobileNumber »: “221769876543″, //The international mobile number without 00 or +

//other details « currency »: « XOF »,
“reference”:”MerchantName” // is the merchant name in capital
« order_id »: « MerchA_1234598762 »,
« amount »: 10, //only integer value is accepted
« state »: « param1%3Dvalue1%26param2%3Dvalue2 » // the Merchant correlation data
“reference” “Merchant-name”

}’

4.2.1 MoneyTransfer API response

Bizao <moneyTransfer> API will response in Json format Success query response sample

Success query response sample

Content-Type: application/json
{
« status »: « Successful »,
« transaction-Id »: «  », //the transaction id from BIZAO system
« senderFirstName »: « A sender name », « senderLastName »: « A sender last name », « senderAddress »: “A sender address”,
“senderMobileNumber »: « 336761234567 », //The international mobile number without 00 or
+
//beneficiary details « beneficiaryFirstName »: « Ibou », « beneficiaryLastName »: « Fall »,
« beneficiaryAddress »: “Rue 10 angle 20, Medina, Dakar” , « beneficiaryMobileNumber »: “221769876543″, to be mapped with the MSISDN in the southbound request. The international mobile number without 00 or +
//other details « fromCountry »: « fr, « toCountry »: « sn »,
« currency »: « XOF »,
« order_id »: « MerchA_1234598762 », « amount »: 10,
« state »: « param1%3Dvalue1%26param2%3Dvalue2 » // the Merchant correlation data
“reference” “Merchant-name”
}

For the getStatus service, we will link the transaction-id with the intransaction parameter.

3.3 getBalanceInfo

This service is used by IRT partners to display their balance details in our hub. It is necessary to pass the account name to display the balance.
If the account name is passed, this specific account balance is displayed. If no account name is passed, all the accounts configured for this IRT is displayed.

Samples Responses:

Content-Type: application/json
{
« meta »:
{
« type »: « account-view »,
« source »: « bizao »
}

{ « currency »: « XOF », « reference »: « sunu_test »,
« main_account_number »: « sunu_test2001 », « main_account_balance »: 184.00,
« advance_amount_provided »: 1000.00,
« loan_amount_taken »: 0.00,
« available_balance »: 1184.00
}
}
Get /moneyTransfer/v1/getBalanceInfo/accountName HTTP/1.1 Host: api.www.bizao.com
Authorization: Bearer cb422427-1wo6-3be2-b15b-sff651s7bs4e

3.4 Notification flow

Bizao moneytransfer is a synchronous API.
For each transfer, there are two types of notification:

o B2C-Notif: this category of notification is for the beneficiary. For each successful payment, the mobile operator will send him an SMS with the details of the transfer.

o B2B-Notif: The response of the API is synchronous and there is no need for a call back from the partner. However, the partner can use the service getStatus anytime to check the transaction status as long as it is kept in the Bizao database.

Get /moneyTransfer/v1/getStatus/orderId HTTP/1.1 Host: api.www.bizao.com
Authorization: Bearer cb422427-1wo6-3be2-b15b-sff651s7bs4e

Get: getStatus/v1/
{
« meta »: { « type »: »transfer-notif », « source »: « sn-free »,
« channel »: « web »
}
{
“status” : “successful”,
“amount” : “xxxxxx”,
“order-id” : “xxxxxx”,//The unique id from the IRT
“currency”: “xxxxx”,
“reference” : “xxxx”,
“country-code”: “xxxxx”,
“state”: ”xxxxxxxxxxx”,
“user_msisdn”:”22575338226 “,
“fromCountry”:”fr “,
“toCountry”:”sn “,
« intransactionId »: «  », //the transaction id from bizao system « extransactionId »: «  », //the transaction id from the operator « senderFirstName »: « A sender name »,
« senderLastName »: « A sender last name », « senderAddress »: “A sender address”, “senderMobileNumber »: « 33761234567 », « beneficiaryFirstName »: « Ibou », « beneficiaryLastName »: « Fall », « beneficiaryAddress »: Medina, « beneficiaryMobileNumber »: “221769876543″,
}
}

4 Bizao transfer API common error code

ErrorCodeException Message TextDescription / CommentsHTTP
Response Code
50Forbidden access to the APIAccess denied by ACL. ‘Unauthorized Access Layer’ or ‘Unauthorized applicationId’ or ‘Unauthorized country’403 Forbidden
1201Forbidden access to the APIForbidden transaction403 Forbidden
1202Forbidden access to the APIInvalid merchant key403 Forbidden
1203Forbidden access to the APIUnauthorized currency for this country403 Forbidden
1204Forbidden access to the APIOrder Already exists. The order_id must be unique in the system. Only one Token per order_id403 Forbidden
Get Statuts API

Get Balance Info

This service is used by IRT partners to display their balance details in our hub. It is necessary to pass the account name to display the balance.

If the account name is passed, this specific account balance is displayed. If no account name is passed, all the accounts configured for this IRT is displayed.

Get /moneyTransfer/v1//getBalanceInfo/accountName HTTP/1.1
Host:api.www.bizao.com
Authorization: Bearer cb422427-1wo6-3be2-b15b-sff651s7bs4e
type: bulk

Samples Responses:

Content-Type: application/json
{

{
« meta »: {
« type »: « account-view »,
« source »: « bizao »

}

{

« currency »: « XOF »,
« reference »: « sunu_test »,
« main_account_number »: « sunu_test2001 »,
« main_account_balance »: 184.00,
« advance_amount_provided »: 1000.00,
« loan_amount_taken »: 0.00,
« available_balance »: 1184.00


}
}

Retour en haut