1 Introduction
1.1 Document purpose
This document covers, in details, the design of VISA and MasterCard API renamed debitCard. It contains the implementation and specification details of the service, which are useful for the NorthBound interface developers.
It describes how to payment enable an e-commerce application or online store by using the functionality of the MasterCard Virtual Payment Client (VPC) through Bizao third party as a bridge.
Even if there are no samples for the 3DS card, all the information and specifications provided here are applicable for both 3DS and non 3DS cards.
1.2 Abbreviations and Definitions
| Term | Definition |
| VPC | Virtual Payment Client |
| 3DS | 3D Secure algorithm |
| SP | Service Providers |
1.3 Dependencies and Assumptions
Merchant should have a valid Auth2 account and is classified in a valid category. Merchant should provide a returnUrl for redirection after a valid payment.
Merchant should provide a cancelUrl to be called when the customer cancels a payment before its processing.
Merchant should provide a callBackUrl for the B2B notifications between Bizao and the merchant for any processed transaction.
1.4 debitCard
The API is a RESTful Web Services with JSON formatted messages. All requests need to set the header Content-type as « application/json ».
The north endpoint is :/debitCard and the communication Protocol is HTTPS standards. The complete url of the service for the merchant is :
• Preproduction : https://preproduction-gateway.www.bizao.com/debitCard/v2/
• Production : https://api.www.bizao.com/debitCard/v2/
POST method is used anywhere it is applicable. In order to accomplish a Basic 3-Party Transaction through BIZAO debitCard service, below are the minimal parameters you need to setup in the request:
The Bizao Northbound debitCard API/solution is multi-country and multi-language. Mandatory header parameters are: “content-Type”, “authorization”,“country-code”,” category” & “lang” (for this version of the API, you must always set the value as “en”).
2 Merchant onboarding
To grant access to the service, our Integration team will do an offline onboarding of the merchant and send the dedicate credentials/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/#/get_access_token
3 < debitCard > API
3.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 and language you target.
• Body-parameters contains detail on your payment transaction: amount, currency, used-id…
• Static-parameters: this category of parameter cover all parameters that are static
3.2 Description
Bizao <debitCard> is a one-time API, below syntax and descriptive
• Api-name: “debitCard”
• URL:
o Preproduction: https://preproduction-gateway.www.bizao.com/debitCard/v2
o Production: https://api.www.bizao.com/debitCard/v2
• Method: POST
3.2.1 debitCard 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 |
| lang | the abbreviation in 2 characters of targeted language In ISO 639 (alpha-2) format. For this version of the debitCard service, only English language (en) is accepted | Mandatory |
| content-type | application/json | Mandatory |
| category | The category of the merchant. | 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 For this version of the service, only XOF currency is accepted. | 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 | amount to be charged. Decimal value is not accepted | Mandatory |
| return_url | The URL of the web site where the customer returns when the payment is completed | Mandatory |
| cancel_url | The URL of the web site where the customer returns when the payment is canceled by the customer | Mandatory |
| reference | Reference to the Merchant Name | Mandatory 30 char max |
| 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 |
Note: the amount doesn’t accept cents. So, 1.00XOF is considered to be 100XOF
Payment query sample:
Note : for each new payment-query you have to provide a new value for “order_id” Parameter.
POST debitCard/v2 HTTP/1.1 Host: api.www.bizao.com
Authorization: Bearer cb422427-1wo6-3be2-b15b-sff651s7bs4e
country-code: ci lang:en category: BIZAO
-d ‘{
« currency »: « XOF »,
« order_id »: « MerchA_1234598762 », « amount »: 10,
« state »: « param1%3Dvalue1%26param2%3Dvalue2 », // the Merchant correlation data
“reference”: “Merchant-name”,
« return_url »: http://merchant-dns/return-page, « cancel_url »: « http://google.com »
}’
3.2.1 debitCard API query syntax
Bizao debitCard API will response in Json format
The debitCard API will send/response with the URL of Bizao web payment page as below:
Success query response sample
Content-Type: application/json
{
« status »: « 201 »,
« message »: « OK »,
« order_id »: « Transction Id of the merchant”
« state »: « test CM »,
« payment_url »: « https://preproduction-visamc.www.bizao.com/visa-mc/7e07e4d4-a3fd- 47a4-8d1e-360c6647bbab »
}
o status uniquely identifies the transaction. Status of the response
o message: Message of the response
o order_id: Transaction id of the partner
o payment_url: URL of the Bizao payment page where the user will enter his information(,first name, last name,…..)
o State: the correlation-Id sent by the merchant
3.2 Notification flow
Bizao debitCard API also manages a Notification flow. For each user payment transaction, Bizao makes two type of notification:
o B2C-Notif: this category of notification is for the Users/purchaser. For this service, BIZAO is not handling a B2C notification. For a successful payment, the customer may expect an SMS from his bank provider based on the customer service.
o 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. Below a sample of notification content:
{
« meta »: { « type »: »payment « , « source »: « debitCard », « category »: « education »
}
{
“status” : “successful”,
“amount” : “xxxxxx”,
“order-id” : “xxxxxx”,
“currency”: “xxxxx”,
“reference” : “xxxx”,
“country-code”: “xxxxx”,
« date »: « 2020-12-08 10:35:00.0 »,
« state »: « xxxxxxxx », « intTransaction-id »: « xxxxxxxxxxx », « extTransaction-id »: « xxxxxxxxxx »
}
}
4 Get Status API
4.1 Principales
Bizao lets you also check the status of any transaction if you know the order_id, This API manages two categories of parameters:
• Headers: contains the token that helps to authentify the origin of the request
• Body-parameters contains detail of required Id to let the Bizao BackEnd tracking your payment transaction.
4.2 Description
Bizao <getstatus> is a one-time API, below syntax and descriptive
• Api-name: “getStatus”
• URL:
o Preproduction: https://preproduction- gateway.www.bizao.com/debitCard/v2/getStatus/ORDER_ID
o Production: https://api.www.bizao.com/debitCard/v2/getStatus/ORDER_ID
• Method: GET
4.2.1 Getstatus API query syntax
Your query will contain the following Headers:
| Header | Description/Content | Usage |
| Authorization | YOUR_ACCESS_TOKEN | Mandatory |
| content-type | application/json | 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 |
GET / debitCard/v2/getStatus/{order_id} HTTP/1.1 Host: api.www.bizao.com
Authorization: Bearer cb422427-1wo6-3be2-b15b-sff651s7bs4e
country-code: ci
4.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.
The body content will be updated according to each targeted channel: the mandatory incoming parameters will be added accordingly
{
« meta »: {
« type »: « payment »,
« source »: « visa-mc », « category »: « education »
},
« status »: « Successful », « amount »: « 100.00 »,
« order-id »: « EB_1_bizao_test09_11_2020_04 », « currency »: « XOF »,
« reference »: « testref »,
« date »: « 2020-11-09 14:30:04.0 »,
« country-code »: « ci »,
« state »: « test »,
« intTransaction-id »: « f8061034-cc5e-4ba6-b891-c39c64c20f1b », « extTransaction-id »: « 211 »
}
5 Payment status
Below are the statuses that exist in the BIZAO HUB:
– INITIATED: Status to be restored as soon as an initialization action occurs, The partner executes the North request essentially on the web channel without any other action.
– INPROGRESS : Status in progress or waiting for validation
– FAILED : Status in failure of a transaction
– SUCCESSFUL : Status in success of a transaction
– CANCELED : Status to be restored, as soon as a cancellation action occurs. From the payment page the user clicks on the « Cancel Transaction » button on the payment page.
– EXPIRED: Status to be returned, as soon as an abandonment action occurs. In this use case:
o Either the user closes the payment page before the transaction is submitted to the operator’s backend (processing)
o Either the BIZAO Hub will pass the transaction to be abandoned after a series of verification of the status of the transaction « INPROGRESS » or « EXPIRED ».
6 Accepted Cards
Below the list of cards accepted in Bizao debitCard service
| card type | currency |
| Visa | XOF/USD/CDF |
| MasterCard | XOF/USD/CDF |
7 Bizao payment API common error code
| card type | currency | currency | currency | |
| 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 |