Boleto with Direct API

About this guide

This page explains how to add Boleto 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.

What you will need

Before starting your integration, please make sure that you have:

1. An EBANX Sandbox account. That's not the case? Please sign up for an Sandbox Account here;
2. Boleto enabled in your EBANX Dashboard.

How it works

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

1. Enable Boleto

   Boleto availability may vary depending on your contract. So the first step is to check if it is active in your EBANX Dashboard.

   All set? We can go ahead to next step, otherwise, please get in touch with our integration specialists.

2. Call the /ws/direct API to get the boleto link (server-side)

   Boleto works as a voucher, so you will need to redirect your customer to a page containing it. To get this link, you just need to call the end-point ws/direct (server-side) with the following required fields:

   • Operation: Must be request;
   • Payment type code: Must be boleto;

   Customer data:

   • Customer name;
   • Customer e-mail;
   • Customer document;
   • Customer address;
   • Customer street number;
   • Customer city;
   • Customer state;
   • Customer zip-code;
   • Customer phone number

   Charge info:

   • Unique merchant payment code;
   • Currency code;
   • Total amount to be charged;

   Optionally, you can set a due date to boleto using the parameter payment.due_date in the format dd/mm/yyyy. It can be more than three days only when payment currency is BRL (Brazilian Real), and your merchant account has this feature enabled. The due date is based on the local time of the country that the payment is generated.

   caution

   Please note the boleto may not be cancelled right after the expire date (3 days for USD) in order to have a proper compensation period specially when the boleto is paid close to a public holiday. Also, if the expire date is on holiday or weekend, we need to always consider the next business day.

   Check the example:

   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": "boleto",

   "merchant_payment_code": "a92253f29db",

   "currency_code": "BRL",

   "amount_total": 100

   }

   }'

   A successful request will return a JSON response like the one below. The boleto link will be in the parameter payment.boleto_url, and the boleto barcode will be the value of payment.boleto_barcode.

   {

   "payment": {

   "hash": "59ad5dd18a6d5ba0e24327c2ba92a730115a80bd58b3baa5",

   "pin": "655158605",

   "merchant_payment_code": "af461f512c1",

   "order_number": null,

   "status": "PE",

   "status_date": null,

   "open_date": "2017-09-04 14:06:09",

   "confirm_date": null,

   "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-08",

   "instalments": "1",

   "payment_type_code": "boleto",

   "boleto_url": "https://sandbox.ebanxpay.com/print/?hash=59ad5dd18a6d5ba0e24327c2ba92a730115a80bd58b3baa5",

   "boleto_barcode": "34191760071302120372714245740007572710000010038",

   "boleto_barcode_raw": "34195727100000100381760013021203721424574000",

   "pre_approved": false,

   "capture_available": null

   },

   "status": "SUCCESS"

   }

   info

   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. Redirect customer to the returned url

   Redirect your customer to the URL returned in the parameter boleto_url. Your customers will see an interface like this:

   

   At this point you have a pending payment in your EBANX Dashboard.

   caution

   Alternatively, you can simply deliver the barcode number to your customer.

4. Wait for the payment

   After Boleto got payed, it will take sometime to EBANX get informed by Boleto's issuer bank. As soon as we get the confirmation, payment status is modified from pending to confirmed.

   If your customers don't pay the Boleto, payment will be automatically canceled.

   info

   Boleto has an expiration date (that will be configured by you in the parameter payment.due_date). After this date, customer will have to issue a new boleto. Optionally, you can generate a new Boleto and send to your customers through your EBANX Dashboard.

note

If you're interested in using Pix Cobrança on Boleto or Instant Boleto, you don't need to make any changes to the integration. Just contact our integration specialists and they'll enable it for you.

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.