Credit Card integration
About this guide
This page explains how to add Credit Cards to your existing Direct API integration. Direct API integration is basically the same for all payment methods, only varying the payment_type_code
and some additional required fields.
If you are not integrated with EBANX Direct API yet, please take a look in this basic guide about it. Are you not sure if EBANX Direct API is the best option for your e-commerce? Please, talk with one of our integration specialists.
Availability
Credit Card integration through Direct API is available to the following countries:
- Argentina;
- Brazil;
- Colombia;
- Chile;
- Costa Rica;
- Dominican Republic;
- El Salvador;
- Egypt;
- India;
- Guatemala;
- Mexico;
- Nigeria;
- Panama;
- Paraguay;
- Peru;
- South Africa;
- Uruguay
What you will need
Prior to starting your integration, please make sure that you have:
- An EBANX Sandbox account. Do not have it? Please sign up for an Sandbox Account here;
- Credit Cards enabled in your EBANX Dashboard.
How it works
To complete Credit Cards integration through EBANX Direct API, please follow the steps below.
Enable Credit Cards in your dashboard
The first step is to check if Credit Cards are active in your EBANX Dashboard.
All set? We can go ahead to next step, otherwise, please get in touch with our integration specialists.
Make sure you have all the mandatory fields in your request
The Credit Card integration is basically the same to all the countries with just some few details and specificities to some of the them, such as required fields or number of installments. Make sure you covered everything in your request.
As a starting point, your request must have the
payment_type_code
set ascreditcard
, as well as the creditcard schema below.The Creditcard schema:
The below fields are mandatory in your request.
Field Description card_number
Credit card number. card_name
Credit card cardholder name. card_due_date
Credit card due date (âvalid thruâ) in the format mm/yyyy. card_cvv
Credit card security code. Authentication fields:
The below fields are recommended for a better 3DS2 and Data-Only Authentication approval:
Field Description name
Customer name. email
Customer email address. address
Customer street name. street_number
Customer street number. city
Customer cityÂŽs name. state
Customer's state. zipcode
Customer zip code. phone_number
Customer phone number with area code. Optional fields:
The below fields are optional in your request.
Field Description instalments
Number of instalments. If you don't know how instalments works, take a look in this tutorial auto_capture
Related with two-stepes payment (Authorization/capture). If true, the payment will be captured automatically by EBANX; if false, the payment will have to be captured by the merchant using the API method capture. caution
Both installments and two-step payments may vary depending on the country. Please, check below the specificities.
Particularities to Credit Card payments to each country
When talking about Latin America, there are some particularities to Credit Card payments to each one of the countries. Please, take a look at those differences below:
- Argentina
- Brazil
- Colombia
- Central America
- Egypt
- India
- Mexico
- Nigeria
- Paraguay
- Peru
- South Africa
- Uruguay
Installments
In Brazil, the accepted number of installments (informed in the field
installments
) can be any value from 1 to 12 to any Credit Card brand but American Express and Elo. When using American Express or ELO, the accepted number of installments can be any value from 1 to 12.Two steps payment
Two-steps payment with credit cards (Authorization and capture, enabled with the parameter
auto_capture
) is fully available in Brazil.The default value to
auto_capture
parameter is true. When set to false, EBANX first issues an authorization (sometimes called as pre-authorization) that will have to be captured later in this step. Authorized-only payments will have statusPE
(pending) until its capture. After the capture, the payment status will be changed toCO
(confirmed).note
Uncaptured payments will be automatically expired.
Complete EBANX Direct API Reference
The complete API reference for the end-point
ws/direct
can be found here. We strongly recommend you to take a look in all the available options.Send your payment request to EBANX
Now, you just need to send your payment request to EBANX, below you can check some examples to the different countries that accepts Credit Cards:
- Argentina
- Brazil
- Colombia
- Chile
- Costa Rica
- Dominican Republic
- El Salvador
- Egypt
- India
- Guatemala
- Mexico
- Nigeria
- Panama
- Paraguay
- Peru
- South Africa
- Uruguay
curl -X POST 'https://sandbox.ebanxpay.com/ws/direct' \-d 'request_body={"integration_key": "your_test_integration_key_here","operation": "request","payment": {"name": "JosĂ© Silva","email": "jose@example.com","document": "853.513.468-93","address": "Rua E","street_number": "1040","city": "MaracanaĂș","state": "CE","zipcode": "61919-230","country": "br","phone_number": "8522847035","payment_type_code": "creditcard","merchant_payment_code": "3ad1f4096a2","currency_code": "BRL","instalments": 3,"amount_total": 100,"creditcard": {"card_number": "4111111111111111","card_name": "JosĂ© Silva","card_due_date": "12/2019","card_cvv": "123"}}}'A successful request will return a JSON response similar to the one below. Credit card payments for merchants with fraud checking enable will have status PE (pending), while for merchants that have fraud checking disabled and
auto_capture
set to true it will have status CO (confirmed).{"payment": {"hash": "59ad5f00945fa382ab051651440826da7701533249b3a475","pin": "045868576","merchant_payment_code": "ecc9be4512a","order_number": null,"status": "CO","status_date": "2017-09-04 14:11:12","open_date": "2017-09-04 14:11:11","confirm_date": "2017-09-04 14:11:12","transfer_date": null,"amount_br": "100.38","amount_ext": "100.00","amount_iof": "0.38","currency_rate": "1.0000","currency_ext": "BRL","due_date": "2017-09-07","instalments": "3","payment_type_code": "visa","details": {"billing_descriptor": ""},"transaction_status": {"acquirer": "EBANX","code": "OK","description": "Sandbox - Test credit card, transaction captured"},"pre_approved": true,"capture_available": false},"status": "SUCCESS"}External Network Tokens
If you want to use tokens that were not issued using EBANX Token API, you can add the following fields to the card or creditcard node on the payment request:
Field Description network_token_pan
The Card PAN related to that network token. network_token_expire_date
The Card Expiration date, related to that network token. network_token_cryptogram
Secure code generated by the card-brand token initiator. Network Token Transaction request JSON payload (CIT)
{"integration_key": "your_test_integration_key_here","operation": "request","payment": {"amount_total": 4550,"country": "cl","currency_code": "CLP","merchant_payment_code": "36165301621","order_number": "P2A414D030","device_id": "2a7d1a1aa99621f7c19b9b5b094c3693e47","creditcard": {"network_token_pan": "5211111111111111","network_token_cryptogram": "network_token_cryptogram_example","network_token_expire_date": "07/2027"},"metadata": {"risk": {"external_customer_id": "d49fa5a573651697b9fd494d60d08321d72f"}}}}If you are sending a recurrent transaction, include the field
network_token_mode
asrecurrent
{"integration_key": "your_test_integration_key_here","operation": "request","payment": {"amount_total": 4550,"country": "cl","currency_code": "CLP","merchant_payment_code": "36165301621","order_number": "P2A414D030","device_id": "2a7d1a1aa99621f7c19b9b5b094c3693e47","creditcard": {"network_token_pan": "5211111111111111","network_token_expire_date": "07/2027","network_token_mode": "recurrent"},"metadata": {"risk": {"external_customer_id": "d49fa5a573651697b9fd494d60d08321d72f"}}}}Capture the payment (required only to two-steps flow)
Capture the payment
Only applied to Two-steps payment
This step is only required if the payment request was done with the parameter
auto_capture
set to false in order to capture an already existing uncaptured payment.This is the second part of the two-steps payment, which in the first step you have already authorized the payment, that is now with PE status (pending), and now we just have to capture it in order to have a CO payment (confirmed).
Here you can check a response example of a payment request done with
auto_capture
set to false.{"payment": {"hash": "5ef38bd200a530d9a4c218b054744cb81f9b25c99d4365aa","pin": "025107300","country": "br","merchant_payment_code": "0x0W27D03-T04","order_number": null,"status": "PE","status_date": null,"open_date": "2020-06-24 17:22:26","confirm_date": null,"transfer_date": null,"amount_br": "100.00","amount_ext": "99.62","amount_iof": "0.38","amount_ext_requested": "100.00","currency_rate": "1.0000","currency_ext": "BRL","due_date": "2020-06-27","instalments": "1","payment_type_code": "visa","details": {"billing_descriptor": "DEMONSTRATION"},"transaction_status": {"acquirer": "EBANX","code": "OK","description": "Accepted","authcode": "87299"},"pre_approved": true,"capture_available": true},"status": "SUCCESS"}In order to capture the payment, you must call the end-point
ws/capture
using thehash
ormerchant_payment_code
(highlighted in the response below) of the previously authorized transaction.Here two examples, with the
hash
andmerchant_payment_code
.curl -X POST -G 'https://sandbox.ebanxpay.com/ws/capture' \-d 'integration_key=your_test_integration_key' \-d 'hash=5ef38bd200a530d9a4c218b054744cb81f9b25c99d4365aa'curl -X POST -G 'https://sandbox.ebanxpay.com/ws/capture' \-d 'integration_key=your_test_integration_key' \-d 'merchant_payment_code=0x0W27D03-T04'A successful request will return a JSON response similar to the one below.
{"payment": {"hash": "5ef38bd200a530d9a4c218b054744cb81f9b25c99d4365aa","pin": "025107300","country": "br","merchant_payment_code": "0x0W27D03-T04","order_number": null,"status": "CO","status_date": "2020-06-24 17:51:08","open_date": "2020-06-24 17:22:26","confirm_date": "2020-06-24 17:51:08","transfer_date": null,"amount_br": "100.00","amount_ext": "99.62","amount_iof": "0.38","amount_ext_requested": "100.00","currency_rate": "1.0000","currency_ext": "BRL","due_date": "2020-06-27","instalments": "1","payment_type_code": "visa","details": {"billing_descriptor": "DEMONSTRATION"},"transaction_status": {"acquirer": "EBANX","code": "OK","description": "Accepted","authcode": "87299"},"pre_approved": true,"capture_available": false},"status": "SUCCESS"}note
Uncaptured payments will be automatically expired.
Complete EBANX Direct API Reference
The complete API reference for the end-point
ws/capture
can be found here. We strongly recommend you to take a look in all the available options.
Getting help
We hope this article was enlightening, but in case weâve failed to take out your doubts you have the following options to keep on seeking for answers:
- If youâre not our partner yet and would like to know more about our prices and conditions please fill our this form and our commercial team will get in touch with you.
- In case youâre already our partner please get in touch with our support team at integration@ebanx.com.