Referencia
Estados de sesión y de transacción, payloads de webhook y los campos que devuelve cada evento.
Referencia de los estados, identificadores y eventos de webhook del Hosted Checkout.
Estados: sesión vs. transacción
Un punto común de confusión es la diferencia entre el status de una sesión y el de una
transacción de pago. Representan dos cosas distintas:
- El estado de la sesión representa toda la experiencia de checkout —piénsalo como el "carrito"
o "pedido" en espera de pago. Su ciclo es simple: empieza en
pendingy solo puede terminar encompleted(pagado) oexpired(abandonado). - El estado de la transacción representa un único intento de pagar esa sesión. Un cliente puede tener varias transacciones en una sesión si su primer intento falla.
| Tipo | Propósito | Valores de ejemplo |
|---|---|---|
| Estado de la sesión | El estado del pedido (¿está pagado?) | pending, completed, expired |
| Estado de la transacción | El estado de un intento de pago concreto (¿pasó este cargo?) | Pending, Success, Declined, Expired |
Para el cumplimiento de pedidos, basa tu lógica en el estado de la transacción
(transaction_status o el evento payment.transaction), no únicamente en el status de la
sesión. Un session.status: "completed" o "expired" no es suficiente para confirmar si el pago
fue exitoso o declinado.
Nota: en algunos comercios, transaction_status puede regresar vacío ("") para representar
una transacción Declinada, en lugar de quedarse en "Pending". Si ves este comportamiento,
trátalo como Declined.
Estado de la sesión
| Estado | Descripción |
|---|---|
| pending | La sesión se creó pero el cliente no completó el pago. La URL está activa. |
| completed | El cliente completó el pago con éxito. Estado final. |
| expired | La sesión no se completó a tiempo (cliente abandonó la página) y ya no puede pagarse. Estado final. |
Estado de la transacción
| Estado | Descripción |
|---|---|
| Pending | El pago se inició pero aún no se confirma (p. ej. esperando 3D Secure). |
| Success | El pago se autorizó y procesó con éxito. |
| Declined | El emisor o procesador rechazó el pago. El cliente puede reintentar. |
| Expired | El intento no se completó a tiempo (p. ej. falló 3D Secure). |
Identificadores clave
| ID | Tipo | Qué es |
|---|---|---|
id (Session ID) | string | Identificador único de la sesión. Ejemplo: cs_97_41521_d11ba771.... Aparece en la URL de checkout y al llamar a Get a Session. |
payment_id (Payment ID) | número | Identificador de una transacción (un intento de pago). Ejemplo: 41521. Una sesión puede tener varios si la primera tarjeta es rechazada. |
external_id (External ID) | string | Tu identificador interno del pedido, p. ej. ORD-001. Lo envías al crear la sesión y lo usas para conciliar. Es buscable en el Dashboard. |
Tu pedido (external_id) mapea 1:1 a una sesión de Tonder, que puede tener 1:N transacciones de
pago.
Eventos de webhook
Todos los payloads de webhook siguen esta estructura:
{
"action": "session.created",
"type": "checkout.hosted",
"data": {
// ... objeto relacionado con el evento
}
}| Campo | Tipo | Descripción |
|---|---|---|
action | string | El tipo de evento (p. ej. session.created, session.completed, session.expired). |
type | string | El tipo de checkout, siempre checkout.hosted para Hosted Checkout. |
data | object | Datos específicos del evento con detalles de la sesión o la transacción. |
El external_id que envías al crear la sesión aparece en el Dashboard como Order ID y en los
reportes de transacciones como Business Transaction ID, pero no se devuelve en los payloads
de webhook. Para recibir tu referencia de pedido en un webhook, inclúyela también dentro del
objeto metadata al crear la sesión; estará disponible en data.metadata.
session.created
Se envía cuando se crea una nueva sesión de checkout.
session.completed
Se envía cuando una sesión se paga y completa con éxito. Es el evento principal para confirmar un pedido exitoso.
session.expired
Se envía cuando una sesión pendiente expira sin un pago exitoso (p. ej. el cliente abandonó el checkout).
payment.transaction
Se envía cuando cambia el estado de una transacción de pago (Pending, Success, Declined). Una sesión
puede tener varios eventos payment.transaction si el usuario reintenta. Mientras
session.completed te dice que el pedido está pagado, payment.transaction te da detalles de cada
intento.