Estados y contrato de error
Referencia rápida de los dos contratos transversales: el sobre de error y el catálogo de estados de una sesión.
Sobre de error (canónico)
{ "success": false, "message": "<texto legible>", "code": "<CÓDIGO>" }
| HTTP | code | Significado |
|---|---|---|
400 | VALIDATION | El cuerpo no cumple el contrato |
401 | UNAUTHENTICATED | Falta o es inválido el Bearer |
404 | NOT_FOUND | El recurso no existe o no es tuyo |
Guía de uso → Manejo de estados y errores.
Catálogo de estados de la sesión
| Estado | Significado | Webhook asociado |
|---|---|---|
pending | Creada, esperando pago | — |
paid | Débito completado (fase 1) | payment_session.paid |
failed | Pago rechazado (solo Botón) | — |
expired | Venció sin pagarse | — |
| (acreditación) | Fase 2 — no cambia el status | payment_session.accredited |
La fase 2 no es un estado
La acreditación (fase 2) no aparece en el campo status, que se queda en paid. Pero sí está en esa misma respuesta, un nivel más abajo: data.session_payment.receiver_credits. Y te llega además por el webhook payment_session.accredited. → Transacción a dos fases.
Eventos de webhook
| Evento | Tiempo |
|---|---|
payment_session.paid | fase 1 (débito) |
payment_session.accredited | fase 2 (acreditación) |