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:
| Header | Description/Content | Usage |
| Authorization | YOUR_ACCESS_TOKEN | Mandatory |
| mno-name | (string) the name of operator you target 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 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 |
| channel | The 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 |
| type | The type of the transfer (Wallet, cash or bank) | 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]. 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 accepted | Mandatory |
| reference | Reference to the Merchant Name | Mandatory 30 char max |
| sender | Object <customer> | Mandatory, it is an object |
| beneficiary | Object <customer> | Mandatory, it is an object |
| 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 |
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
| ErrorCode | Exception Message Text | Description / Comments | HTTP Response Code |
| 50 | Forbidden access to the API | Access denied by ACL. ‘Unauthorized Access Layer’ or ‘Unauthorized applicationId’ or ‘Unauthorized country’ | 403 Forbidden |
| 1201 | Forbidden access to the API | Forbidden transaction | 403 Forbidden |
| 1202 | Forbidden access to the API | Invalid merchant key | 403 Forbidden |
| 1203 | Forbidden access to the API | Unauthorized currency for this country | 403 Forbidden |
| 1204 | Forbidden access to the API | Order Already exists. The order_id must be unique in the system. Only one Token per order_id | 403 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
}
}