Hosted Checkout
Referencia
Estados, identificadores, métodos de pago, URLs de redirección y códigos de error de Hosted Checkout.
Referencia de los estados, identificadores, métodos de pago, redirecciones y errores de Hosted Checkout.
Estados: sesión vs. transacción
El status de una sesión y el transaction_status de un intento de pago representan dos
cosas distintas:
- El estado de la sesión es el checkout completo: el pedido en espera de pago. Empieza en
pendingy solo puede terminar encompletedoexpired. - El estado de la transacción es el resultado del intento de pago más reciente del cliente. Un cliente puede hacer varios intentos en una sesión.
Para la entrega de pedidos, basa tu lógica en el estado de la transacción, no únicamente en el
status de la sesión. Antes del primer intento, transaction_status es una cadena vacía ("") en
cuentas de API Direct, y Pending o "" en cuentas legacy.
Estado de la sesión
| Estado | Descripción |
|---|---|
| pending | La sesión está abierta. La URL está activa y el cliente puede pagar. |
| completed | El cliente pagó, o guardó la tarjeta en una sesión de registro de tarjeta. Estado final. |
| expired | Se alcanzó el límite de tiempo (24 horas como máximo). La sesión 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 (en espera de 3D Secure, de un voucher o de una transferencia). |
| Success | El pago se autorizó y se procesó. |
| Declined | El pago fue rechazado. El cliente puede reintentar. |
| Expired | El intento no se completó a tiempo. |
Identificadores clave
| Identificador | Qué es |
|---|---|
id de la sesión | Identifica la sesión, p. ej. cs_97_41528_42434d…. Úsalo con Consultar una sesión. |
payment_id | Un número que identifica el pago de una sesión de pago. Existe desde la creación, nunca cambia y se mantiene igual cuando el cliente reintenta con otra tarjeta. Úsalo con Consultar un pago, para conciliación y con soporte. 0 en las sesiones de registro de tarjeta. |
external_id | Tu propia referencia del pedido, p. ej. ORD-001 (se genera por ti si no envías una). Envíala también como metadata.external_id para que regrese en los webhooks. |
direct_transaction_id | Solo en cuentas de API Direct: el id del intento de pago más reciente del cliente (un UUID). Cambia cuando el cliente reintenta. |
payment_flow | direct cuando tu cuenta se procesa con la API Direct; en otro caso no está presente. Queda fijo al crear la sesión. |
Un pedido (external_id) corresponde a una sesión y a un payment_id, que puede tener varios
intentos.
Métodos de pago
Valores para payment_method_types. Un método se muestra solo cuando está activo para tu negocio en
el Dashboard y aparece en la lista de la sesión.
| Valor | Método | Tipo |
|---|---|---|
card | Tarjeta de crédito / débito | Tarjeta |
saved_cards | Las tarjetas guardadas del cliente | Tarjeta |
apple_pay | Managed Apple Pay, sobre el Merchant ID de Tonder — en el diseño v2, para cuentas que procesan por la API Direct, en dispositivos Apple | Billetera |
oxxopay | OXXO Pay | Voucher en efectivo |
spei | SPEI | Transferencia bancaria |
mercadopago | Mercado Pago | Redirección externa |
safetypayCash | SafetyPay Cash | Efectivo |
safetypayTransfer | SafetyPay Transfer | Transferencia bancaria |
neosurf | Neosurf | Voucher prepagado |
Opciones de Mercado Pago
Se envían en payment_method_config.mercadopago:
| Campo | Tipo | Descripción |
|---|---|---|
payment_methods.excluded_payment_methods[].id | string | Métodos a ocultar, p. ej. master. |
payment_methods.excluded_payment_types[].id | string | Tipos de método a ocultar, p. ej. ticket. |
payment_methods.default_payment_method_id | string | Método preseleccionado. |
payment_methods.installments | number | Máximo de mensualidades. |
binary_mode | boolean | Solo aprobado o rechazado, nunca pendiente. |
statement_descriptor | string | Texto en el estado de cuenta de la tarjeta. |
auto_return | string | Cuándo regresar automáticamente: approved o all. |
URLs de redirección
| URL | El cliente es enviado ahí cuando… |
|---|---|
success_url | el pago es exitoso. |
pending_url | el pago está pendiente (por ejemplo, un voucher de OXXO o una transferencia SPEI). |
cancel_url | el cliente cancela o el pago es rechazado en Mercado Pago. |
return_url | no aplica ninguna de las URLs específicas anteriores. Es la única que usan las sesiones de registro de tarjeta. |
Con redirect_on_completion: "always" (por defecto) el checkout redirige automáticamente al final.
Con "never" no redirige; tu página decide qué hacer a partir de los
eventos del checkout embebido.
Códigos de error
| Estado HTTP | Código | Significado |
|---|---|---|
| 400 | E004 | La petición es inválida. metadata.errors tiene una entrada por problema. |
| 400 | E0014 | Pediste el pago de una sesión de registro de tarjeta. |
| 401 / 403 | — | Llave API faltante o inválida, o una llave de otro entorno. |
| 404 | E003 | No hay ninguna sesión ni pago con este id. |
| 500 | E001 | Error inesperado. Reintenta con la misma x-idempotency-key. |
Entornos
| Sandbox | Producción | |
|---|---|---|
| URL base de la API | https://api-stage.tonder.io | https://api.tonder.io |
| Origen de la página de checkout | https://stage-payflow.tonder.io | https://payflow.tonder.io |
| Dashboard | https://dashboard-stage.tonder.io | https://dashboard.tonder.io |
Conviene saber
- Una sesión puede pagarse una sola vez y dura 24 horas como máximo.
- El monto, la moneda y los artículos de una sesión no se pueden cambiar. En su lugar, crea una sesión nueva.
- Si el cliente reintenta, la sesión reporta solo el intento más reciente; el
payment_idnunca cambia. - Prueba todo en Sandbox con tu llave API de prueba antes de salir a producción.
Siguientes pasos
¿Te resultó útil esta página?