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;
  • Guatemala;
  • Mexico;
  • Nigeria;
  • Panama;
  • Paraguay;
  • Peru;
  • South Africa;
  • Uruguay

What you will need

Prior to 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. Credit Cards enabled in your EBANX Dashboard.

How it works

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

  1. 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.

  2. 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.

    FieldDescription
    card_numberCredit card number.
    card_nameCredit card cardholder name.
    card_due_dateCredit card due date (“valid thru”) in the format mm/yyyy.
    card_cvvCredit card security code.

    Optional fields

    The below fields are optional in your request.

    FieldDescription
    installmentsNumber of installments. If you don't know how installments works, take a look in this tutorial
    auto_captureRelated 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.

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

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

  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": "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.

    note

    Combo cards are a special phenomenon in Brazil, having both Credit and Debit functions in the same card, that can be enabled for one or both functions.

    When the merchant doesn’t separate the Credit Card and Debit Card options at checkout, and the card is a Combo, the merchant can choose whether to send this payment as credit or debit.

    If the transaction fails, the merchant can choose to submit a new request, with another payment type.

    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 Fernando Pankiewicz Gomes
On this page