Cashin visa Api
1 introduction
Bizao gateway gives you access to a large panel of services through REST APIs.
Credit Card is one of these services.
This service is based on a <creditcard> northbound API that aggregates and covers multiple countries, processor, and card type.
Right now, our credit card API manages as card type, visa card prepaid and covers below processor types:
- gtp
- Visa direct
This API lets you target the right country, processor, channel, et card type by using the dedicated Header for that.
The onboarding process of partners is out of the scope of this document. Our integration will be in charge to manage this step. The access credentials will be provided the same way.
2 Your access token
You can call our API generate token with the credentials received in the onboading process to get an ACCESS_TOKEN. Please contact our integration team at [email protected] for more the details.
The ACCESS_TOKEN is generated 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.bizao.com/#/get_access_token
Once your integration finished, BIZAO will generate your production access and our support team [email protected] will take the over.
3 Partner provisioning
Before using our credit card APIs, you should provide some informations as data provisioning. You can find below all data you should share with our integration team.
- Your name, should be the name of your structure
- Your email, should be the notification email address
- Your phone number, should be the phone number linked to your activity card
- Your card serial number, should be the accountId of your activity card
- Your fees type, should be the type of fees you want configure(fixe or variable)
- Your bankId, should be your bank identification which allow us to verify if a card is issued by you
- You should also provide your minimum and maximum amount for transactions
4 Credit card APIs
These APIs allow you to manage cards through Bizao Hub based on the information provided in your request.
These APIs manage three categories of parameters:
- Headers: contains information letting Bizao to route your traffic by country, processor, channel and card-type you target.
- Body-parameters contains detail on your request: beneficiary details, amount, currency, the country where the transaction was originated etc…
Note that this section could be empty for some APIs - Static-parameters: this category of parameters covers all parameter that are static per partner 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 reloading process.
Bizao <creditcard> is a JSON/Rest based API.
Below are the syntax and descriptive:
• Api-name: “creditCard/v1”
• Based URL: https://api.bizao.com/
o Live: https://api.bizao.com/
o Preproduction: https://preproduction-gateway.bizao.com
4.1 FundsTransfer
This operation allows you to do transfer between two cards through Bizao Hub based on the informations provided in your request.
fundsTransfer 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) (for instance: <sn> is the country-code for Senegal. | Mandatory |
| card-processor | The type of targeted processor, visa direct in this project. | Mandatory |
| card-type | The type of the card we will manage. (Prepaid visa card in this project) | Mandatory |
| lang | Mandatory | |
| content-type | application/json | Mandatory |
The body of your query will manage parameters below:
| Parameter | Description | Usage |
| reference | (string) the partner reference created in Bizao Hub, must be unique for each partner | Mandatory |
| order_id | (string) identifies this create transfer request. This field SHOULD be present. IT MUST BE UNIQUE FOR THE SYSTEM. | Mandatory 30 char max |
| amount | (integer) amount to be charged. | Mandatory |
| recipientAccountNumber | (string) The accountId of the recipient | Mandatory 16 char max |
| Last4Digits | (string) last4Digit of the recipient’PAN | Mandatory, 4 char max |
| recipientCurrencyCode | (string) Currency code of the recipient | Mandatory, 3 char max |
fundsTransfer query sample
curl –location –request POST ‘https://preproduction-gateway.bizao.com/creditCard/v1’ \
–header ‘Authorization: Bearer your access token’ \
–header ‘country-code: ci’ \
–header ‘card-type: visa-prepaid’ \
–header ‘card-processor: gtp’ \
–header ‘content-type: application/json’ \
–header ‘lang: fr’ \
–header ‘Cookie: route=1668502331.444.5709.656383|81ae3a9a04c06b83bdb4bb4311fcd72d’ \
–data-raw ‘{
“order_id”: “cc-123456794”,
“reference”: “ecobankci”,
“recipientAccountNumber”: “12704204”,
“amount”: 2000,
“recipientCurrencyCode”: “XOF”,
“last4Digits”: “8562”,
“localTransactionDateTime”: “2022-11-02T09:33:06”
}’
{
“reference”: “ecobankci”,
“status”: “Successful”,
“amount”: 2000.00,
“fees”: 400.00,
“correlation”: “sharefeesecobankci”,
“localTransactionDateTime”: “2022-11-16T08:10:46.953”,
“order-id”: “cc-123456794”,
“intTransaction-Id”: “d3052428-60ef-402d-9131-2810e1d23668”,
“extTransaction-Id”: “695799490”
}
Getstatuts API
4.2 Get Status
The getstatus use only headers and query string parameters (no body parameter for this API). It can be used to know the status of a transaction. This API will return the transaction data through your orderId used in your request.
• URL: https://api.bizao.com/creditcard/v1/getstatus
• Method: GET
Getstatus query syntax
The 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) (for instance: <sn> is the country-code for Senegal. | Mandatory |
| card-processor | The type of targeted processor, visa direct in this project. | Mandatory |
| card-type | The type of the card we will manage. (Prepaid visa card in this project) | Mandatory |
| content-type | application/json | Mandatory |
The query string parameters:
| Parameter name | Description | Usage |
| order_id | The parter orderId | Mandatory |
Getstatus query call sample
curl –location –request GET ‘https://preproduction-gateway.bizao.com/creditCard/v1/getStatus/your_order_id’ \
–header ‘Authorization: Bearer 72eea75f-61fd-3ca2-b5f2-c3bb7be31ac1’ \
–header ‘card-processor: gtp’ \
–header ‘Cookie: route=1668502331.444.5709.656383|81ae3a9a04c06b83bdb4bb4311fcd72d’
{
“order-id”: “cc-123456794”,
“reference”: “ecobankci”,
“activityCardId”: “12704201”,
“countryCode”: “ci”,
“endUserCountryCode”: “ci”,
“endUserCardId”: “Q1zD9bHS9n7xe0fThhe5IKQec8q13g10uKSXOTu95Us=”,
“amount”: “2000.00000”,
“fees”: “400.00000”,
“currency”: “XOF”,
“transactionType”: “DEBIT”,
“date”: “2022-11-16T08:10:46.953”,
“statusDescription”: “Fund transfer request”,
“status”: “Successful”,
“intTransaction-id”: “d3052428-60ef-402d-9131-2810e1d23668”,
“extTransaction-Id”: “695799490”,
“refundTransaction-id”: “”,
“cardProcessor”: “GTP”
}
4.3 Cardholder details
This service is used to find a customer card details (customer name, card status ect.) by accountId or the primary account number depending the card processor you used. With this API, you can know if a card is active, inactive, or expired.
cardholderdetails 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) (for instance: <sn> is the country-code for Senegal. | Mandatory |
| card-processor | The type of targeted processor, visa direct in this project. | Mandatory |
| card-type | The type of the card we will manage. (Prepaid visa card in this project) | Mandatory |
| lang | Mandatory | |
| content-type | application/json | Mandatory |
The body of your query will manage parameters below:
| Parameter name | Description | Usage |
| customerId | (string) The PAN or the accountId of the consumer | Mandatory 16 char max |
cardholderdetails query sample
curl –location –request POST ‘https://preproduction-gateway.bizao.com/creditCard/v1/cardHolderDetails’ \
–header ‘Authorization: Bearer 72eea75f-61fd-3ca2-b5f2-c3bb7be31ac1’ \
–header ‘country-code: sn’ \
–header ‘card-type: visa-prepaid’ \
–header ‘card-processor: gtp’ \
–header ‘content-type: application/json’ \
–header ‘Cookie: route=1668593264.876.5843.616839|81ae3a9a04c06b83bdb4bb4311fcd72d’ \
–data-raw ‘{
“customerId”: “12345678”
}’
{
“firstName”: “string”,
“middleName”: “string”,
“lastName”: “string”,
“preferredName”: “string”,
“country”: “string”,
“mobilePhoneNumber”: “string”,
“alternatePhoneNumber”: “string”,
“emailAddress”: “string”,
“cardStatus”: “string”, AC=Active ,EX=Expired, IA=Inactive, DE=Deactivated, LC=Lost/Stolen
“cardHash”: “string”,
}
4.4 Get Balance
This service is used to request the balance and currency of a customer account.
getBalance query sample
curl –location –request POST ‘https://preproduction-gateway.bizao.com/creditCard/v1/getBalance’ \
–header ‘Authorization: Bearer 72eea75f-61fd-3ca2-b5f2-c3bb7be31ac1’ \
–header ‘country-code: sn’ \
–header ‘card-type: visa-prepaid’ \
–header ‘card-processor: gtp’ \
–header ‘content-type: application/json’ \
–header ‘Cookie: CookieConsentPolicy=0:1; LSKey-c$CookieConsentPolicy=0:1; route=1668165084.076.5843.605664|81ae3a9a04c06b83bdb4bb4311fcd72d; route=1668593264.876.5843.616839|81ae3a9a04c06b83bdb4bb4311fcd72d’ \
–data-raw ‘{
“accountId”: “12704201”
}’
{
“status”: “Success”,
“balance”: “6824.0”,
“currencyCode”: “XOF”
}
4.5 Reports API
The reports api use only Headers and Query string parameters (no body parameter for this API). It can be used to retrieve all your transactions through an accountId, start date and end date, reference or currency.
Report api query syntax
The 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) (for instance: <sn> is the country-code for Senegal. | Mandatory |
| card-processor | The type of targeted processor, visa direct in this project. | Mandatory |
| card-type | The type of the card we will manage. (Prepaid visa card in this project) | Mandatory |
| content-type | application/json | Mandatory |
The body parameters:
| Parameter | Description | Usage |
| accountId | integer customer account identification | optional |
| reference | String Partner reference | optional |
| currency | String Transaction currency | optional |
| date_start | integer The beginning date. Format: YYYY-MM-DD (1985-11-02) | Mandatory |
| Date_end | integer The end date. Format: YYYY-MM-DD (1985-11-02) | Mandatory |
Report api call sample
curl –location –request POST ‘https://preproduction-gateway.bizao.com/creditCard/v1/transactiondata’ \
–header ‘Authorization: Bearer 72eea75f-61fd-3ca2-b5f2-c3bb7be31ac1’ \
–header ‘country-code: sn’ \
–header ‘card-type: visa-prepaid’ \
–header ‘card-processor: gtp’ \
–header ‘content-type: application/json’ \
–header ‘Cookie: route=1668593264.876.5843.616839|81ae3a9a04c06b83bdb4bb4311fcd72d’ \
–data-raw ‘{
“date_start”:”2022-11-08″,
“date_end”:”2022-11-10″,
“accountId”:””,
“reference”:”ecobankci”,
“currency”:”XOF”
}’
{
“meta”: {
“report_name”: “GTP Transactions Report”,
“page_num”: 0,
“page_size”: 10,
“record_count”: 0,
“total_record_count”: 0,
“total_page_count”: 0,
“record_max_limit”: false
},
“headers”: {
“status”: “Status”,
“amount”: “Amount”,
“orderId”: “Order Id”,
“currency”: “Currency”,
“reference”: “Reference”,
“date”: “Date”,
“countryCode”: “Country Code”,
“fees”: “Fees”,
“userCardId”: “User Card Id”,
“intTransactionId”: “Int Transaction Id”,
“extTransactionId”: “Ext Transaction Id”,
“statusDescription”: “Status Description”,
“transactionType”: “Transaction Type”
},
“data”: [
{
“status”: “Successful”,
“amount”: “2000.00000”,
“order-id”: “cc-123456792”,
“currency”: “XOF”,
“reference”: “ecobankci”,
“date”: “2022-11-10T11:00:16.789”,
“countryCode”: “ci”,
“fees”: “500.00000”,
“endUserCountryCode”: “ci”,
“endUserCardId”: “HjXU9TViubCdzP/Itgct0Q==”,
“intTransaction-Id”: “143170ad-bfd3-4624-b555-25d4d85fc16e”,
“extTransaction-Id”: “695798495”,
“refundTransaction-Id”: null,
“statusDescription”: “Fund transfer request”,
“transactionType”: “DEBIT”
},
{
“status”: “Successful”,
“amount”: “2000.00000”,
“order-id”: “cc-123456793”,
“currency”: “XOF”,
“reference”: “ecobankci”,
“date”: “2022-11-10T13:01:52.731”,
“countryCode”: “ci”,
“fees”: “500.00000”,
“endUserCountryCode”: “ci”,
“endUserCardId”: “HjXU9TViubCdzP/Itgct0Q==”,
“intTransaction-Id”: “5b5a82cd-8c25-48aa-954d-3fe4cb798d84”,
“extTransaction-Id”: “695798574”,
“refundTransaction-Id”: null,
“statusDescription”: “Fund transfer request”,
“transactionType”: “DEBIT”
}
]
}
| 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) (for instance: <sn> is the country-code for Senegal. | Mandatory |
| card-processor | The type of targeted processor, visa direct in this project. | Mandatory |
| card-type | The type of the card we will manage. (Prepaid visa card in this project) | Mandatory |
| content-type | application/json | Mandatory |
| Parameter | Description | Usage |
| accountId | integer customer account identification | Mandatory |
| mobilePhoneNumber | String Mobile phone number linked to the card | Mandatory |
| newCardStatus | String [ Active, Inactive, LostOrStolen ] | Mandatory |
| last4Digits | String last4Digit of the recipient’PAN | Mandatory |
curl –location –request POST ‘https://preproduction-gateway.bizao.com/creditCard/v1/updateCardStatus’ \
–header ‘Authorization: Bearer 72eea75f-61fd-3ca2-b5f2-c3bb7be31ac1’ \
–header ‘country-code: ci’ \
–header ‘lang: en’ \
–header ‘card-type: visa-prepaid’ \
–header ‘card-processor: gtp’ \
–header ‘content-type: application/json’ \
–header ‘Cookie: route=1666583965.687.3142.968267|81ae3a9a04c06b83bdb4bb4311fcd72d; route=1668593264.876.5843.616839|81ae3a9a04c06b83bdb4bb4311fcd72d’ \
–data-raw ‘{
“mobilePhoneNumber”:”225105623423″,
“newCardStatus”:”active”,
“last4Digits”:”2553″,
“accountId”:”12704201″
}’
Content-Type: application/json
{
“status”: “success”,
“response”: “updated”
}
4.7 BankIdVerify
This API allows you to verify if a card given in parameter by its accountId is issued by the bank through the bankId provisioned in our side during the onboading process.
bankIdVerify API query syntax
The 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) (for instance: <sn> is the country-code for Senegal. | Mandatory |
| card-processor | The type of targeted processor, visa direct in this project. | Mandatory |
| card-type | The type of the card we will manage. (Prepaid visa card in this project) | Mandatory |
| content-type | application/json | Mandatory |
The body parameters:
| Parameter | Description | Usage |
| accountId | integer customer account identification | Mandatory |
| reference | String Partner reference | Mandatory |
bankIdVerify query sample
curl –location –request POST ‘https://preproduction-gateway.bizao.com/creditCard/v1/bankIdVerify’ \
–header ‘authorization: Bearer 72eea75f-61fd-3ca2-b5f2-c3bb7be31ac1’ \
–header ‘card-processor: gtp’ \
–header ‘card-type: visa-prepaid’ \
–header ‘content-type: application/json’ \
–header ‘country-code: sn’ \
–header ‘lang: fr’ \
–header ‘Cookie: route=1668593264.876.5843.616839|81ae3a9a04c06b83bdb4bb4311fcd72d’ \
–data-raw ‘{
“accountId”: “12704201”,
“reference”: “ecobankci”
}’
Content-Type: application/json
{
“status”: “success”,
“response”:” true”
}
4.8 Configuration fees API
This service allows you to create your own fees for the transaction. Fees can be fixe or variable depending on the data provisioned for you on our side. You can also get all your fees configured by your reference.
4.8.1 Fixe fees
fixeFees API query syntax
| Parameter | Description | Usage |
| reference | String Partner reference | Mandatory |
| currency_code | String Transaction currency | Mandatory |
| country_code | String 2 characters code of the country you target ( use this norme : ISO 3166 alpha 2 country code) (for instance: <sn> is the country-code for Senegal. | Mandatory |
| fees_type | String Can take Fixe or Variable | Mandatory |
| fees_amount | integer amount of fees, you want to configure | Mandatory |
| fees_percentage | String percentage, you want to apply in amount of transaction as fees | optional |
fixeFees query sample
curl –location –request POST ‘http://preproduction-gateway.bizao.com/creditCard/v1/fees’ \
–header ‘Authorization: Bearer 72eea75f-61fd-3ca2-b5f2-c3bb7be31ac1’ \
–header ‘content-type: application/json’ \
–header ‘Cookie: route=1668601303.419.5707.359564|81ae3a9a04c06b83bdb4bb4311fcd72d’ \
–data-raw ‘{
“reference”: “ecobankci”,
“country_code”: “ci”,
“currency_code”: “XOF”,
“fees_type”: “FIXED”,
“fees_amount”: “400”,
“fees_percentage”: “”
}’
{
“reference”: “ecobankci”,
“country_code”: “ci”,
“currency_code”: “XOF”,
“fees_type”: “FIXED”,
“fee_amount”: 400
}
4.8.2 Variable fees
variableFees API query syntax
The body parameters:
| Parameter | Description | Usage |
| reference | String Partner reference | Mandatory |
| currency_code | String Transaction currency | Mandatory |
| country_code | String 2 characters code of the country you target ( use this norme : ISO 3166 alpha 2 country code) (for instance: <sn> is the country-code for Senegal. | Mandatory |
| fees_type | String Can take Fixe or Variable | Mandatory |
| fees_amount | integer amount of fees, you want to configure | Mandatory |
| fees_percentage | integer percentage, you want to apply in amount of transaction as fees | optional |
| from_amount | integer the beginning of the interval | Mandatory |
| to_amount | integer the end of the interval | Mandatory |
variableFees query sample
curl –location –request POST ‘http://preproduction-gateway.bizao.com/creditCard/v1/fees’ \
–header ‘Authorization: Bearer 72eea75f-61fd-3ca2-b5f2-c3bb7be31ac1’ \
–header ‘content-type: application/json’ \
–header ‘Cookie: route=1668601303.419.5707.359564|81ae3a9a04c06b83bdb4bb4311fcd72d’ \
–data-raw ‘{
“reference”: “ecobankci”,
“country_code”: “ci”,
“currency_code”: “XOF”,
“fees_type”: “VARIABLE”,
“fees_amount”: “500”,
“fees_percentage”: “”,
“from_amount”: 10001,
“to_amount”: 50000
}’
{
“reference”: “ecobankci”,
“country_code”: “ci”,
“currency_code”: “XOF”,
“fees_type”: “VARIABLE”,
“fee_amount”: 500,
“from_amount”: 10001,
“to_amount”: 50000
}
4.8.3 Get fees partner
getFees query sample
curl –location –request GET ‘http://preproduction-gateway.bizao.com/creditCard/v1/fees’ \
–header ‘Authorization: Bearer 72eea75f-61fd-3ca2-b5f2-c3bb7be31ac1’ \
–header ‘content-type: application/json’ \
–header ‘reference: ecobankci’ \
–header ‘Cookie: route=1668601303.419.5707.359564|81ae3a9a04c06b83bdb4bb4311fcd72d’
[
{
“id”: 4,
“country_code”: “ci”,
“currency_code”: “XOF”,
“fees_type”: “VARIABLE”,
“fee_amount”: 400.00000,
“from_amount”: 2000.00000,
“to_amount”: 10000.00000,
“created_at”: “2022-11-10T16:01:22”,
“created_by”: “[email protected]”,
“updated_at”: “2022-11-10T16:01:22”,
“updated_by”: “[email protected]”
},
{
“id”: 5,
“country_code”: “ci”,
“currency_code”: “XOF”,
“fees_type”: “VARIABLE”,
“fee_amount”: 500.00000,
“from_amount”: 10001.00000,
“to_amount”: 50000.00000,
“created_at”: “2022-11-16T13:20:03”,
“created_by”: “[email protected]”,
“updated_at”: “2022-11-16T13:20:03”,
“updated_by”: “[email protected]”
}
]