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

TermDefinition
VPCVirtual Payment Client
3DS3D Secure algorithm
SPService 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:

HeaderDescription/ContentUsage
AuthorizationYOUR_ACCESS_TOKENMandatory
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
langthe 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 acceptedMandatory
content-typeapplication/jsonMandatory
categoryThe category of the merchant.Mandatory

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
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
amountamount to be charged. Decimal value is not acceptedMandatory
return_urlThe URL of the web site where the customer returns when the payment is completedMandatory
cancel_urlThe URL of the web site where the customer returns when the payment is canceled by the customerMandatory
referenceReference to the Merchant NameMandatory 30 char max
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

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:

 

HeaderDescription/ContentUsage
AuthorizationYOUR_ACCESS_TOKENMandatory
content-typeapplication/jsonMandatory
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 typecurrency
VisaXOF/USD/CDF
MasterCardXOF/USD/CDF
7 Bizao payment API common error code
card typecurrencycurrencycurrency
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 API Order Already exists. The order_id must be unique in the system. Only one Token per order_id403 Forbidden
Retour en haut