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.site-dev.bizao.com
o Production: https://api.site-dev.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.site-dev.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.site-dev.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.site-dev.bizao.com
o Production: https://api.site-dev.bizao.com/
• Method: GET
5.2.1 “getStatus” API query syntax :
To call the “getStatus” service, below is the syntax: https://api.site-dev.bizao.com/bulk/v1/getStatus/{batchNumber}
“getstatus” sample query :
curl –location –request GET ‘https://api.site-dev.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 »: « »
}
]
}
| 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. |
