Skip to content

· 7 min read

Paygrama: a payment, drawn from the inside

Paygrama is a free lab that shows, message by message, what happens in a card payment, Pix, chargeback, MED, Open Finance and account opening. For people new to the field, for product, engineering and support teams, and for anyone who has ever wondered why a purchase was declined.

Payments are invisible

You tap your card, the terminal beeps and says "approved". For the buyer, that's it. Behind it, in less than a second, four or five companies exchanged messages, a bank decided whether to trust you, and a fee was split among players you didn't know existed. Days later, the merchant receives less than they sold, on a date that depends on the kind of purchase.

What happens in less than a second in a card purchase: the terminal asks for approval, the acquirer finds the network, the network routes to the customer's bank, which approves, the receipt comes out and the sale is captured. 0 msTerminalasks for approval21 msAcquirerfinds the network88 msCard networkroutes to the bank326 msCustomer's bankapproves (00)379 msReceipton the terminal775 msCapturesale confirmedillustrative timings from the lab, for a one-off credit purchase
An approved purchase, from the card tap to the capture, as the lab shows it.

Almost nobody sees the whole path. The customer sees the terminal. The merchant sees the statement. Support sees the complaint. Engineering sees its own system's logs. Product sees the approval rate. Each one sees a piece, and conversations between them tend to get stuck exactly where the pieces meet.

Paygrama is a lab for seeing the whole path. You pick a payment, trigger a failure if you want, and follow every message between the participants: who talks to whom, how long it takes, what goes inside the message, where the money goes and what the official rule for that step is. The lab is in Portuguese.

Paygrama screen for choosing the scenario: tabs for card, chargeback, Pix, refund and MED, Open Finance and account opening; purchase amount; channel; selectors for terminal, network, issuer, acquirer and merchant setup; payment type and failures to inject
The first step in the lab: choose the flow, the amount, the channel, the participants and, if you want, a failure. The brands you combine reveal the model, here the four-party one. The lab is in Portuguese.

The questions it answers

The lab covers card payments, chargebacks, Pix (Brazil's instant payments), refunds and MED, Open Finance and account opening. More than the list of flows, what matters are the questions it helps answer.

"Why was my purchase declined if I had credit?" A decline can come from different places. An invalid card number is stopped by the acquirer itself, without even reaching the bank. Suspected fraud is the issuer's call. When a bank is down, the card network answers on its behalf. In the lab, you see where the "no" came from and the code that traveled back, like 51 for insufficient funds.

"Was I charged twice?" When the bank's answer gets lost on the way, the terminal doesn't know whether the purchase went through. So nobody pays twice, it asks to reverse the transaction. Watching that reversal happen explains, in seconds, one of the most common questions support gets.

Paygrama message diagram for a lost response: the issuer approves, the response is lost between network and acquirer, and the acquirer sends a 0400 reversal that releases the hold on the card; on the side, a panel explains the step and cites the ISO 8583 standard
A response lost on the network: the bank approved, but the answer never arrived. Eight seconds later, the acquirer reverses the transaction and the bank releases the held amount. On the side, the step's explanation with sources.

"How much does the merchant get, and when?" Type the sale amount and the lab shows the fee, each participant's share and the payout schedule, with and without early payment. A purchase in ten installments becomes ten payouts, one a month.

Paygrama's Where the money goes panel for a R$ 1,000 purchase in ten installments: the merchant gets R$ 966, interchange R$ 15, network fee R$ 1.50 and acquirer R$ 17.50, with a schedule of ten payouts from D+30 to D+300
A R$ 1,000 sale in ten installments: how much each participant keeps and when each installment reaches the merchant, with the option to get it all early.

"Is a sub-acquirer worth it?" Choose the terminal, the card network, the customer's bank and the acquirer, and the lab shows the model that combination forms. The same R$ 100 purchase costs a different amount and is split differently in each one:

The fee on a R$ 100 one-off credit purchase in four models: four-party, R$ 1.50 goes to the issuer, R$ 0.15 to the network and R$ 1.15 to the acquirer, R$ 2.80 in total; with a sub-acquirer the merchant pays R$ 3.49 and it keeps R$ 0.69; on-us the fee is the same, but issuer and acquirer are in one group; three-party, a single company keeps the R$ 2.80. Four-partyeach role in a companyR$ 2.80With sub-acquirerit sits in the middleR$ 3.49On-usissuer and acquirer in one groupR$ 2.80Three-partyone company keeps it allR$ 2.80issuer (interchange)networkacquirersub-acquirer
Who keeps the fee on a R$ 100 one-off credit purchase, with the lab's illustrative rates.
Paygrama diagram in the sub-acquirer model: the terminal talks to the sub-acquirer, which talks to Cielo, Mastercard and Nubank; on the side, the panel shows the 0100 message fields and explains the ISO 8583 standard
With a sub-acquirer, there is one more participant between the terminal and the acquirer. Each step shows what goes inside the message, useful for people integrating systems.

"I fell for a Pix scam. Now what?" The refund and MED tab shows the actual path: the claim at your bank, the notice to the receiving bank, the block on money still in the account and the return. It also shows why speed matters: only what hasn't been withdrawn comes back.

Paygrama diagram for MED with part of the money already moved: the payer reports the scam, the bank files an infraction notice in DICT, the receiving bank blocks what is left in the suspicious account and returns R$ 87.50 of R$ 250
A Pix scam where part of the money had already left: the receiving bank blocks what was left, and only R$ 87.50 of the R$ 250 comes back.

"The customer doesn't recognize the purchase. Does the merchant lose the money?" The chargeback tab shows it from start to finish: the customer's claim, the debit to the merchant, the defense with evidence and the decision, which changes with the kind of purchase.

"What happens when I let an app see my bank data?" Open Finance shows the consent, the redirect, what is shared and for how long, plus a Pix started from another app.

"Why does opening an account need a selfie, and sometimes take a while?" Account opening shows the document and face checks, the Central Bank's opt-out registry, anti-money-laundering checks and what changes for a politically exposed person.

Paygrama diagram of account opening at a payment institution: sign-up, opt-out registry check, document photo, selfie with liveness check, ID and list checks, customer flagged as politically exposed, risk assessment, enhanced approval, account creation, report to the Central Bank's registry and Pix key registration
Opening an account for a politically exposed person: after the selfie and the checks, the institution assesses the risk and asks for enhanced approval before creating the account.

Who it's for

  • People new to payments. The map that used to take weeks of conversations and whiteboards is available from day one, to explore at your own pace.
  • Product. Understanding where declines come from, what each model costs and where the customer experience can break helps you decide with more confidence.
  • Engineering. Each step shows the message's technical fields, the timings and the failures that are hard to reproduce in a test environment, like a lost response or an issuer that's down.
  • Support and operations. Explaining why a purchase was declined, why a refund takes time or how MED works gets easier with the flow on screen.
  • Leadership and business. How the money is split and how the models differ become visible without reading a specification.
  • Students and the curious. Payments are infrastructure everyone uses every day and almost no one sees. The lab is a way to look inside.

How to use it day to day

A few ways that work well:

  • When onboarding new people, as a script: start with an approved purchase, then the failures, then chargebacks and Pix.
  • To explain an incident, reproducing the closest case and showing where the flow broke.
  • In support training, with the questions customers ask most.
  • To discuss a product decision, comparing models and channels side by side, like terminal, Tap on Phone, payment link and digital wallet.
  • To send to someone, downloading the flow as a video and dropping it into a chat or a presentation.

Next to the lab there is a general payments guide, split into the same parts, with figures, a glossary and sources, to read calmly after seeing the flow.

Home page of Paygrama's general guide, How payments work, with parts for card, chargeback, Pix, refund and MED, Open Finance and account opening
The general guide, split into the same parts as the lab, with links back and forth between reading and the flow.

Reliable, but illustrative

A tool that teaches can't teach things wrong. So every step has an "About this step" block, with the explanation and a link to the official source: the card message standards, the Pix Regulation, Central Bank resolutions, the card networks' rules and the Open Finance Brasil specifications. What couldn't be confirmed was left out, or went in with a note to check the current rule.

Amounts, timings and fees are illustrative, to show the logic, not the numbers of any specific company. Brands appear only as names, to explain each one's role.

How it was made

Paygrama was built with the help of AI, using Claude Code, just like amardoar and Soccer Deal. What the AI didn't replace were the years of working in payments that defined what to show, and checking every fact against its source.

Next steps

I want to keep adding flows and failures, and I'm thinking about how to bring the same cases to people building payment systems, so they can test their own systems. If you work in the field and miss a flow, or found something to fix, let me know.

The lab is at fghisi.com.br/paygrama, free and with no sign-up.