O modelo em uma frase
Uma transação representa uma cobrança e contém um ou mais payments (tentativas de pagamento por um método). Quando um payment é pago, o valor é creditado em uma ou mais carteiras de recebedores, opcionalmente dividido por um split.Glossário rápido
| Objeto | Prefixo do ID | O que é |
|---|---|---|
| Transaction | txn_ | Uma cobrança. Agrupa items e payments. Tem um status derivado dos payments. |
| Payment | pay_ | Uma tentativa de pagar parte (ou todo) o valor por um método (credit_card, pix, boleto). |
| Customer | cust_ | O comprador (pessoa física ou jurídica). |
| Recipient | rec_ | Quem recebe o dinheiro (você e/ou terceiros num marketplace). |
| Split | spl_ | Regra de divisão do valor entre recebedores. |
| Wallet | wlt_ | Saldo virtual de um recebedor, por moeda. |
| Withdrawal | wdr_ | Saque do saldo da carteira para a conta bancária. |
| Refund | rfd_ | Estorno (total ou parcial) de um payment. |
| Chargeback | cbk_ | Contestação do portador junto à adquirente. |
| Card | crd_ | Cartão tokenizado e armazenado para reuso. |
| Webhook | whk_ | Endpoint seu que recebe notificações de eventos. |
No mundo de assinaturas existem mais objetos — Plan (
plan_), Price, Subscription
(sub_) e Invoice (inv_). Veja Assinaturas.Transação × Payment
Uma transação pode ter mais de um payment (pagamento combinado — ex.: parte no cartão, parte no PIX). Ostatus da transação é calculado a partir dos status dos seus payments:
| Status da transação | Quando |
|---|---|
waiting_payment | Aguardando pagamento (ex.: PIX/boleto emitido, ainda não pago). |
paid | Soma dos payments pagos cobre o total. |
refused | Pagamento recusado pela adquirente. |
refunded / partially_refunded | Estornado total/parcialmente. |
chargeback | Em contestação/contestado. |
canceled | Cancelada. |
Recebedor, carteira e saque
- Por padrão, você é o recebedor “owner” e recebe 100% do valor (menos as taxas).
- Em um marketplace, você cria outros recipients e usa split para dividir cada venda.
- O valor recebido entra na wallet do recebedor (com saldo
available,pendingeblocked). - O recebedor pode então solicitar um withdrawal (saque) para a conta bancária.