El modelo en una frase
Una transacción representa un cobro y contiene uno o más payments (intentos de pago por un método). Cuando un payment es pagado, el valor se acredita en una o más carteras de destinatarios, dividido opcionalmente mediante un split.Glosario rápido
| Objeto | Prefijo del ID | Qué es |
|---|---|---|
| Transaction | txn_ | Un cobro. Agrupa ítems y payments. Tiene un status derivado de los payments. |
| Payment | pay_ | Un intento de pagar parte (o todo) el valor mediante un método (credit_card, pix, boleto). |
| Customer | cust_ | El comprador (persona física o jurídica). |
| Recipient | rec_ | Quien recibe el dinero (usted y/o terceros en un marketplace). |
| Split | spl_ | Regla de división del valor entre destinatarios. |
| Wallet | wlt_ | Saldo virtual de un destinatario, por moneda. |
| Withdrawal | wdr_ | Retiro del saldo de la cartera a la cuenta bancaria. |
| Refund | rfd_ | Devolución (total o parcial) de un payment. |
| Chargeback | cbk_ | Disputa iniciada por el titular ante la adquirente. |
| Card | crd_ | Tarjeta tokenizada y almacenada para reutilización. |
| Webhook | whk_ | Endpoint propio que recibe notificaciones de eventos. |
En el mundo de las suscripciones existen más objetos — Plan (
plan_), Price, Subscription
(sub_) e Invoice (inv_). Consulte Suscripciones.Transacción × Payment
Una transacción puede tener más de un payment (pago combinado — ej.: parte con tarjeta, parte con PIX). Elstatus de la transacción se calcula a partir de los status de sus payments:
| Status de la transacción | Cuándo |
|---|---|
waiting_payment | En espera de pago (ej.: PIX/boleto emitido, aún no pagado). |
paid | La suma de los payments pagados cubre el total. |
refused | Pago rechazado por la adquirente. |
refunded / partially_refunded | Devuelto total/parcialmente. |
chargeback | En disputa/disputado. |
canceled | Cancelado. |
Destinatario, cartera y retiro
- Por defecto, usted es el destinatario “owner” y recibe el 100% del valor (menos las comisiones).
- En un marketplace, usted crea otros recipients y utiliza split para dividir cada venta.
- El valor recibido ingresa en la wallet del destinatario (con saldo
available,pendingyblocked). - El destinatario puede entonces solicitar un withdrawal (retiro) a su cuenta bancaria.