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;
  • El Salvador;
  • Guatemala;
  • Mexico;
  • Panama;
  • Paraguay
  • Peru;
  • 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.

    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. 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_eci": "05",
    "threeds_cryptogram": "AAIBAkl0NwmHglFBAXQ3AAAAAAA",
    "threeds_xid": "AAIBAkl0NwmHglFBAXQ3AAAAAAA",
    "threeds_version": "2",
    "threeds_trxid": "AAIBAkl0NwmHglFBAXQ3AAAAAAA"
    }
    }
    }'

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

  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 ou this form and our comercial 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 Jefferson Diefenbach
On this page