Accepting payments in Brazil. 7 chapters and a final quiz.

Chapter 1. Choosing between Pix, parcelado, and boleto.

In Brazil, choosing a payment method is not about picking a button at checkout. You are choosing a cash-flow calendar and a legal remedy. Brazil's three collection rails meet three different needs, and none of them is the default stand-in for the other two. A checkout that offers only Pix “because it's modern” drags down order value. A checkout that offers only cards loses buyers who pay in full. A checkout without boleto loses B2B customers and payments on a due date.

The decision rule in four questions

• Is the product delivered instantly? If so, Pix is structurally risky for the buyer (no protection against non-delivery) and structurally comfortable for the seller, the exact opposite of a card. Adjust your refund policy accordingly, not your rail.
• Does the order value justify credit? Above the average order value in your category, not offering parcelado costs you conversions. Parcelado is not a payment option. It is the most widely used consumer credit product in the country.
• Do I need an enforceable instrument? If the buyer is a company and nonpayment is a real risk, the boleto is the only one of the three that produces an instrument. An unpaid Pix does not exist. There is nothing to collect, just a sale that never happened.
• Who bears the cost of time? With parcelado lojista, you do. With parcelado emissor (com juros, with interest), the buyer does. Switching between the two changes your working capital needs far more than your MDR.

Chapter 2. Wiring up Pix: key, BR Code, txid, and webhook.

In Brazil, the API contract doesn't belong to your PSP. The Banco Central do Brasil publishes the API Pix as an official OpenAPI specification (repository github.com/bacen/pix-api), and the Manual de Padrões para Iniciação do Pix as the QR code standard. Every receiving PSP exposes the same surface: /cob, /cobv, /loc, /pix, /webhook. You can therefore read, test, and build your integration layer before choosing a provider, and switching providers later won't force you to rewrite your business logic. With cards, it's exactly the opposite.

00 02 01                                      Payload Format Indicator
26 58                                         Merchant Account Information
   00 14 br.gov.bcb.pix                       Pix arrangement GUI
   01 36 123e4567-e12b-12d1-a456-426655440000 Pix key (random)
52 04 0000                                    Merchant Category Code (not provided)
53 03 986                                     ISO 4217 currency — 986 = BRL
58 02 BR                                      Country Code
59 13 Fulano de Tal                           Merchant Name
60 08 BRASILIA                                Merchant City
62 07                                         Additional Data Field
   05 03 ***                                  no txid -> "***" by EMV convention
63 04 1D3D                                    CRC16 (polynomial 0x1021, initial value 0xFFFF)

Concatenated payload actually encoded in the QR code:
00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-42665544000052040000
5303986
5802BR
5913Fulano de Tal
6008BRASILIA
62070503***
63041D3D

Static vs. dynamic QR codes and the txid

• Static QR code: you generate it, with no API call. The BCB specifies that creating one is not part of the Pix API. The amount can be left out (the payer enters it). Its transaction ID is EMV object 62-05, capped at 25 characters; if you leave it empty, EMV convention requires the value ***.
• Dynamic QR code: created with PUT /cob/{txid} (immediate payment) or PUT /cobv/{txid} (with a due date). The QR code then carries only a location pointing to a JSON payload hosted by your PSP.
• The Pix API `txid` follows the pattern `[a-zA-Z0-9]{26,35}`: no hyphens, underscores, or periods, and at least 26 characters. A canonical UUID and a short order number are both invalid, and this is the No. 1 cause of rejections in first-time integrations.
• The `txid` must be unique per receiving CPF/CNPJ, and the PSP must enforce that rule: reusing an order ID on a new payment attempt fails.
• `location` values are URLs with no protocol prefix, accessed only over HTTPS after validation, and capped at 77 characters. The path segment indicates the type: none or /cob/ for immediate payment, /cobv/ for a due date, /rec/ for recurring payments.
• `calendario.expiracao` is in seconds and defaults to 86,400; a checkout QR code rarely needs to live longer than an hour. The BCB's official example uses 3600.

{
  "calendario": { "criacao": "2020-09-09T20:15:00.358Z", "expiracao": 3600 },
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25",
    "tipoCob": "cob"
  },
  "status": "ATIVA",
  "devedor": { "cnpj": "12345678000195", "nome": "Empresa de Servicos SA" },
  "valor": { "original": "37.00", "modalidadeAlteracao": 1 },
  "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
  "solicitacaoPagador": "Servico realizado."
}

Chapter 3. Pix Automático: subscriptions without cards.

Pix Automático has been live since June 16, 2025, and every institution that offers transaction accounts to payers must support it. The payer grants an authorization to their PSP, and you then send periodic cobranças recorrentes (recurring charges) that the payer's PSP schedules and settles automatically. You are no longer collecting from a card that expires, but from an account. Adoption remains modest: about 2.87 million transactions worth R$1.2 billion in May 2026, up from 919,000 and R$568.7 million in January 2026 (Finsiders Brasil, June 2026). Treat it as a complementary channel, not a replacement for cards in recurring billing.

The five jornadas correspond to items a) through e) of Regulamento do Pix, art. 11-Q, § 1º, inciso VII, added by Resolução BCB nº 402 of July 22, 2024. Three objects structure the integration. The `Rec` holds the recurrence: purpose of the debit, frequency, and start date. The `SolicRec` is the confirmation request specific to Jornada 1, and the `CobR` is each cobrança recorrente sent on its due date. Frequency is a closed list: SEMANAL, MENSAL, TRIMESTRAL, SEMESTRAL, ANUAL. An “every 45 days” recurrence is not possible.

The retry policy, a field of the recurrence, has only two possible values: NAO_PERMITE or PERMITE_3R_7D. The second allows “up to 3 retries, on different days, within a 7-calendar-day window counted from the settlement date scheduled in the original payment instruction.” That choice is encoded in the recurrence ID: an idRec starts with RR (created in Pix, retries allowed), RN (in Pix, no retries), or CR or CN for the Open Finance equivalents. Two other kinds of retry exist, outside your control. The first, intraday, handles insufficient funds and is up to the payer's PSP alone; the second, also intraday, handles settlement errors. Any adjustment for a payment made after the due date applies only to the next cobrança.

Chapter 4. Parcelado and antecipação: calculating the real cost.

Brazil has two kinds of installment plans, and they must never be confused in an acquiring contract. With parcelado emissor (com juros), the issuer extends the credit: you are paid as for a single-payment sale, and the buyer pays interest to their bank. With parcelado lojista (sem juros), you carry the installments. The customer pays no stated interest, and you are paid one installment at a time, month by month. This mechanism shapes the entire cash cycle of Brazilian retail, and it is also why antecipação de recebíveis, the discounting of your future receivables, exists.

The formula, then the numbers

Sale data
  Gross amount V            = R$ 1,200.00
  Number of parcelas n      = 6 (parcelado lojista, interest-free for the customer)
  Credit MDR                = 2.16%   (BCB average, H1 2025)
  Antecipacao rate a        = 1.5% / month  <-- CALCULATION ASSUMPTION, NOT A
                                              MARKET RATE: replace it
                                              with the rate in YOUR price list

Step 1 — acquiring fee
  MDR       = 1,200.00 x 2.16%                        = R$  25.92
  Net       = 1,200.00 - 25.92                        = R$ 1,174.08
  Parcela   = 1,174.08 / 6                            = R$  195.68
              (due at D+30, D+60, ... D+180)

Step 2 — cost of advancing the entire schedule
  Sum of months waited = n(n+1)/2 = 6 x 7 / 2         = 21 installment-months
  Cost      = 195.68 x 1.5% x 21                      = R$  61.64

Step 3 — total cost and effective rate
  Total cost = 25.92 + 61.64                          = R$  87.56
  Effective rate = 87.56 / 1,200.00                   = 7.30% of gross

Check which discounting convention applies in YOUR contract
(simple or compound, on gross or on net): over 12 parcelas,
the gap between two conventions runs to several points of margin.

This table shows why, in Brazil, negotiating the MDR without negotiating antecipação means haggling over a quarter of the real cost. It also explains the business model of local acquirers. In 2025, Rede reported R$2.058 billion in service revenue and R$3.770 billion in financial intermediation revenue, nearly twice as much. A Brazilian acquirer isn't selling you a fee. It's selling you cash.

Chapter 5. Choosing an acquirer in the world's most competitive market.

Brazil is one of the few markets in the world where acquiring is becoming less concentrated. The combined share of the top four acquirers fell from about 84.8% in Q1 2019 to 72.7% in Q3 2023 (Banco Central do Brasil data reported by the trade press). You are not entering a duopoly with take-it-or-leave-it pricing, but a market where five large-scale players compete for your receivables schedule, plus a long tail of sub-acquirers and wallets. Negotiate accordingly.

A new due diligence question emerged in 2025: who is your provider's PSTI, and what does its license cover? An incident forced the issue. In July 2025, an attack on C&M Software led to the theft of roughly R$800 million from its clients' reserve accounts. This prestador de serviços de tecnologia da informação (IT service provider, or PSTI) connects institutions without direct access to the SPB (Brazil's payment system) and the SPI. The attack vector was not a flaw in Pix but the technical intermediation layer, and social engineering of its staff. The regulatory response came fast. PSTIs are governed by Resolução BCB nº 498/2025, overhauled in January 2026 and then tightened by Resolução BCB nº 547/2026, and their minimum capital is around R$15 million.

Chapter 6. CNPJ, collection setup, FX, and repatriation.

There are only three setups for collecting from Brazilian consumers, and your choice drives everything else: approval rate, access to the rails, taxes, and repatriation time. Make the call before technical integration, never after. Switching setups means redoing the project.

The CNPJ: the identity key for all your collections

• The CNPJ isn't just a tax ID: it's the settlement identifier. It carries the company's Pix key, identifies the recebedor (payee) on every cobrança, owns the receivables schedule, and is the uniqueness key for the `txid`: the Pix API specification requires the txid to be unique per receiving CPF/CNPJ.
• Structure: 14 characters, including an 8-character root that identifies the company. The BCB manual explicitly uses that root to build the Pix Automático idRec when the agent is a payment initiation provider (“the first 8 characters of the CNPJ”).
• A CNPJ can contain letters. The Manual de Padrões para Iniciação do Pix v2.9.0 gives two valid CNPJ key examples: 00038166000105 and 12ABC34501DE35. Any ^[0-9]{14}$ validation in your code, your ERP, or your third-party master data breaks on this format. Fix it before go-live, not after.
• The receiving PSP verifies that you hold the account declared in the cobrança: you can't have a third party collect under your CNPJ without a properly structured sub-acquiring or split-payment arrangement.
• The CPF, its equivalent for individuals, appears on the payer side. A DICT lookup shows the payer, before confirmation, the payee's name, masked CPF or CNPJ, and key, but never the branch or account number. Payee verification is built into the rail: there's no confirmation-of-payee layer to build.

Foreign exchange is governed by Lei nº 14.286 of December 29, 2021, which replaced a framework dating back to 1935. Resolução BCB nº 277 of December 31, 2022 implements it. Two operational points stand out. The purpose of the transaction must be declared up to a threshold of $50,000, with the reporting responsibility shifted to the authorized institution. The regime also explicitly recognizes eFX providers: fintechs not licensed for FX that operate through a contract with an institution that is. This route is the regulatory entry point for most cross-border players in Brazil, which is why you should ask your PSP which authorized institution executes your FX.

Chapter 7. Handling the most common declines.

In Brazil, three families of declines look alike on a dashboard but have nothing in common. An integration error comes from an invalid request, while a settlement rejection comes from a payer who can't pay. A false decline isn't a decline at all: nothing failed, you just didn't see it. Confusing them leads to the worst possible decision: retrying.

• Settlement rejections in Pix Automático: the attempt carries a rejeicao.codigo object taken from the Catálogo de Mensagens do SPI. The 19 possible codes are AB10, AC05, AC06, AM02, AM09, DENC, DS27, DTED, DTNT, FBRD, IRNT, MIDI, MSUC, NIEC, NIPA, NITX, QUNT, RC09, UDEI. Nine of them don't just fail an attempt, they kill the cobrança recorrente: AC05, AM09, DENC, DS27, DTED, MIDI, MSUC, NITX, and RC09. Your retry logic must read the code before scheduling a retry. On those nine, there's nothing to retry: the customer has to subscribe again.
• Card declines: cross-border. In pure cross-border, the approval rate collapses because Brazilian issuers decline foreign transactions en masse. Retrying won't fix this decline; changing your setup will (local entity or merchant of record).
• Card declines: card brand not enabled. Elo accounted for 8.7% of cards issued in Q1 2025 (BCB): not enabling it means structurally turning away part of the cardholder base. Conversely, Hipercard has shut down: no transaction has been approved since July 1, 2025, and its portfolio has migrated to Mastercard. An outdated BIN table produces phantom declines.
• Card declines: parcelado not set up. The number of parcelas and the mode (lojista or emissor) must be provided for in the merchant agreement and sent in the transaction. If they aren't, the sale simply can't be split into installments.
• Acceptance declines: meal voucher (vale-refeição) cards presented on a standard MID. Alelo, Ticket (Edenred), VR, Pluxee Brasil, Caju, and Flash run closed arranjos de pagamento: they require a separate affiliation with their own rules. Their MDR is capped at 3.6% by Decreto nº 12.712/2025.

• False decline No. 1: the webhook that never arrives. The callback SLA is set by each receiving PSP, not by the standard, and PSPs may batch several Pix payments to the same key into a single call. A GET /pix poller and idempotent processing turn this “decline” into mere latency.
• False decline No. 2: the unregistered boleto. Since the Nova Plataforma de Cobrança run by Nuclea, “unregistered” boletos no longer exist: without central registration, payment is impossible. A boleto “rejected at the counter” is almost always a boleto that was never registered.
• False decline No. 3: the unreadable QR code. location values are capped at 77 characters with no protocol prefix, over HTTPS only. A URL that's too long or includes a protocol prefix produces a QR code that apps refuse to open. The payment was never even attempted.
• False decline No. 4: the “lost” Pix. Always reconcile on the EndToEndId (exactly 32 alphanumeric characters), not on the amount: the same amount can arrive several times in the same second, and the txid may be missing from a Pix initiated by entering the key manually.