Guía de Hosted Checkout
Los cuatro pasos de Hosted Checkout, con el request armándose en vivo.
Con Hosted Checkout tú creas la sesión y Tonder te da una URL; mandas a tu cliente ahí para que pague y luego consultas el resultado. Son 4 pasos, y el primero se hace una sola vez.
🇲🇽 🇨🇱 México y Chile usan el mismo flujo. Nada cambia salvo currency: "MXN" para México,
"CLP" para Chile.
Aquí defines el logo y los colores que se verán en todas tus sesiones de checkout. No se repite por venta: normalmente lo haces una vez al integrar.
Este endpoint también acepta un campo logo para subir el archivo directo (multipart) en vez de
una URL ya alojada. Esta guía usa logo_url porque es lo más común.
curl -X POST "https://api-stage.tonder.io/checkout/v1/business/config" \
-H "Authorization: Token YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "active",
"logo_url": "https://cdn.my-store.com/logo.png",
"ui_config": {
"branding": {
"brand_color": "#00A859"
},
"theme": {
"shapes": "rounded"
}
}
}'Este es el paso que sí repites en cada venta. Le dices a Tonder quién es el cliente, qué compra y
cuánto paga. Tonder devuelve una url: ahí mandas a tu cliente para que ingrese los datos de pago
—tú nunca ves ni tocas la tarjeta en este flujo.
metadata es libre: manda los campos que te sirvan para identificar la venta en tus sistemas.
Mantén metadata.external_id — es la clave con la que conciliarás el pago en los webhooks.
curl -X POST "https://api-stage.tonder.io/checkout/v1/sessions" \
-H "Authorization: Token YOUR_API_KEY" \
-H "x-idempotency-key: test-001" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"first_name": "Vicente",
"last_name": "Quintero",
"email": "vquintero@testuser.com"
},
"amount_total": 150.00,
"currency": "MXN",
"line_items": [
{
"name": "Deposit",
"quantity": 1,
"unit_price": 150.00,
"product_id": "your internal product id"
}
],
"payment_method_types": [
"card",
"spei",
"oxxopay"
],
"return_url": "https://tonder.io",
"external_id": "ORD-12345-4",
"metadata": {
"external_id": "ORD-12345-4"
}
}'Si sale bien, abre el campo url de la respuesta en el navegador: ahí es donde pagaría tu cliente.
Guarda el id de la sesión para el paso 3.
Tu cliente puede cerrar la ventana, perder internet o tardarse. En vez de depender solo del
return_url, consulta el estado de la sesión con su id.
curl -X GET "https://api-stage.tonder.io/checkout/v1/sessions/cs_541_4999601" \
-H "Authorization: Token YOUR_API_KEY"Para el cumplimiento de pedidos basa tu lógica en el estado de la transacción
(transaction_status), no en el status de la sesión: completed o expired por sí solos no
confirman si el pago fue exitoso o declinado. Ver
Referencia de Hosted Checkout.
La sesión te dice si se pagó; este endpoint te da el detalle fino del intento: qué método se usó,
últimos 4 dígitos si fue tarjeta, marca. Usa el payment_id que viste en el paso 3.
curl -X GET "https://api-stage.tonder.io/checkout/v1/payments/4999601" \
-H "Authorization: Token YOUR_API_KEY"