Version: current

Debit Card integration

About this guide

This page explains how to add Debit 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

Debit Card integration through Direct API is available to the following countries:

  • Argentina;
  • Brazil;
  • Chile;
  • Colombia;
  • Costa Rica;
  • Dominican Republic;
  • El Salvador;
  • Egypt;
  • India;
  • Guatemala;
  • Mexico;
  • Nigeria;
  • Panama;
  • Paraguay;
  • Peru;
  • South Africa;
  • Uruguay

What you will need

Before starting your integration, please make sure that you have:

  1. An EBANX Sandbox account. Do not have it? Please sign up for an Sandbox Account here;
  2. Debit Cards enabled in your EBANX Dashboard.

How it works

To complete Debit Cards integration through EBANX Direct API, please follow the steps below.

  1. Enable Debit Cards in your dashboard

    The first step is to check if Debit 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.

  2. Make sure you have all the mandatory fields in your request

    The Debit 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. Make sure you covered everything in your request.

    Important!

    For payments with Debit Cards in Brazil, 3DS 2.0 is required. Check this guide for all the details.

    As a starting point, your request must have the payment_type_code set as debitcard, as well as the card schema below.

    The Card schema:

    The below fields are mandatory in your request.

    FieldDescription
    card_numberDebit card number.
    card_nameDebit card cardholder name.
    card_due_dateDebit card due date (“valid thru”) in the format mm/yyyy.
    card_cvvDebit card security code.

    Authentication fields:

    The below fields are recommended for a better 3DS2 and Data-Only Authentication approval:

    FieldDescription
    nameCustomer name.
    emailCustomer email address.
    addressCustomer street name.
    street_numberCustomer street number.
    cityCustomer cityÂŽs name.
    stateCustomer's state.
    zipcodeCustomer zip code.
    phone_numberCustomer phone number with area code.
    threeds_forceRelated 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_onlyIn 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_urlIn 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.

    Particularities to Debit Card payments to each country

    When talking about Latin America, there are some particularities to Debit Card payments to each one of the countries.

    When talking about South Africa, there are some particularities to Debit Card payments to consider.

    Please, take a look at those differences below:

    3DS 2.0

    Debit cards transactions in Brazil require additional authentication, through 3DS 2.0. Check this guide for all the details.

    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.

  3. 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 Debit 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": "debitcard",
    "merchant_payment_code": "3ad1f4096a2",
    "currency_code": "BRL",
    "instalments": 1,
    "amount_total": 100,
    "card": {
    "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. Debit 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": "1",
    "payment_type_code": "debitcard",
    "details": {
    "billing_descriptor": ""
    },
    "transaction_status": {
    "acquirer": "EBANX",
    "code": "OK",
    "description": "Sandbox - Test debit 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": "1",
    "payment_type_code": "debitcard",
    "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"
    }

  4. 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": "debitcard",
    "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": "debitcard",
    "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.
Edit this page
Last updated on by FlavioCostaeSilva
On this page