EBANX Direct Guide

Version: 2

A simple guide with all LatAm countries and payment methods.

The Direct API of EBANX allows you to accept payments by all payment methods – Boleto Bancário, Bank Transfers and Credit/Debit Cards – directly on your domain.

Your customers will benefit from a smoother user experience as they can complete the checkout without the need to leave the store’s front end.

There are some requirements to follow before making the integration that you can learn here.

Please pay attention to the following example and see how it works. Also, here’s a guide of EBANX Direct

First, the user must choose which product he wants, click on it:

Then, the customer has to click on “Add to cart” to select and add the product to the shopping cart.

From there, the user can click at the “cart icon” to see the cart and what it contains:

After “Proceed to checkout” it is essential to complete all the checkout fills entering the personal customer details.

In the example below the purchase will be paid with Boleto Bancário. For credit card payments, additional fields will be shown to enter the corresponding credit card information.

After the confirmation, the Boleto is shown to the customer within the store’s front end. Alternatively, you can also show a link to where the Boleto can be demonstrated. Please note that EBANX will also send the Boleto Bancário via email.

1. Using EBANX Direct

The use of Direct API needs to be implemented in the store’s checkout process. After the customer has verified the shopping cart and provided his personal & shipping information, he should input the data to conclude the payment. Afterward, you can show a confirmation page according to the payment status.

For some payment methods the status may change, and you will receive status change notifications from our server. You will also see the following sections how this can be done.

Please see the diagram below for full mode:

Visual flow of the Direct Requests and reponses.

If the customer chooses Boleto as a payment method, the flow is a little different. Although the user gets the boleto as an email from EBANX, we highly recommend that you also display it to your customer when he returns to your store after checkout.

See the following example to have an idea of how it works under the hood.

1.1. Calling request via HTTP POST

Your store’s web server makes a server-to-server call to the EBANX server. The given example includes the minimum number of parameters needed for a boleto request. Please see the Direct API Reference for further settings and details. For more details about how to create a payment using different payment methods from all countries that EBANX supports, click here.


curl -X POST 'https://sandbox.ebanx.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": "boleto",
        "merchant_payment_code": "a92253f29db",
        "currency_code": "BRL",
        "amount_total": 100
    }
}'

Please note the JSON expression needs to be included in a parameter called request_body. Also, you should pass your store’s payment id or order id as merchant_payment_code. EBANX will save the relationship between the hash and the merchant payment code for further reference. We recommend that you do the same after receiving the confirmation from the EBANX server.

In case of a failure the response will look like this:

{
  "status": "ERROR",
  "status_code": "DA-1",
  "status_message": "Field payment.merchant_payment_code is required"
}

2. Merchant Notifications

Due to the nature of some payment methods, payments will not always be confirmed instantly, like Boleto Bancário payment method. It also, happens with the online methods like TEF, due to customer behavior (closing the browser) or connection problems among the merchant website, EBANX and other involved financial institutions.

The merchant will be notified by any status changes happening this way. Some may happen a few minutes after the checkout, others a couple of days later.

To receive the status change notifications correctly, you need to configure the URL of the script in the merchant area.

Learn how the flow works.

The status Notification Flow

2.1. Example of the merchant notification

As mentioned you need to register the URL of your server script in the merchant area. It should be something like this: https://www.yourstore.com/ebanx/status_change

Every time a status changes, the EBANX server will make a POST request to the registered URL. This application will only have one parameter, which includes the hashes for all updated payments.

hash_codes=1998bff11bf7b3185e8f2af113ee3fb1fa4c9,c6f60b67e8a076f659af8f1d6569ab1d6b600

Afterwards, your script should make a call to EBANX’s query service. The same way like after the customer returns to your store after checkout.

https://api.ebanx.com/ws/query?
  integration_key=YOUR_KEY
  &hash=1998bff11bf7b3185e8f2af113ee3fb1fa4c9

The EBANX server will send a JSON object as a response, including the payment status:


{
  "payment": {
    "hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
    "pin": "253639240",
    "country": "br",
    "merchant_payment_code": "9dwdwdw1e31c4c234",
    "order_number": null,
    "status": "CO",
    "status_date": "2018-04-19 20:57:07",
    "open_date": "2018-04-19 20:56:42",
    "confirm_date": "2018-04-19 20:57:07",
    "transfer_date": null,
    "amount_br": "100.38",
    "amount_ext": "100.00",
    "amount_iof": "0.38",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2018-04-22",
    "instalments": "1",
    "payment_type_code": "itau",
    "pre_approved": false,
    "capture_available": null,
  },
  "status": "SUCCESS"
}

3. Testing and going live with EBANX

The integration with EBANX includes a test account so that you can test all the functionalities in a test environment. Therefore you will first receive a test account. When you are ready for production, you can contact your EBANX integration representative to do your homologation and send you the production credentials. Alternatively, you can also send an e-mail to integration@ebanx.com

Please keep in mind that EBANX’s testing and production environment are entirely separated. For testing, you have to replace pay in the corresponding service URL with the test.

See this example for the requested service:

Test:

https://sandbox.ebanx.com/ws/direct

Production:

https://api.ebanx.com/ws/direct

Please keep in mind that the integration keys are not interchangeable, i.e., a product key will not work when used with a test URL and vice-versa.

After you receive your production key, your test key will remain valid for further testing, ok?