The model in one sentence
A transaction represents a charge and contains one or more payments (payment attempts via a method). When a payment is settled, the amount is credited to one or more wallets belonging to recipients, optionally divided by a split.Quick glossary
| Object | ID prefix | What it is |
|---|---|---|
| Transaction | txn_ | A charge. Groups items and payments. Has a status derived from its payments. |
| Payment | pay_ | An attempt to pay part (or all) of the amount via a method (credit_card, pix, boleto). |
| Customer | cust_ | The buyer (individual or business). |
| Recipient | rec_ | Who receives the money (you and/or third parties in a marketplace). |
| Split | spl_ | A rule for distributing the amount among recipients. |
| Wallet | wlt_ | A recipient’s virtual balance, per currency. |
| Withdrawal | wdr_ | A payout from the wallet balance to a bank account. |
| Refund | rfd_ | A full or partial reversal of a payment. |
| Chargeback | cbk_ | A dispute filed by the cardholder with the acquirer. |
| Card | crd_ | A tokenized card stored for reuse. |
| Webhook | whk_ | Your endpoint that receives event notifications. |
In the subscriptions world there are additional objects — Plan (
plan_), Price, Subscription
(sub_), and Invoice (inv_). See Subscriptions.Transaction × Payment
A transaction can have more than one payment (combined payment — e.g., part on a card, part via PIX). The transactionstatus is calculated from the statuses of its payments:
| Transaction status | When |
|---|---|
waiting_payment | Awaiting payment (e.g., PIX/boleto issued but not yet paid). |
paid | The sum of settled payments covers the total amount. |
refused | Payment declined by the acquirer. |
refunded / partially_refunded | Fully or partially reversed. |
chargeback | Under dispute / disputed. |
canceled | Canceled. |
Recipient, wallet, and withdrawal
- By default, you are the “owner” recipient and receive 100% of the amount (minus fees).
- In a marketplace, you create additional recipients and use split to distribute each sale.
- The received amount is credited to the recipient’s wallet (with
available,pending, andblockedbalances). - The recipient can then request a withdrawal to their bank account.