Skip to content

Localization and Recommended Best Practices




Boleto is one of the most popular payment methods in Brazil. It is a push method which consists of an invoice-like document issued by a financial institution (usually a bank), identified by a unique numeric code. A boleto contains the amount, due date and the beneficiary account linked to it.

Boletos issued by any bank can be paid using any banking apps, ATMs or directly in a bank teller, making it a very interoperable payment method.

After a boleto is paid, it takes 1 to 2 business days for the bank to send the payment confirmation. There are no chargebacks and eventual refunds require a bank transfer to the payer's account.

The best user experience using boletos is not hard to achieve no matter what kind of device your customer is using. If you are integrating directly to our API, please use this guidelines to provide a frictionless checkout flow to your customers:

  1. Always email the original document to the buyer because:

    1. the buyer should store it for recordkeeping

    2. If it is not possible to pay it during the checkout, the buyer can go back to it to pay it later

  2. During the checkout, offer a clean interface with the relevant info (picture below)

    1. Amount

    2. Due Date

    3. Tax ID

    4. Boleto number

    5. An easy way to copy the boleto number (see suggestion below)

    6. A barcode of the boleto number (if the buyer is paying it in an ATM or using another device to pay it)

Interface Suggestion:

Boleto documents as they are issued by Financial Institutions are not ideal for a good ecommerce experience, so some optimization is necessary.

This is what an original boleto looks like:

image alt text

This is what a good user experience could look like:

image alt text

In order to build this interface you will need to use the fields provided by our API and some information from your own system:


"refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZF69Q",
"boleto_amount": "150",
"payment_status": "PROCESSING",
"payment_token": "59557907-98e7-4457-bfc1-9efc3d0968bb",
"gateway_order_id": "ORD-RE1NVX7W7BRP",
"boleto_html": "eNrtXdl2L3bkO8gOfbhcewDOS53k29f7EPbanYPttW8+OLl20ffGTv42ydif7f4McsC/8v/A18OExw=",
"boleto_code": "00190.00009 01014.051005 00000.787176 7 72370000001000",
"error": "",
"customer_id": "CUS-2HH3DZBFTSVI",
"boleto_duedate": "2015-07-28"

So, the correspondence is:

Interface Element PT_BR field title Information Source API field (if applicable)
Amount The number as is API response "boleto_amount"
Order Pedido Merchant System -
Due date Vencimento API response "boleto_duedate"
Tax ID CPF/CNPJ/CEI Merchant System -
Boleto Number NĂºmero do Boleto API response "boleto_code"
Barcode none API "boleto_code"
  • The barcode should be generated locally using the boleto code. SVG is the recommended format.

  • The "boleto_html" field contains the original boleto and should be emailed to the buyer.

  • The landscape position on mobile devices should show a bigger barcode so they can be easily scanned by ATMs.