¿Qué es un Checkout?

Un Checkout es una intención de cobro: tú defines qué estás cobrando (ítems y moneda) y Venti genera una página de pago alojada (url) donde tu cliente elige el medio de pago y confirma. No integras pasarelas ni manejas datos de tarjetas: creas un objeto, compartes un link y escuchas un webhook.

POST /checkouts  →  compartes la `url`  →  el cliente paga  →  webhook `checkout.paid`

El principio detrás del producto

Un checkout no es dinero: es una intención. El dinero existe recién cuando el cliente confirma y el cobro se materializa en otro objeto, según el medio de pago que eligió:

Payment — medios de pago externos: tarjetas, transferencia, etc.
Loan — compra en cuotas BNPL de Venti (ver Suscripciones y otros productos para el mapa completo).
AccountEntry — pago con una cuenta de crédito de Cuentas Venti (no mueve dinero real).

El checkout pagado te dice exactamente con qué se pagó mediante su discriminador:

{
  "status": "paid",
  "successful_object": "payment",
  "successful_object_id": "pay_hK2mR8vQpL9wN4sJhT5yBc3d",
  "payment_id": "pay_hK2mR8vQpL9wN4sJhT5yBc3d",
  "loan_id": null,
  "account_entry_id": null
}

payment_id, loan_id y account_entry_id son mutuamente excluyentes: solo se llena el del objeto que pagó, y successful_object / successful_object_id siempre apuntan a él.

Los objetos

Objeto	Prefijo	Qué representa
`Checkout`	`chk_`	La intención de cobro y su página de pago (`url`). Define ítems, moneda y redirecciones.
`Payment`	`pay_`	El cargo a un medio de pago externo. Registra autorización, captura, comisión y liquidación.
`Charge`	`ch_`	Un intento de cargo en el adquirente. Un `Payment` puede tener varios; el exitoso queda en `successful_charge_id`.
`Refund`	`ref_`	Una devolución total o parcial de un pago.
`PaymentButton`	`pb_`	Un link de pago reutilizable que genera un checkout nuevo por cada cliente que lo abre.
`Coupon`	`cpn_`	Un descuento por código, aplicable a checkouts o suscripciones.

Cómo se leen los montos

Todos los montos van en unidades menores de la moneda (para clp, pesos). Los campos clave de un checkout:

amount — el total a pagar. Se calcula en el servidor: suma de los ítems (subtotal), menos descuentos (discount), más impuestos exclusivos. No puedes fijarlo directamente.
original_amount — el total al momento de crearse, antes de cupones o promociones.
items[] — cada ítem lleva unit_price, quantity y su total calculado.
available_for_refund — cuánto queda por reembolsar (amount − refunded_amount).
settlement_amount / settlement_currency — lo que se liquida a tu comercio una vez pagado.
fee — la comisión de procesamiento del pago que lo saldó.
session_email / session_taxid / session — datos que el cliente entregó en la página de pago.

Estados de un checkout

Estado	Significado
`unpaid`	Pendiente de pago. Es el único estado desde el que se puede pagar, cancelar o aplicar cupones.
`paid`	Pagado (`paid_at` indica cuándo). Mira `successful_object` para saber con qué.
`canceled`	Cancelado por ti con `POST /checkouts/{id}/cancel`.
`expired`	Venció sin pagarse (pasó `expires_at`, por defecto 2 semanas desde la creación).

Estados de un pago

Estado	Significado
`requires_authorization`	Creado, esperando que el cliente autorice con un medio de pago.
`requires_capture`	Autorizado pero no capturado (flujo en dos pasos, `capture: false`).
`succeeded`	Autorizado y capturado: el cobro se hizo efectivo.
`failed`	La autorización falló (`status_reason` indica por qué).
`canceled`	Cancelado antes de capturarse.

Los booleanos authorized y captured (con authorized_at / captured_at) registran cada mitad del cobro por separado.

Siguientes pasos

Inicio rápido — tu primer cobro y tu primer reembolso en 5 llamadas.
Ciclo de vida y dinero — cuándo llega el dinero a tu balance y con qué comisiones.
Webhooks y conciliación — cómo integrar tu backend.
Reglas y errores — las reglas del producto y sus códigos de error.
La referencia completa de la API está en la sección Payments del API Reference.