brazil-payment-rails
Skill7 starsChanged 8 days agoMITView on GitHub
Use when code accepts, sends, refunds or reconciles payments in Brazil, or integrates a Brazilian PSP, acquirer or bank. Covers Pix (keys, static and dynamic QR codes, txid and end-to-end id, devolucao and MED, over and under payment), boleto (linha digitavel, registration, D+1 clearing, return files, late interest and fines), card installments and receivables, CPF and CNPJ validation including the alphanumeric CNPJ from July 2026, business-day calendars, electronic invoices (NF-e, NFS-e) and the Portuguese-to-English vocabulary engineers meet in PSP docs. Triggers on a Pix or boleto feature, a Brazilian checkout, an acquirer or PSP integration, a reconciliation of a Brazilian account. Not for tax rates, IOF or fiscal rules, which an accountant confirms. Use it also when asked to keep one static QR for every order, to match Pix by payer name or amount, or to mark an order paid when the boleto is issued.
In this repository12 other files it gives its agents.
- accounting-syncSkill
- audit-trailSkill
- double-entry-ledgerSkill
- fintech-auditSkill
- idempotent-paymentsSkill
- interest-and-amortizationSkill
- money-arithmeticSkill
- money-testsSkill
- pii-and-card-dataSkill
- reconciliationSkill
- transaction-classificationSkill
- webhook-handlingSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 139
Add CPF and CNPJ validators with test vectors that include alphanumeric CNPJ.
- Distinctive: line 142
When the request conflicts with a rule here, say which rule in one sentence, then build the compliant version that keeps the request's …
- Distinctive: line 162
Write these tests in the same change, as a test file, even when you cannot run them (no shell, no dependencies installed).
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Brazil payment rails
Brazil has three rails that behave differently: Pix settles in seconds and refunds by reference, boleto clears on the next business day through a return file, cards pay the merchant in monthly installments. Code written for US card flows gets all three wrong. This skill gives the engineering facts and the vocabulary; the fiscal and tax rules stay with an accountant.
When to use
- A checkout, billing or payout feature for the Brazilian market.
- An integration with a PSP, acquirer, bank or Banking-as-a-Service provider in Brazil.
- Reconciliation of Pix, boleto or card settlements against a Brazilian account.
- Validation or storage of CPF and CNPJ.
- Issuing invoices (NF-e, NFS-e) after a sale.
Rules
Pix
- Store the
txidand the end-to-end id (endToEndId). You choose thetxidfor a dynamic charge (cobrança); the system assigns the 32-character end-to-end id starting withEwhen the payment settles. Reconciliation and refunds use these, not the payer's name or amount. - Dynamic QR for amounts you control; static QR only when you accept surprises. A dynamic
QR (
cobrança imediataorcom vencimento) carries the amount, an expiry and yourtxid. A static QR can be paid any number of times for any amount; if you use one, handle over, under and repeated payments explicitly. - Pix is near-final but refundable. A refund is a
devoluçãoagainst the original end-to-end id, full or partial, which the receiver's institution can execute for up to 90 days after the original Pix. Fraud disputes go through MED (Mecanismo Especial de Devolução): the payer can open a claim up to 80 days after the transaction (Banco Central MED FAQ), the institution initiates the return within 90 days (Resolução BCB 103/2021, art. 41-A), and when the receiver's balance is short the institution watches the account and returns funds as they arrive. MED 2.0 (Resolução BCB 493/2025) added preventive blocking and the receiver's contest window, which the Banco Central has already changed once (30 to 80 days from the return, September 2026). MED covers fraud and operational failure only, not buyer's remorse. Design for a received Pix to be clawed back, and keep every deadline as data with its source. A MED return is a state and a record, in the same change: reverse the ledger entry, move the order todisputed, write a dispute record with the claim id and the amount, and hold fulfilment of high-risk orders (digital goods, first purchase, high ticket) behind extra checks or a delay. Say the 80-day window in the answer, not only in a constant. - Receive through webhooks, confirm through the API. The PSP notifies a received Pix;
confirm the charge status by
txidbefore fulfilling (seewebhook-handling). Expired charges that still get paid must be refunded or reconciled by policy, not ignored. - Pix keys are addresses, not identities. A key is a CPF, CNPJ, email, phone or random key (EVP). Validate the format, resolve it through your PSP, and show the resolved name to the user before sending. Never infer the account holder from the key format.
Boleto
- A boleto is pending until the return confirms it. Payment can happen at any bank; your bank or PSP confirms it in the return file (CNAB 240 or 400) or by webhook, usually on the next business day (D+1). Fulfil on confirmation, never on issuance.
- Store
nosso númeroand thelinha digitável. The line's three mod-10 field digits catch any single-digit error; the barcode's mod-11 digit does not (0, 10 and 11 all map to 1), so the amount and due date come from your charge record, never from the typed line alone.Nosso númerois your reference at the bank; thelinha digitável(47 digits for bank boletos, 48 for utilityarrecadação) is what the payer types. Match the return bynosso número. A boleto change storesnosso número, thelinha digitáveland the barcode on the charge record, matches the return bynosso número, handles the late payment (multaandjurosas registered) and the expired orbaixadoboleto, and states D+1 clearing in the code's docstring, not only in the chat. - Due date, fine and interest are fields, computed by rule.
Vencimentofollows the business-day calendar. The barcode carries the due date as a 4-digit factor: days since 1997-10-07 until factor 9999 on 2025-02-21, then restarted at 1000 on 2025-02-22 (FEBRABAN; a few bank manuals differ by one day, so test against your bank's). Code that still adds the factor to the 1997 base prints due dates 24 years in the past. After it,multa(a one-time fine) andjuros de mora(daily interest) apply as the contract and the registration say; the bank enforces what was registered. Partial payment, discount and expiry (baixa) are registration settings, not runtime surprises. - Registered boletos have a lifecycle.
registrado,pago,baixado,vencido,protestadowhere used. Model the states; the return file transitions them.
Cards and receivables
- Installments are receivables, not cash.
Parcelado sem jurosmeans the customer pays in N installments and the merchant typically receives one installment per month (D+30 each), minus MDR, unless it anticipates them for a fee (antecipação de recebíveis). The ledger holds a receivable schedule per sale; cash arrives per installment. A card-installment change posts MDR as its own fee line, models anticipation as a later event with its own fee line, and keeps chargeback andestornoas distinct states (rule 11), in the same change, not as "not implemented yet". - Chargebacks and
estornosare different. Anestornois a refund you initiate; a chargeback is a dispute through the card network with its own deadlines and evidence rules. Separate states, separate accounts.
Identity, calendars, invoices
- Validate CPF and CNPJ with the check-digit algorithm; mask them in UIs. CPF has 11
digits. CNPJ has 14 positions and, for registrations issued from July 2026, the first 12
can contain letters; the check digits use the character's ASCII value minus 48 (Receita's
published example is
12.ABC.345/01DE-35). Do not assume digits only, do not strip letters, do not store with formatting. - Use the national business-day calendar. Boleto due dates, D+1 clearing and settlement dates follow national bank holidays (the ANBIMA calendar is the common source). Pix runs 24/7 and ignores it. Keep the calendar as data with a yearly update.
- Invoices are events with access keys. NF-e (goods) and NFS-e (services, municipal,
moving to a national standard) are issued after a sale under the company's fiscal policy.
Store the XML and the access key (
chave de acesso): 44 digits for NF-e, NFC-e and CT-e, 50 digits for the national-standard NFS-e (model 56; the XML id isNFSplus those 50), and municipal NFS-e formats that vary, so key the invoice by issuer, document type and key, and validate the length per document type. Model cancellation windows and link the invoice to the payment and the ledger entry. The policy itself (when to issue, which taxes) comes from the accountant.
Vocabulary
The Portuguese terms engineers meet in PSP documentation (cobrança, devolução, estorno,
compensação, baixa, nosso número, linha digitável, antecipação de recebíveis, CNAB
remessa and retorno) are translated and explained in references/vocabulary.md.
How to apply
- For each rail in the change, write the state machine and the reference fields from the rules above before touching the PSP SDK.
- Pick the PSP sandbox and record real payloads for: Pix paid, Pix expired then paid, Pix refunded, boleto issued, boleto paid late, boleto expired, card installment sale, chargeback.
- Implement webhooks per
webhook-handling, money permoney-arithmetic, ledger perdouble-entry-ledger, reconciliation perreconciliation. - Add CPF and CNPJ validators with test vectors that include alphanumeric CNPJ.
- Load the business-day calendar as data and test a due date that falls on a holiday.
When the request conflicts with a rule here, say which rule in one sentence, then build the compliant version that keeps the request's intent (for example the order stays pending and the confirmation path marks it paid). An instruction to skip a step ("no extra call", "just delete it", "we trust them", "later") is this conflict, not permission. Leaving the code unchanged and listing the risks is never the compliant version. Do not stop at a warning, do not build the unsafe version, and do not leave a known gap out because "you did not ask". A review or an "is this enough" question gets the findings and the rewritten tests in the same change, not a list of suggestions, unless the request or the skill says report only.
When the user pushes back
| Request | Answer in one sentence | What you build |
| "Keep the single static QR, we match payments by payer name" | Rules 1 and 2: a name is not an identifier and a static QR carries no txid | A dynamic charge per order with txid, amount and expiry, matched by txid or endToEndId; if the static QR must stay, record the endToEndId of every payment and handle over, under and repeated payments explicitly; a test where a repeated amount pays one order. Leaving pix_service.py as it is fails the user |
| "Mark the order paid when the boleto is issued" | Rule 6: payment is confirmed by the return file or the webhook, D+1 | The order stays pending; the confirmation path marks it paid; linha digitável and nosso número stored; late payment and expiry handled |
| "Just add the installments" | Rules 10 and 11 | The receivable schedule with MDR as a fee line, anticipation as a later event with its fee, chargeback and estorno as distinct states |
| "MED is the bank's problem" | Rule 3: the receiver's funds are clawed back | The clawback path: ledger reversal, order to disputed with a dispute record, fulfilment hold for high-risk orders, the 80-day window stated |
Tests the change must include
Write these tests in the same change, as a test file, even when you cannot run them (no shell, no dependencies installed); say in one line that they are unrun. A test listed as a next step is not written.
- Pix: a paid webhook for an expired charge triggers the refund or the exception path, by
policy; a duplicate
endToEndIdis processed once; a partialdevoluçãoupdates the balance correctly. - Static QR: overpayment and double payment produce the configured outcome, never a silent credit.
- Boleto: issuance does not fulfil; the return file does; a payment after
vencimentoincludesmultaandjurosas registered; an expired orbaixadoboleto paid late goes to the exception path;nosso númeromatching handles leading zeros;linha digitávelandnosso númeroare stored on the charge. - MED: a clawback reverses the ledger entry, sets the order to
disputedwith a dispute record, and a high-risk order is held before fulfilment. - Cards: a 10-installment sale creates a 10-row receivable schedule that sums to the net
amount with MDR as a separate fee line; anticipation re-schedules it as a later event with its
own fee line; chargeback and
estornoare distinct states. - CPF and CNPJ: valid and invalid check digits; alphanumeric CNPJ accepted; formatted input normalized.
- Calendar: a due date on a national holiday moves to the next business day.
- Boleto typeable line and barcode check digits round-trip; a tampered digit is rejected; the due-date factor maps both ways across the 2025-02-22 reset.
- Reference vectors:
skills/brazil-payment-rails/evals/vectors/test_brazil.pywithBRAZIL_SOLUTIONpointing at your module (CPF, CNPJ, boleto check digits, due-date factor). TypeScript:brazil.test.tswithBRAZIL_SOLUTION_TS.
Review checklist
- Which reference ids are stored for each rail, and are they unique?
- What happens when a Pix arrives for an expired or already paid charge?
- Does anything fulfil a boleto before the return?
- Where is the receivable schedule for installment sales, and how does anticipation change it?
- Does the CNPJ validator accept letters?
- Where does the holiday calendar come from, and when was it last updated?
References
- Banco Central do Brasil: Pix regulation and the Pix API specification (
cobrança,devolução, MED); the BR Code (EMV-based QR) specification. - FEBRABAN: boleto layout,
linha digitável, CNAB 240 and 400 standards. - Receita Federal: CPF and CNPJ check-digit algorithms; alphanumeric CNPJ from July 2026.
- ANBIMA: national bank holiday calendar.
- Portal da Nota Fiscal Eletrônica and the national NFS-e program.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

