EBANX Direct allows merchants to accept payments by all payment methods EBANX offers – Boleto Bancário, Bank Transfers and Credit Cards – directly on their domain. Customers can benefit from a smoother user experience as they can complete the checkout without having to leave to store’s front end. There are some requirements to follow before integration EBANX Direct, you can learn them here. The following example will show you how it works.

The customer puts the product in the shopping cart.

1-65e9615f985fa7770b999ce08b29f325

Now the customer goes to the shopping cart and completes the checkout by entering his personal details. In this example the customer pays by Boleto Bancário. For credit card payments there would be fields to enter the corresponding credit card information.

2-b8c2c419d9c22ff4e287b0e734458dd4

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 shown. Please note that EBANX will also send the Boleto Bancário via e-mail.

3-8f6d3f9ebb6b11cae9b32090f6244587

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 information to conclude the payment. Afterwards 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 in the following sections how this can be done.

Please see the diagram below for full mode:

ebanx-direct-2

If Boleto is chosen 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.

ebanx-direct-3

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

1.1. Calling request via HTTP POST

Your stores webserver 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 parameters and details. The JSON expression needs to be included in a parameter called request_body.

{
  "integration_key": "fd29a3b39d8f7bffa31cecfe895236ba5b43683e225f9d4de78ac3bdca7dfb184abfed285cc99d5b13813672e586f9cf9eb8",
  "operation": "request",
  "payment": {
    "merchant_payment_code": 1367237838,
    "amount_total": 100,
    "currency_code": "USD",
    "name": "JOSE SILVA",
    "email": "jose@example.com",
    "birth_date": "12\/04\/1979",
    "document": "88282672165",
    "address": "AV MIRACATU",
    "street_number": "2993",
    "street_complement": "CJ 5",
    "city": "CURITIBA",
    "state": "PR",
    "zipcode": "81500000",
    "country": "br",
    "phone_number": "4132332354",
    "payment_type_code": "boleto"
  }
}

You should pass your store’s payment id or order id as merchant_payment_code. EBANX will save the relation between the hash and the merchant payment code for further reference. It is recommended that you do the same after receiving the hash 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. This is always the case for the Boleto Bancário payment method, and it happens sometimes 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.

The following figure shows how the flow works.

ebanx-checkout-6-1

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 request 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. This happens 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 response, including the payment status:

{
  "payment": {
    "merchant_payment_code":"27",
    "status":"CO",
    "open_date":"2011-03-20 16:14:57",
    "confirm_date":"2011-03-20 06:15:00",
    "receive_date":null,
    "transfer_date":null,
    "amount_br":"182.00",
    "amount_ext":"100.00",
    "currency_ext":"USD",
    "due_date":"2011-03-09",
    "hash":"1cd3ea04dd17c14a0b5d329e2557d8a73cc9",
    "payment_type_code":"itau"
  },
  "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 completely separated. For testing, you have to replace pay in the corresponding service URL with test.

See this example for the request 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 production 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.