Version: current

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 as creditcard, 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.
`threeds_force`	Related to the 3DS request in the Ebanx API Payment as an optional field, if true, the payment will be processed with authentication, indicating that your payment page can handle 3DS transactions.
`threeds_data_only`	In relation to the 3DS request in the Ebanx API Payment as an optional field, if the request is true, the payment will be processed using Data Only authentication, provided it is available. This indicates that your payment page is capable of handling 3DS transactions. Please note that the "threeds_force" field must also be set to true.
`threeds_redirect_url`	In the 3D Secure (3DS) process, Ebanx redirects the cardholder to a specific URL provided by the merchant after authentication. This merchat´s threeds_redirect_url is essential for continuing the transaction and includes the results of the 3DS process.

note

After the payment request with threeds_force as "true" and the other 3DS parameters Ebanx will return the field threedsecure.threeds_redirect_url to the merchant to continue the 3DS process with the cardholder. That URL contains the necessary tools to capture device information and will redirect the cardholder to the URL link provided by the merchant in the payment request.

note

The 3D Secure (3DS) Data-Only flow is designed to enhance the security and authorization rates of online transactions without requiring user authentication, providing a frictionless experience for the customer. In this model, merchants submit the same additional data required by 3DS 2.0 directly to the card schemes (e.g., Mastercard, Visa), and the schemes include their risk data within the authorization message, helping issuers make more informed decisions.

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:

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 status PE (pending) until its capture. After the capture, the payment status will be changed to CO (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:

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",
            "threeds_force": true,
            "threeds_data_only": true,
            "threeds_redirect_url": "https://www.merchant.com/3ds-response"
        }
    }
}'

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"
}

A successful request with threeds_force": true will return a JSON response similar to the one below. Card payments for merchants with 3DS enabled will have status PE (pending), with the threedsecure.threeds_redirect_url field to redirect your customers.

{
  "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": ""
    },
    "pre_approved": true,
    "capture_available": false,
    "threedsecure": {
      "threeds_redirect_url": "https:\/\/ui-elements.ebanx.com\/three-d-secure?auth_token=aGFzaD02NzFiYjMwM2VmZDmdGVuYW51PUNST1NTX0JPUkRFUiZtb2RlPVBST0RVQ1RJT04mY291bnRyeT1jbA==",
      "has_threeds": true,
      "status": "PENDING_AUTHENTICATION",
      "threeds_attempts": [],
      "threeds_result": null
    }
  },
  "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 as recurrent

{
    "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 the hash or merchant_payment_code (highlighted in the response below) of the previously authorized transaction.
Here two examples, with the hash and merchant_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.

Credit Card integration#

About this guide#

Availability#

What you will need#

How it works#

Enable Credit Cards in your dashboard

Make sure you have all the mandatory fields in your request

The Creditcard schema:#

Authentication fields:#

note

note

Optional fields:#

caution

Particularities to Credit Card payments to each country#

Installments#

Two steps payment#

note

Complete EBANX Direct API Reference

Send your payment request to EBANX

External Network Tokens#

Capture the payment (required only to two-steps flow)

Capture the payment#

Only applied to Two-steps payment

note

Complete EBANX Direct API Reference

Getting help#

Credit Card integration

About this guide

Availability

What you will need

How it works

The Creditcard schema:

Authentication fields:

Optional fields:

Particularities to Credit Card payments to each country

Installments

Two steps payment

External Network Tokens

Capture the payment

Getting help