Documentación

Pagos y confirmación

Un pago nace cuando tu cliente inicia el checkout. Solo el estado succeeded confirma que el dinero llegó a la cuenta conectada.

Estados del pago

status	Significado	Qué hacer
`pending`	El checkout se creó y el cliente aún no terminó.	Espera el webhook o el worker de conciliación. No entregues nada.
`succeeded`	La pasarela confirmó el pago.	Entrega el servicio. Es el único estado que confirma fondos.
`failed`	Un método de pago asíncrono falló después del checkout.	El enlace vuelve a ser pagable si sigue vigente.
`canceled`	La sesión de checkout expiró o se canceló.	Informativo. El enlace puede volver a intentarse.

Un pago con provider: "manual" lo registró el comercio con mark_paid: trae note, el method declarado y, si se adjuntó, un comprobante disponible en GET /v1/payments/{id}/reference(hasReference).

No confíes en la redirección

La página de éxito del navegador no prueba nada: el cliente pudo cerrar la pestaña, compartir la URL o llegar sin pagar. Confirma siempre con la API o con un webhook payment.succeeded.

Listar y consultar

Operación	Ruta	Notas
Listar	`GET /v1/payments`	`limit`, `starting_after` y `status` opcional. Ej. `?status=succeeded`.
Consultar	`GET /v1/payments/{id}`	Incluye `linkId`, `amountCentavos`, `paidAt`, `reconcileAfter` y `reconcileError`.

Sincronizar con la pasarela

Si un webhook se perdió o el resultado de una creación fue incierto, pide una verificación manual:

POST /v1/payments/{id}/sync

{ "paymentId": "pay_…", "status": "succeeded", "outcome": "updated" }

outcome es updated, pending, retrying o needs_review; los resultados diferidos incluyen detail.
Un pago con verificación en curso responde 409. Reintenta en unos segundos.
La sincronización puede recuperar el checkout original si la respuesta de creación se perdió. Nunca reembolsa ni cancela sesiones competidoras.

Un worker de conciliación revisa los pagos pendientes de forma continua, así que en la mayoría de los casos no necesitas llamar a sync. Para enterarte al instante, registra un webhook.