Boleto

Boleto, a popular payment method in Brazil, is a bank slip that allows customers to make payments either online or in person at authorized locations, such as banks, ATMs, or convenience stores. EBANX supports Boleto as a payment method, making it a valuable option for e-commerce platforms and other digital businesses targeting Brazilian customers.

Requirements

• API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
• Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters. See Direct API Guide for more info.

How it works

• Generate Boleto - Create a Boleto via the API, setting the amount, due date, and customer details.
• Display to customer - Provide the customer with the Boleto slip, barcode, or link for payment.
• Customer pays - The customer pays the Boleto at a bank, ATM, or through their banking app using the barcode.
• Confirmation - Payment confirmation may take up to 3 business days.

Instructions

Follow the steps below.

1. Select your environment

   Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

   SandboxProduction

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

2. Define your parameters

   Boleto operates as a voucher-based payment method, so you’ll need to redirect your customer to a page displaying the voucher details. To obtain this redirection link, call the ws/direct endpoint with the required parameters.

   
   

   Defining API parameters

   You must provide required parameters for payment requests. These parameters ensure successful completion of transactions.
   
   

   Essential parameters

   • payment.payment_type_code - Specifies the payment method to be used for the transaction.
   • payment.currency_code - Three-letter code of the payment currency.
   • payment.amount_total - Total amount to be charged.

   
   

   Additional parameters

   • EBANX Integration Key - Used to authenticate and authorize API requests.
   • Customer Information
     • Includes details such as the customer name, email, address and document number (Depends on the requirements of the payment method or local regulations).
     • While not mandatory for all countries or payment methods, providing this information can enhance security and increase the likelihood of successful processing.
   • Additional Context - Extra data for specific methods or countries.

   
   

   To learn more about API parameters, please refer to the

   API Reference Guide chevron_right

   At the API Reference Guide, select Brazil and Boleto from the dropdown menues.

3. Sample request

   Use the following example to initiate a request.

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/direct' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "your_test_integration_key_here",
       "operation": "request",
       "payment": {
         "name": "José Silva",
         "email": "jose@example.com",
         "document": "853.513.468-93",
         "country": "br",
         "payment_type_code": "boleto",
         "merchant_payment_code": "a92253f29db",
         "currency_code": "BRL",
         "amount_total": 100
       }
     }'

4. Sample response

   A successful request returns a response similar to the example below.

   • Boleto voucher URL - See payment.boleto_url parameter.
   • Boleto barcode - See payment.boleto_barcode parameter.
   • At this stage, the payment status is marked as pending (PE).
   
   

   {
     "payment": {
       "hash": "59ad5dd18a6d5ba0e24327c2ba92a730115a80bd58b3baa5",
       "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"
   }
   
   
   At this stage, the payment will appear as pending (PE) in your

   EBANX Dashboardchevron_right

5. Show voucher using redirect URL (Option 1)

   Redirect your customer to the URL provided in the boleto_url parameter. Once redirected, they will be able to view or print the barcode.

   Sample voucher:

   

6. Show barcode number directly (Option 2)

   Alternatively, you can directly provide the customer with the barcode number from the boleto_barcode parameter.

   Guidelines

   • Clearly indicate that this is a Boleto payment.
   • Use a modal, iframe or webview to display the barcode within your site (or app).
   • Include a button for easy copying, allowing customers to send the link to themselves if needed.
   • Display the payment amount prominently.
   • Display the expiration date.
   • Render the barcode with high contrast.
   • Provide clear instructions to make the customer comfortable with the payment process.

7. Monitor payment for status changes

   Notifications

   • EBANX will send a notification whenever a payment status changes.

   • Make sure your system is set up to receive notifications from EBANX for any changes in payment status.

   • Learn more about Payment Notificationschevron_right

   Status

   • After receiving a notification, retrieve the payment status.

   • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). Each Boleto comes with an expiration date, which you can set using the payment.due_date parameter. After this date passes, the customer will need to generate a new Boleto to complete the payment. If the customer does not complete the payment before the expiration date, the status will automatically change to cancelled (CA).

   • Learn more about Retrieving Payment Statuschevron_right

8. Congratulations!

   You have succesfully integrated Boleto.

   For more information, refer to the

   Direct API reference guidechevron_right

info

To enable Pix Cobrança on Boleto or Instant Boleto, contact our integration specialists to activate it for you. These are optimized forms of Boleto that allow for faster confirmation times, leveraging the speed of Pix without completely bypassing the traditional Boleto workflow.

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.