Hosted Checkout legacy
Qué son el checkout de primera generación y el flujo de pago legacy, cómo mantenerte en ellos y cómo migrar a 2.0.
Esta página describe el Hosted Checkout de primera generación. Las integraciones nuevas deben seguir Hosted Checkout 2.0.
"Legacy" abarca dos cosas independientes. Tu integración puede usar una, ambas o ninguna.
| Legacy | Hosted Checkout 2.0 | |
|---|---|---|
| Diseño del checkout | v1 — la página de primera generación | v2 — resumen del pedido, plantillas, fuentes, es / en / zh, Apple Pay |
| Flujo de pago | Procesamiento legacy, con los payloads de webhook legacy | Procesamiento con API Direct, con los webhooks de Tonder estándar |
Los endpoints son los mismos en ambos: POST /checkout/v1/sessions, GET /checkout/v1/sessions/{id},
GET /checkout/v1/payments/{payment_id} y /checkout/v1/business/config. Una sesión nunca
cambia de diseño ni de flujo a la mitad: ambos quedan fijos al crearla.
El diseño v1
Las sesiones de pago nuevas usan el diseño v2, a menos que pidas otra cosa. Para mantener el
diseño de primera generación:
- Para todo tu negocio — guarda
checkout_ui_version=v1como valor por defecto del negocio con Guardar configuración del negocio. - Para una sesión — envía
"checkout_ui_version": "v1"al crearla.
{
"customer": { "first_name": "Maria", "last_name": "Garcia", "email": "maria@example.com" },
"amount_total": 150.00,
"currency": "MXN",
"line_items": [{ "name": "Premium Plan", "quantity": 1, "unit_price": 150.00 }],
"payment_method_types": ["card", "saved_cards"],
"checkout_ui_version": "v1",
"external_id": "ORD-001",
"return_url": "https://your-store.com/checkout/complete"
}Lo que el diseño v1 no tiene: plantillas, el selector de fuente, la distribución con resumen del
pedido y Apple Pay. Las sesiones de registro de tarjeta
siempre usan v1.
El flujo de pago legacy
La forma en que se procesan tus pagos se define por cuenta, no por petición. Te integras de la misma manera en ambos casos; lo que cambia es lo que recibes de vuelta:
| Flujo legacy | Flujo con API Direct | |
|---|---|---|
payment_id | Se devuelve al crear la sesión | Se devuelve al crear la sesión |
payment_flow | No está presente | direct |
direct_transaction_id | No está presente | Presente una vez que el cliente ha intentado pagar |
transaction_status antes del primer intento | Pending o "" | "" |
| Webhooks | Payloads legacy | Webhooks estándar de Tonder |
| Apple Pay | No disponible | Disponible en el diseño v2 |
Cuando tu cuenta se mueve a la API Direct, las sesiones nuevas dejan de producir payloads de webhook legacy. Actualiza tu handler de webhooks al formato estándar antes del cambio. Si no sabes con certeza qué flujo usa tu cuenta, consúltalo con soporte de Tonder.
Migrar a 2.0
Envía "checkout_ui_version": "v2" en una sesión de Sandbox, o usa la
demo interactiva. Nada más cambia en tu petición.
Maneja los webhooks de pago estándar (event_type: payment_Pending, payment_Success,
payment_Failed) junto con los legacy. Consulta
Escuchar webhooks.
session.created, session.completed y session.expired ya no se envían en ningún flujo.
Sigue la sesión con los webhooks de pago o con Consultar una sesión.
GET /checkout/v1/payments/{payment_id} acepta únicamente el payment_id numérico.
Cuando tu handler esté listo, soporte de Tonder cambia tu cuenta a
la API Direct. Quita el valor por defecto v1 cuando quieras el diseño nuevo en todas partes.