Crear una sesión

Llama a este endpoint desde tu backend cada vez que un cliente esté listo para pagar. Crea una sesión de checkout —para un pago o para un registro de tarjeta— y devuelve la url a la que envías al cliente.

POST https://api-stage.tonder.io/checkout/v1/sessions   # Sandbox
POST https://api.tonder.io/checkout/v1/sessions          # Producción

Cómo funciona

1. Tu servidor llama a este endpoint con el cliente, el monto y los artículos.
2. Tonder crea la sesión y, en las sesiones de pago, el pago. Recibes la url del checkout y el payment_id.
3. Rediriges al cliente a la url, o la embebes.
4. El cliente paga en la página de Tonder. Puede reintentar en la misma sesión.
5. El cliente regresa a tu sitio y confirmas el resultado con webhooks o consultando la sesión.

Una sesión es de un solo uso y es válida por un máximo de 24 horas. Su monto, moneda y artículos no se pueden cambiar; en su lugar, crea una sesión nueva.

Headers

Cuerpo

Cliente

Artículos

Ejemplo

curl -X POST 'https://api-stage.tonder.io/checkout/v1/sessions' \
  -H 'Authorization: Token YOUR_TEST_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'x-idempotency-key: ORD-001-attempt-1' \
  -d '{
    "customer": { "first_name": "Maria", "last_name": "Garcia", "email": "maria@example.com" },
    "amount_total": 150.00,
    "currency": "MXN",
    "external_id": "ORD-001",
    "line_items": [
      { "name": "Premium Plan", "quantity": 1, "unit_price": 150.00, "product_id": "plan-premium-01" }
    ],
    "payment_method_types": ["card", "saved_cards", "oxxopay"],
    "submit_type": "pay",
    "locale": "en",
    "return_url": "https://your-store.com/checkout/complete",
    "metadata": { "external_id": "ORD-001" }
  }'

curl -X POST 'https://api.tonder.io/checkout/v1/sessions' \
  -H 'Authorization: Token YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'x-idempotency-key: ORD-001-attempt-1' \
  -d '{
    "customer": { "first_name": "Maria", "last_name": "Garcia", "email": "maria@example.com" },
    "amount_total": 150.00,
    "currency": "MXN",
    "external_id": "ORD-001",
    "line_items": [
      { "name": "Premium Plan", "quantity": 1, "unit_price": 150.00, "product_id": "plan-premium-01" }
    ],
    "payment_method_types": ["card", "saved_cards", "oxxopay"],
    "submit_type": "pay",
    "locale": "en",
    "return_url": "https://your-store.com/checkout/complete",
    "metadata": { "external_id": "ORD-001" }
  }'

{
  "id": "cs_97_41528_42434df6c3644b9610df7b64a1fa9925e3b9562b05972097",
  "url": "https://stage-payflow.tonder.io/checkout/cs_97_41528_42434df6c3644b9610df7b64a1fa9925e3b9562b05972097",
  "status": "pending",
  "session_type": "payment",
  "checkout_type": "hosted",
  "payment_id": 41528,
  "checkout_ui_version": "v2",
  "submit_type": "pay",
  "locale": "en",
  "amount_total": 150.00,
  "currency": "MXN",
  "external_id": "ORD-001",
  "return_url": "https://your-store.com/checkout/complete",
  "payment_method_types": ["card", "saved_cards", "oxxopay"],
  "ui_config": {},
  "ui_config_version": "V1",
  "created_at": 1751483563558,
  "modified_at": 1751483563558,
  "expires_at": 1751569963
}

Qué te da la respuesta

La lista completa de identificadores y estados está en la Referencia.

Intentos de pago

Un cliente puede intentar pagar más de una vez en la misma sesión: una tarjeta es rechazada y reintenta con otra. La sesión conserva solo el intento más reciente: transaction_status (y direct_transaction_id en cuentas de API Direct) se reemplaza con cada intento nuevo, así que un primer Declined puede convertirse en Success. El payment_id se mantiene igual durante toda la sesión, así que todos los intentos pertenecen al mismo pago.

Errores

{
  "code": "E004",
  "message": "The request was invalid. Please check your input and try again.",
  "metadata": {
    "errors": [
      {
        "keyword": "required",
        "params": { "missingProperty": "currency" },
        "message": "must have required property 'currency'",
        "field": "currency"
      }
    ]
  },
  "name": "TNDR004",
  "statusCode": 400
}

Tarjetas guardadas

Incluye saved_cards en payment_method_types y el checkout muestra las tarjetas que el cliente ya guardó, junto al formulario de tarjeta nueva. Listarlas, seleccionarlas y eliminarlas se maneja por ti: no hay un endpoint extra que llamar.

A qué cliente pertenece una tarjeta guardada

Las tarjetas guardadas siempre pertenecen al cliente identificado por el customer.email de la sesión. Tonder puede configurar tu cuenta para requerir además customer.phone para las tarjetas guardadas: el cliente se sigue identificando por su email, y el teléfono es lo que habilita sus tarjetas guardadas. Pregunta a soporte de Tonder si tu cuenta lo requiere — no se puede consultar por API.

Cuando tu cuenta requiere teléfono:

• Envía customer.email y customer.phone en cada sesión que incluya saved_cards, incluida aquella en la que la tarjeta se guarda por primera vez (y en cada sesión de registro de tarjeta). Sin customer.phone no hay tarjetas guardadas: el cliente no las ve.
• El teléfono no reemplaza al email. El mismo teléfono con otro email es otro cliente y no ve esas tarjetas.
• Tonder compara el teléfono exactamente como lo envías. No se normaliza: +525512345678 y 5512345678 no son el mismo valor. Normaliza el número en tu propia aplicación antes de crear la sesión y envía siempre el mismo valor para el mismo cliente, en E.164 — +, código de país y número, por ejemplo +525512345678.

"customer": {
  "first_name": "Maria",
  "last_name": "Garcia",
  "email": "maria@example.com",
  "phone": "+525512345678"
}

La casilla de guardar tarjeta

Pon payment_method_config.saved_cards.show_save_card_checkbox en true para mostrar una casilla "guardar esta tarjeta para futuros pagos" en el formulario de tarjeta nueva, para que el cliente pueda elegir guardar su tarjeta.

curl -X POST 'https://api-stage.tonder.io/checkout/v1/sessions' \
  -H 'Authorization: Token YOUR_TEST_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "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"],
    "payment_method_config": {
      "saved_cards": { "show_save_card_checkbox": true }
    },
    "external_id": "ORD-001",
    "return_url": "https://your-store.com/checkout/complete"
  }'

curl -X POST 'https://api.tonder.io/checkout/v1/sessions' \
  -H 'Authorization: Token YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "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"],
    "payment_method_config": {
      "saved_cards": { "show_save_card_checkbox": true }
    },
    "external_id": "ORD-001",
    "return_url": "https://your-store.com/checkout/complete"
  }'

Card-on-File

Card-on-File (COF) guarda las tarjetas automáticamente y permite que el cliente vuelva a pagar sin volver a capturar su CVV. Funciona sobre la infraestructura de suscripciones y tokenización de Tonder.

Cuando Card-on-File está habilitado para tu cuenta, el checkout:

1. Ejecuta una verificación 3D Secure al guardar la tarjeta.
2. Crea una suscripción para esa tarjeta.
3. Acepta pagos con ella en visitas posteriores sin pedir el CVV.

Si Card-on-File está habilitado para tu cuenta, el checkout se encarga de todo esto por sí solo. Lo único que tu integración puede necesitar enviar es customer.phone, cuando tu cuenta requiere además el teléfono para las tarjetas guardadas — consulta A qué cliente pertenece una tarjeta guardada. Es la misma suscripción que el SDK expone como subscription_id; consulta la Referencia del SDK Web.

Referencia de la API

curl -X POST "https://example.com/checkout/v1/sessions" \  -H "Content-Type: application/json" \  -d '{    "customer": {      "first_name": "Maria",      "last_name": "Garcia",      "email": "maria@example.com"    },    "amount_total": 150,    "currency": "MXN",    "external_id": "ORD-001",    "line_items": [      {        "name": "Premium Plan",        "quantity": 1,        "unit_price": 150,        "product_id": "plan-premium-01"      }    ],    "payment_method_types": [      "card",      "saved_cards",      "oxxopay"    ],    "submit_type": "pay",    "locale": "en",    "return_url": "https://your-store.com/checkout/complete",    "metadata": {      "external_id": "ORD-001"    }  }'

{
  "id": "cs_97_41528_42434df6c3644b9610df7b64a1fa9925e3b9562b05972097",
  "url": "https://stage-payflow.tonder.io/checkout/cs_97_41528_42434df6c3644b9610df7b64a1fa9925e3b9562b05972097",
  "status": "pending",
  "session_type": "payment",
  "checkout_type": "hosted",
  "payment_id": 41528,
  "checkout_ui_version": "v2",
  "submit_type": "pay",
  "locale": "en",
  "amount_total": 150,
  "currency": "MXN",
  "external_id": "ORD-001",
  "return_url": "https://your-store.com/checkout/complete",
  "payment_method_types": [
    "card",
    "saved_cards",
    "oxxopay"
  ],
  "ui_config": {},
  "ui_config_version": "V1",
  "created_at": 1751483563558,
  "modified_at": 1751483563558,
  "expires_at": 1751569963
}

{
  "code": "E004",
  "message": "The request was invalid. Please check your input and try again.",
  "metadata": {
    "errors": [
      {
        "keyword": "required",
        "params": {
          "missingProperty": "currency"
        },
        "message": "must have required property 'currency'",
        "field": "currency"
      }
    ]
  },
  "name": "TNDR004",
  "statusCode": 400
}

{
  "code": "E004",
  "message": "The request was invalid. Please check your input and try again.",
  "metadata": {},
  "name": "TNDR004",
  "statusCode": 400
}

Siguientes pasos