EBANX Checkout is EBANX’s most popular integration method. It is working neatless with online stores of any size and is integrated into the shopping cart. Please see the following example of how EBANX Checkout works.

The customer selects EBANX as a payment method within your store’s checkout.

1-23feff2a64384413f56637c0570d2152

Afterwards the customer is redirected to EBANX’s domain to complete the payment. First he will select a payment method, and then enter his name, contact and payment details. You can prefill most of the fields, if you pass them in the request.

ebanx-checkout-1-1024x652

Finally a confirmation will be shown and the customer is redirect to your store.

ebanx-checkout-3-1024x652

1. Using EBANX Account

The checkout can be easily integrated by making an API call, followed by a redirect to our checkout flow.

Afterwards you just need a script which treads the update notifications sent by our servers.

Please see the diagram below. There are three interactions with EBANX: request, input redirect, query.

ebanx-checkout-4-1

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-checkout-5-1

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

1.1 Calling request via http GET

Your stores webserver makes a server-to-server call to the EBANX server. The given example includes the minimum number of parameters needed. Please see the API Reference for further parameters and details.

https://api.ebanx.com/ws/request?
  integration_key=YOUR_SECRET_KEY
  &payment_type_code=_all
  &currency_code=USD
  &amount=100
  &merchant_payment_code=ABC
  &name=Marcos+Silva
  &email=marcos@silva.com

There is also the option to use the sub-account in the request. The following is an example of request:

https://api.ebanx.com/ws/request?
  integration_key=YOUR_SECRET_KEY
  &payment_type_code=_all
  &currency_code=USD
  &amount=100
  &merchant_payment_code=ABC
  &name=Marcos+Silva
  &email=marcos@silva.com
  &sub_acc_name=Merchant+Test+Name
  &suba_acc_image_url=https://www.colourbox.com/preview/9155263-store-front.jpg

For both requests, you will receive a response which includes a JSON object like this:

{
  "status": "SUCCESS",
  "payment": {
    "merchant_payment_code":"ABC",
    "status":"OP",
    "open_date":"2011-05-01 13:40:01",
    "amount_br":182,
    "amount_ext":100,
    "currency_ext":"USD",
    "due_date":"2011-05-09",
    "hash":"1998bff11bf7b3185e8f2af113ee3fb1fa4c9",
    "payment_type_code":"itau"
  },
  "redirect_url": "https://api.ebanx.com/ws/?hash=1998bff11bf7b3185e8f2af113ee3fb1fa4c9"
}

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.

The other important parameter is the redirect_url. After getting the response from request, you have to redirect the customer to the URL.

1.2. Redirecting the customer to the EBANX Checkout pages

https://api.ebanx.com/ws/?hash=1998bff11bf7b3185e8f2af113ee3fb1fa4c9

On the following pages that the customer will see, he will enter all the payment details, like CPF (Brazilian residents registration number), name and address. After the customer is done, he will be redirected to your store’s website.

1.3. Calling query via https get after customer return to store

When the customer returns to your store’s site you must query EBANX for the payment status. This is done making a server-to-server call using the query service. You will receive the hash as get parameter when the customer returns to your store.

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

In this case the payment has the status “CO”, which means it is confirmed and you process with shipping the goods.

Please see this table for possible payment status:

CodeStatusDescription
OPOpenThe payment was recently opened.
PEPendingThe customer has already completed the checkout process and the payment is waiting to be cleared.
COConfirmedThe payment is confirmed
CACanceledThe payment was canceled. This usually happens when the customer did not complete checkout.

Note: If the customer has chosen Boleto Bancário as payment method he will get the Boleto from EBANX by e-mail, but you can also choose to display it to the customer on your checkout confirmation page.

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

Afterwards your script should make a call to EBANX’s queryservice. 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 payin the corresponding service URL with test.

See this example for the request service:

Test:

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

Production:

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

Please keep in mind that the integration keys are not interchangable, 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.