Estados y glosario
Al terminar esta página sabrás qué significa cada estado de sesión y de pago, y qué transiciones maneja tu integración.
Estados de la sesión (status)
Sección titulada «Estados de la sesión (status)»| Estado | Significado |
|---|---|
open |
El pagador puede continuar. Es el estado inicial y también el estado al que vuelve la sesión después de un intento de cobro fallido. |
processing |
Hay un intento de cobro en curso. |
completed |
El checkout terminó con un pago confirmado (succeeded). |
canceled |
El pagador salió antes de completar un cobro, o una devolución posterior canceló la obligación pagada. |
expired |
Reservado. La API no lo asigna hoy; ver la nota de vencimiento más abajo. |
Transiciones observadas
Sección titulada «Transiciones observadas»| De | A | Disparador |
|---|---|---|
| Nueva | open |
POST /v1/checkout-sessions |
open |
processing |
El pagador confirma un medio de pago (POST /v1/checkout/{token}/pay). |
processing |
completed |
El cobro se confirma (payment.status = succeeded). |
processing |
open |
El intento de cobro falla (payment.status = failed); el pagador puede reintentar mientras la sesión no haya vencido. |
open |
canceled |
El pagador sale del checkout sin haber iniciado un cobro. |
completed |
canceled |
Una solicitud de cancelación del pagador se confirma por completo, ver más abajo. |
Estados del pago (payment.status)
Sección titulada «Estados del pago (payment.status)»| Estado | Significado |
|---|---|
pending |
Neat todavía no tiene un resultado definitivo del cobro. |
succeeded |
El cobro fue confirmado. No implica por sí solo que el dinero ya se depositó a tu comercio. |
failed |
Este intento fue rechazado de forma definitiva. Un reintento explícito del pagador genera otro payment_id. |
partially_refunded |
Reservado. Existe en el contrato y v1 no lo emite nunca: hoy toda cancelación devuelve el cargo completo. |
refunded |
El cargo fue devuelto por completo y confirmado. |
Un pago llega a refunded cuando el pagador solicita la cancelación desde su historial en Neat y el
adquirente confirma la devolución; tu comercio se entera por el webhook payment.refunded. Ver
Webhooks: eventos y firma.
No hay devoluciones parciales en v1. Una cancelación devuelve el cargo completo, con la comisión
si la pagó el pagador, así que refunded_amount_minor siempre termina igual a charged_amount_minor. El estado
partially_refunded está reservado por si eso cambia; si programas contra él hoy, estás manejando un
caso que no ocurre.
Estado de cancelación (cancellation_state)
Sección titulada «Estado de cancelación (cancellation_state)»Acompaña a payment.status cuando el pagador pide cancelar un cobro ya confirmado.
| Estado | Significado |
|---|---|
none |
No hay una cancelación en curso. |
requested |
El pagador pidió cancelar; Neat está confirmando con el adquirente. |
completed |
La cancelación se confirmó. payment.status pasa a refunded y refunded_amount_minor iguala al monto cobrado completo, con la comisión de Neat e IVA si los pagó el pagador: al pagador se le devuelve todo lo que se le cobró. |
rejected |
El adquirente no confirmó la cancelación. payment.status no cambia. |
Si el adquirente no responde de forma definitiva a la solicitud de cancelación, el pago se queda en
requested y Neat la resuelve con el adquirente antes de moverla. Tu comercio no necesita hacer nada
durante esa espera: el webhook o la consulta de la sesión te avisan cuando se resuelva. Una
cancelación que lleve más de un día sin resolverse la atiende una persona en Neat.
Glosario
Sección titulada «Glosario»| Término | Significado |
|---|---|
Sesión (checkout_session) |
Un intento de checkout: tiene un enlace, un vencimiento y, eventualmente, un pago. |
| Obligación | Lo que el pagador debe, identificado por tu external_reference. Sobrevive a varias sesiones si la primera vence sin pagarse. |
Pago (payment) |
Un intento de cobro contra una obligación. Cada intento tiene su propio payment_id. |
version |
Entero creciente del pago; aumenta con cada cambio de estado confirmado (por ejemplo, al pasar de pending a succeeded, o al completarse una cancelación). |