2. Your ACCESS_TOKEN
The ACCESS_TOKEN is generated offline and sent to the IRT via a suitable chanel.

3. Partner onboarding:
For < Bulk >, we have two additional steps apart the access token:

1- we will follow the same step as the <transfer> to create the partner id and the security token for the authentication

2- We will create Three virtual wallets for the partner:

a. one called <MainAccount> where we credit the balance of the partner in Bizao hub. Transactions will debit this account. It is mandatory to have enough balance in this wallet for a transaction to be processed correctly. It is necessary to have a dedicated profile to be able to credit this account via a GUI portal. All transactions there are typed (via the parameter operationType) as credit, debit, refund or advance.

  • i. operationType= credit: means it is a classical and normal operation of crediting an account
  • ii. operationType = debit: means it is a classical and normal operation of debiting an account
  • iii. operationType =advance means it is a loan possibility accorded to the partner. This operation can only be done in the and is like a counter which limits the maximum loan amount for a service provider. If the advancedAccount is set to 100.000 for an SP, this means that SP can have a loan till 100.000. In other word, the mainAccount can be decreased till (-100.000) but not lower.
  • iv. operationType =refund: : means it is an operation of credit (or debit) to (from) the main account to adjust an error.

b. <fees> wallet where Bizao collects all the fees gained from transactions processed by this partner. This wallet is only for internal use.In order to be able to collect the fees, it is mandatory to setup the fees calculation process in the Bizao system. Based on the fees, Bizao system should be able to generate invoices.

c. <advancedAccount>: is used to set a loan possibility accorded to the partner

4. < Bulk > API

4.1 Principles
This API allows you to do Cashin in different recipients with just one click 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.
  • Headers: contains information letting Bizao to route your traffic by country, operator, channel and type you target.
  • Static-parameters: this category of parameter cover all parameters that are static per merchant for all its payment traffic (Notification-Fees rules,sender details, …). These parameters will be provisioned in Bizao Hub (in SignUP step) per Partner and will be used by Bizao-Hub in the transfer process.

4.2 Description
Bizao <bulk> isss a restful API, based on json.

• Api-name: “bulk/v1”
• URL:
o Preproduction: https://preproduction-gateway.www.bizao.com
o Production: https://api.www.bizao.com
• Method: POST

4.2.1 bulkpayment API query syntax

Your query will contain the following Headers:

Header Description/Content Usage
Authorization YOUR_ACCESS_TOKEN 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>:
Mandatory
type The type is set to bulk Mandatory
lang the abbreviation in 2 characters of targeted language for the request, 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 Mandatory
reference Reference to the bulkpayment client Mandatory 30 char max
batchNumber (string) identifies this create payment request. This field SHOULD be present. IT MUST BE UNIQUE FOR THE SYSTEM. Mandatory
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
beneficiary Object <customer> Mandatory, it is an object

Customer object

<<customer ::Object>>
id //lock number
beneficiaryFirstName //customer first name beneficiaryLastName //customer last name beneficiaryAddress //customer address beneficiaryMobileNumber //customer msisdn
amount //customer address Amount to transfer to the beneficiary wallet feesApplicable //(YES or NO) boulean parameter to know if the fees is applicable or not mno // MNO name

bulkpayment query sample:
Note : for each new bulkpayment query you have to provide a new value for “batchNumber ”
Parameter.

POST bulk/v1/
Host: api.www.bizao.com Authorization: Bearer token
Content-Type: application/json
country-code: sn lang:fr channel:web type: bulk

–d ‘{
“currency”: “XOF”,
“reference”: “bsc-bulk-mt-XOF”,
“batchNumber”: “bulk-sn_07-10-2021_01”, // Unique “state”: “param1%3Dvalue1%26param2%3Dvalue2”, “data”: [
{
“id”: “001”, // This id will be concatenated with the batchNumber. The result of this concatenation will be order_id of the request to be sent to the MNO.
“beneficiaryFirstName”: “Abdou”,
“beneficiaryLastName”: “Diop”, “beneficiaryAddress”: “”,
“beneficiaryMobileNumber”: “221761234567”, // to be mapped with the MSISDN in the southbound request. The international mobile number without 00 or +
“amount”: 10,
“feesApplicable”: “YES”, “mno”: “free”
},
{
“id”: “002”,
“beneficiaryFirstName”: “Logan”, “beneficiaryLastName”: “Doo”,
“beneficiaryAddress”: “Rue 10 angle 20, Medina, Dakar”, “beneficiaryMobileNumber”: “2217754566666”,
“amount”: 1, “feesApplicable”: “YES”, “mno”: “orange”
}
]
}’

4.2.2 Bulk API response
Bizao <bulk> API will response in Json format
This Json format/response has two different parties :

  • The meta bloc containing the common details( reference, batchNumber, bulkpayment customer informations, …)
  • The second bloc(data) contain the specific data for the beneficiary

Response query

Content-Type: application/json
}
“meta”: {
“source”: “bizao”,
“merchant-name”: “[email protected]”,
“type”: “bulk”,
“currency”: “XOF”,
“batchNumber”: “bulk-sn_07-10-2021_01”, “reference”: “bsc-bulk-mt-XOF”,
“feesType”: “FIXED_FEE”, //Type of fees applicable for this bulk payment customer
“lang”: “fr”,
“totalAmount”: 11.00, //Total principal amount in the batch
“totalFees”: 2.00, //Total fees amount in the batch

//Bulkpayment customer details “senderFirstName”: “Damith”, “senderLastName”: “Sulochana”, “senderAddress”: “Colombo”, “senderMobileNumber”: “2250512345678”, “fromCountry”: “cm”,
//END Bulkpayment customer details
“comment”: “Bulk Process will take minimum 0.28 minutes”
},
“data”: [
{
“id”: “001”,
“orderId”: “bulk-sn_07-10-2021_01-001”, “mno”: “free”, “beneficiaryFirstName”: “Salif”, “beneficiaryLastName”: “KA”, “beneficiaryAddress”: “”,
“beneficiaryMobileNumber”: “221765151504”. The international mobile number without 00 or +
“toCountry”: “sn”, “feesApplicable”: “Yes”, “amount”: 10.00,
“fees”: 1.00,
“status”: “Pending”,
“intTransaction-Id”: “1aa27e52-969b-4fd1-8012-da5606b8de71”, //the transaction id from BIZAO system
“extTransaction-Id”: “” //the transaction id from the MNO system
},
{
“id”: “002”,
“orderId”: “bulk-sn_07-10-2021_01-002”, “mno”: “orange”, “beneficiaryFirstName”: “Logan”, “beneficiaryLastName”: “Doo”,
“beneficiaryAddress”: “Rue 10 angle 20, Medina, Dakar”, “beneficiaryMobileNumber”: “221775782348”, “toCountry”: “sn”,
“feesApplicable”: “Yes”, “amount”: 1.00,
“fees”: 1.00,
“status”: “Pending”,
“intTransaction-Id”: “4be22560-389b-4c69-9e45-e6aa7452b7dd”, //the transaction id from
BIZAO system
“extTransaction-Id”: “” //the transaction id from the MNO system
}
]
}

4.3 getBalanceInfo
This service is very important for Northbound partners. It will help them to know the remaining balance in their virtual wallet merchantAccount(main wallet) in BIZAO system.
Each partner has its own dedicated < main wallet>. So, it is necessary to have the partner id to be able to display the correct balance for a given partner.

Get /bulk/v1/getBalanceInfo/merchantAccount/Account_number
api.www.bizao.com
Authorization: Bearer token type: bulk

Samples Responses:

{
“meta”: {
“source”: “bizao”,
“type”: “bulk”
},
“accounts”: [

{
“account_number”: “bsc2001”, // Account number
“status”: “Active”, // Account status
“currency”: “XOF”, “balance”: 9767.00, //total balance in the system
“reserved_amount”: 43.00, //reserved amount for a batch not treated yet
“loan_balance”: 0.00,
“advance_amount”: 0.00,
“turnover_balance”: 6.00,
“settlement_balance”: 0.00
}
]
}

4.4 Notification flow
Bizao bulk is an asynchronous API.

For each bulk payment, there are two types of notification:

  • B2C-Notif: this category of notification is for the beneficiary. For each successful transfer, the mobile operator will send him an SMS with the details of the transfer.
  • B2B-Notif: this category of notification is for the bulkpayment customer backend. For each batch of transfers, based on the backend configuration (Asynch), Bizao will notify the partner backend (using the partner-Callback when necessary) with the final status of the payment transaction.

Below a sample of notification content:

{
“meta”: {
“source”: “bizao”,
“merchant-name”: “[email protected]”, “type”: “bulk”,
“currency”: “XOF”,
“batchNumber”: “bulk-sn_07-10-2021_01”, “reference”: “bsc-bulk-mt-XOF”, “feesType”: “FIXED_FEE”,
“lang”: “fr”, “totalAmount”: 11.00,
“totalFees”: 2.00, “senderFirstName”: “Damith”, “senderLastName”: “Sulochana”, “senderAddress”: “Colombo”,
“senderMobileNumber”: “2250512345678”, “fromCountry”: “cm”
},
“data”: [
{
“id”: “001”,
“orderId”: “bulk-sn_07-10-2021_01-001”, “mno”: “free”,
“beneficiaryFirstName”: “Salif”, “beneficiaryLastName”: “KA”, “beneficiaryAddress”: “”, “beneficiaryMobileNumber”: “221765151504”, “toCountry”: “sn”,
“feesApplicable”: “Yes”, “amount”: 10.00,
“fees”: 1.00,
“status”: “Successful”,
“intTransaction-Id”: “1aa27e52-969b-4fd1-8012-da5606b8de71”, “extTransaction-Id”: “CI211007.1411.A95748”
},
{
“id”: “002”,
“orderId”: “bulk-sn_07-10-2021_01-002”, “mno”: “orange”, “beneficiaryFirstName”: “Logan”, “beneficiaryLastName”: “Doo”,
“beneficiaryAddress”: “Rue 10 angle 20, Medina, Dakar”, “beneficiaryMobileNumber”: “221775782348”, “toCountry”: “sn”,
“feesApplicable”: “Yes”,
“amount”: 1.00,
“fees”: 1.00,
“status”: “Failed”,
“failedReason”: “Validation failed, please contact support”, “intTransaction-Id”: “4be22560-389b-4c69-9e45-e6aa7452b7dd”, “extTransaction-Id”: “”
}
]
}

Get Statuts API

5.1 Principales
The bulkpayment customer can check any transactions in a batch via the “getStatus” service.
“getStatus” API

5.2 Description
Bizao <getStatus> API Resful/json API. Below syntax and description

• Api-name: “bulk/v1/getStatus”
• batchNumber: the batchNumber of the bulk transaction.
• Based URL:
o Preproduction: https://preproduction-gateway.www.bizao.com
o Production: https://api.www.bizao.com/
• Method: GET

5.2.1 “getStatus” API query syntax :
To call the “getStatus” service, below is the syntax: https://api.www.bizao.com/bulk/v1/getStatus/{batchNumber}

“getstatus” sample query :

curl –location –request GET ‘https://api.www.bizao.com/bulk/v1/getStatus/bulk-sn_07-10- 2021_01’ \
–header ‘Authorization: token’ \
–header ‘Content-Type: application/json’ \
–header ‘channel: web’ \
–header ‘type: bulk’ \
–header ‘Cookie: AlteonMS17=AVGuRvbEYwp+/a0U3c6Ndg$; SERVERID=s0; SRV=c4929e28-54ed-4c57-bec6-a50f7151ac41’

5.2.2 Getstatus API response
Bizao <getstatus> API will response in Json format.
This Json format/response has the same format as for notification flow.

{
“meta”: {
“source”: “bizao”,
“merchant-name”: “[email protected]”, “type”: “bulk”,
“currency”: “XOF”,
“batchNumber”: “bulk-sn_07-10-2021_01”, “reference”: “bsc-bulk-mt-XOF”, “feesType”: “FIXED_FEE”,
“lang”: “fr”, “totalAmount”: 11.00,
“totalFees”: 2.00, “senderFirstName”: “Damith”,
“senderLastName”: “Sulochana”, “senderAddress”: “Colombo”, “senderMobileNumber”: “2250512345678”, “fromCountry”: “cm”
},
“data”: [
{
“id”: “001”,
“orderId”: “bulk-sn_07-10-2021_01-001”, “mno”: “free”, “beneficiaryFirstName”: “Salif”, “beneficiaryLastName”: “KA”, “beneficiaryAddress”: “”,
“beneficiaryMobileNumber”: “221765151504”, “toCountry”: “sn”,
“feesApplicable”: “Yes”, “amount”: 10.00,
“fees”: 1.00,
“status”: “Successful”,
“intTransaction-Id”: “1aa27e52-969b-4fd1-8012-da5606b8de71”, “extTransaction-Id”: “CI211007.1411.A95748”
},
{
“id”: “002”,
“orderId”: “bulk-sn_07-10-2021_01-002”, “mno”: “orange”, “beneficiaryFirstName”: “Logan”, “beneficiaryLastName”: “Doo”,
“beneficiaryAddress”: “Rue 10 angle 20, Medina, Dakar”, “beneficiaryMobileNumber”: “221775782348”, “toCountry”: “sn”,
“feesApplicable”: “Yes”, “amount”: 1.00,
“fees”: 1.00,
“status”: “Failed”,
“failedReason”: “Validation failed, please contact support”, “intTransaction-Id”: “4be22560-389b-4c69-9e45-e6aa7452b7dd”, “extTransaction-Id”: “”
}
]
}

5 Bizao transfer API common error code

Error Code API Reponses Error Message Error Description.
Transfer API (BMT100XX)
BMT10001 Missing mandatory header parameter: m no-name mno-name header is missing
BMT10002 Missing mandatory header parameter: country-code country-code header is missing
BMT10003 Missing mandatory header parameter: channel channel header is missing
BMT10004 Missing mandatory parameter: amount Transfer amount is not provided
BMT10005 Amount cannot contain cents Invalid amount, amount is provided with cents
BMT10006 Amount should be in number Provided amount consist some character or special signs
BMT10007 Missing mandatory parameter: beneficiaryMobileNumber BeneficiaryMobileNumber is not provided
BMT10008 senderMobileNumber and beneficiaryMo bileNumber must not be same. User has pass same MSISDN for sender and beneficiary.
BMT10009 Beneficiary number does not match with MNO number format. Invalid MSISDN format for MNO and country
BMT10010 Missing mandatory parameter: currency Currency for transfer is not provided.
BMT10011 Missing mandatory parameter: reference Merchant reference for the currency account Is not provided.
BMT10012 Missing mandatory parameter: order_id Order id for request is not provided.
BMT10013 Missing mandatory header parameter: lang Lang header is missing.
BMT10014 Missing mandatory header parameter: USER_ID Missing USER_ID parameter which send from Api Manager
BMT10015 Missing mandatory header parameter: state State is not provided in the request
BMT10016 Missing mandatory header parameter : type Type header is missing
BMT10017 Invalid parameter for header parameter: type When type parameter type other than wall et or bulk
BMT10018 Invalid header parameter: channel When the channel parameter is having unr ecognized values
BMT11000 Duplicate Order ID Order ID is already used.
BMT11001 You have successful transaction recently for same amount, same sender and same benef iciary. Request has already success for same bene ficiary/sender/mount/currency/mno
BMT11002 No matching account for the request Cannot find Service provider provisioning for requested currency and reference.
BMT11003 Invalid service provider name: %s or merchant name does not match with service provider name. Invalid Service Provider
BMT11004 Fee rule not found for the transfer. Please contact support. Fee rule has not been provisioned for the currency and SP.
BMT11005 Order does not exist for given order ID Invalid or not existing Order ID
BMT11006 Insufficient account Balance Insufficient account balance
BMT00000 Validation failed. Please contact support. General Error
BMT21000 Can’t find the mt_bulk settings conf Cannot find the bulk account no
BMT21001 Exceeded the bulk transaction record limit Cannot find the bulk settings configuration for id = 1
BMT21002 Can’t find bulk account no Merchant is not provisioned or invalid mer chant reference
BMT21003 Date format exception yyyy-mm-dd For the request parameters, date format should be as “yyyy-mm-dd”
BMT20004 Number format exception Beneficiary msisdn is not match with the mno number format.
BMT20005 Can’t find the sender msisdn Merchant information is invalid or not provision the sender msisdn.
BMT20006 Same sender and beneficiary msisdn Both sender and benificiary msisdns as same.
BMT20007 Can’t find the information for given order id. Invalid order id.
BMT20008 Can’t find the bulk accounts for given sp Invalid geven parameters
BMT20009 Request items have missing mandatory properties. Request items have missing mandatory properties
BMT20010 Transaction amount exceeded to current balance. Transaction amount exceeded to current b alance.
BMT20011 No records found for the given criteria. No records found for the given criteria.
BMT20012 date format error When the request parameter is not on the declared date format.
BMT20013 Error while executing background processor. Error while executing background processor.
Scroll to Top