Skip to content

Localization and Recommended Best Practices




Since 2021 Brazil’s Central Bank is offering a technological platform for initiation, processing, routing and settlement of instant payments using Brazilian Reais, called “SPI - Sistema de Pagamentos Instantâneos”, meaning “System for Instant Payments”. The platform is owned and operated by the central bank itself, and is open to payment providers and financial institutions that want to offer an instant payment method to their customers, called PIX.

PIX quickly became very popular due to its instant nature, ease of use and interoperability, and its popularity keeps growing everyday. It is already considered a crucial “must have” payment method for merchants that deal with Brazilians and it is expected to continue to take market share from other payment methods such as boletos and debit cards.

In order to maximize trust and conversion rates, we offer below some simple recommendations that will help you to provide an easy and familiar experience to Brazilian buyers.

The Payment Experience:

Here are the main ideas that can help understand the PIX experience.

  • Paying with PIX should be a simple and instantaneous task
  • Payment confirmation and transactional emails should be released as soon as possible to the buyer
  • The main elements of the payment screen should be:
  • The QR Code, so the buyer can scan it with a payment app
  • Amount
  • The button to copy the payment code, called “COPIA E COLA”. The code then can be pasted into a payment app (mostly when the payment app and the checkout happen to be on the same device)
  • An “I already paid” button to avoid leaving the buyer waiting if the payment confirmation takes a bit longer to arrive
  • A message letting the buyer know about the destination of the transfer, so they don’t feel distrust when they don’t see the merchant’s name as the destination of the payment.
  • If the payment is confirmed while the payment page is open, or the buyer clicks on the “I already paid” button, show a confirmation page, as suggested further below.

Here is a diagram to understand the overall flow

Ideal Payment Flow

Interface Suggestion:

No matter what type of screen on the checkout page, the important elements can be shown clearly.

Payment Screen

All the elements necessary to build such an interface are delivered in the API response to a PIX request:


  "refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0ZV9lcGFnIiwiZXhwIjoxNTM4NTIxNjc4fQ.BsFj_IwOjITo-ccuNfzsM-g_QTUzH9vSo-GESbWpZ6QJni8Kvm6I1j0Og8xywY_UohhtV4zsCO6Ou7gK_IFuwQ",
  "payment_status": "PROCESSING",
  "payment_token": "59557907-98e7-4457-bfc1-9efc3d0968bb",
  "pix_amount": "190",
  "pix_qr_code": "eNrtXdl2L3bkO8gOfbhcewDOS53k29f7EPbanYPttW8+OLl20ffGTv42ydif7f4McsC/8v/A18OExw=",
  "pix_code": "00020101021226600016IO.EPAG0136D6299C0D-00D0-42F0-AACD-389A105C892B520489995303986540510.005802BR5925ELPL Tecnologia em Pagame6009Sao Paulo6304B250",
  "error": "",

The correspondence to the interface elements are:

Interface Element PT_BR field title Information Source API field (if applicable)
Amount The number as is API pix_amount
QR Code Decoded image of the Base64 Zipped PNG representation of PIX QR code API pix_qr_code
Button to copy the payment code Copia e Cola API pix_code
"I already paid" button Já Paguei - -
A message letting the buyer know about the destination of the transfer O seu pagamento constará no seu extrato como uma transferência para: EPLP Tecnologia em Pagamentos LTDA - -

We think it is a good idea to show the message regarding the destination funds again on the confirmation page. Something like “thank you for your payment” and the message, which in portuguese would be:

"Obrigado! O seu pagamento constará no seu extrato como uma transferência para: EPLP Tecnologia em Pagamentos LTDA"



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.