Crear una sesión de checkout

Envía a tu cliente a la página de pago de Paygumi para registrar su tarjeta (modo setup) o registrarla y suscribirse a un plan (modo subscription).

Una sesión de checkout es un enlace de un solo uso a la página de pago de Paygumi (checkout.paygumi.com). Tu cliente escribe allí su tarjeta, que va de su navegador directo a Wompi: tu sitio no toca datos de tarjeta y no instalas ningún SDK.

Modos

`mode`	Qué hace	Cuándo usarlo
`setup`	Registra o reemplaza la tarjeta del cliente.	Cambiar la tarjeta, o recuperar a un cliente con un pago rechazado.
`subscription`	Registra la tarjeta y suscribe al cliente a `plan_id`.	El alta de un usuario a un plan.

El modo no distingue mayúsculas (setup o SETUP); en las respuestas viene en mayúsculas.

Modo subscription

Desde tu backend, cuando tu usuario elige un plan:

curl https://api.paygumi.com/v1/checkout-sessions \
  -H "Authorization: Bearer pgm_test_..." \
  -H "Idempotency-Key: 3f0c1d7e-8b1a-4f3e-9a51-6d2b7c9e0a14" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "subscription",
    "customer": {
      "external_id": "user_42",
      "email": "ana@ejemplo.co",
      "full_name": "Ana Pérez"
    },
    "plan_id": "pln_01JB86R800ABCDEFGHJKMNPQRS",
    "success_url": "https://tuapp.co/billing/ok",
    "cancel_url": "https://tuapp.co/billing"
  }'

Cliente: envía customer_id si ya existe en Paygumi, o customer con sus datos para crearlo al completar (uno de los dos). external_id es tu id del usuario.
Plan: obligatorio en este modo, del mismo entorno y ACTIVE.
Al completar: Paygumi crea la suscripción (TRIALING si el plan tiene días de prueba; si no, ACTIVE con el primer cobro en curso) y la deja en subscription_id.

La respuesta (201, aquí recortada) trae la url de la página de pago:

{
  "id": "cs_01JB86R800ABCDEFGHJKMNPQRS",
  "environment": "SANDBOX",
  "mode": "SUBSCRIPTION",
  "status": "OPEN",
  "url": "https://checkout.paygumi.com/c/3q2-7wEmWbIu4pS1Jx7bS1Kc0yQe9Gm9cXyZ0aBcDeF",
  "expires_at": "2026-11-02T05:00:00Z"
}

Redirige a tu usuario a url (por ejemplo con un 303 See Other). Es la única vez que la recibes: Paygumi solo guarda el hash del token. Si la pierdes, cancela la sesión y crea otra.

Modo setup

curl https://api.paygumi.com/v1/checkout-sessions \
  -H "Authorization: Bearer pgm_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "setup",
    "customer_id": "cus_01JB86R800ABCDEFGHJKMNPQRS",
    "success_url": "https://tuapp.co/billing/ok",
    "cancel_url": "https://tuapp.co/billing"
  }'

En modo setup no se envía plan_id. Si el cliente tenía un cobro rechazado, actualizar la tarjeta dispara un reintento inmediato.

Al volver a tu sitio

Al completar, Paygumi redirige a success_url?session_id=cs_…. Si el cliente abandona, vuelve a cancel_url.

No des acceso solo porque el usuario volvió a success_url: esa URL se puede abrir a mano. Confirma con el webhook checkout_session.completed o consultando la sesión.

curl https://api.paygumi.com/v1/checkout-sessions/cs_01JB86R800ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer pgm_test_..."

Una sesión COMPLETED trae customer_id, payment_method_id y, en modo subscription, subscription_id.

Estados

Estado	Significado
OPEN	Esperando a que el cliente registre su tarjeta.
COMPLETED	El cliente registró la tarjeta.
EXPIRED	Venció sin completarse (por defecto a las 24 h; `expires_at` entre 30 min y 7 días).
CANCELED	La cancelaste con `POST /v1/checkout-sessions/{id}/cancel`, o el cliente agotó los 5 intentos de tarjeta.

Errores frecuentes

Código	Causa
`409 tenant_not_ready`	El entorno no tiene llaves de Wompi verificadas.
`422 customer_required`	Falta `customer_id` o `customer` (o enviaste los dos).
`409 customer_external_id_taken`	Ya existe un cliente con ese `external_id`; su id viene en `error.resource_id`. Usa `customer_id`.
`422 plan_required` / `422 plan_not_allowed`	Falta `plan_id` en modo `subscription`, o sobra en modo `setup`.
`409 plan_archived`	El plan está archivado.
`409 subscription_exists`	El cliente ya tiene una suscripción viva a ese plan (id en `error.resource_id`).
`422 invalid_success_url` / `invalid_cancel_url`	URL no absoluta, con fragmento, o `http` en producción.

Todos los detalles en la referencia de sesiones de checkout.

Probar en sandbox

Con una llave pgm_test_ la página de pago trabaja contra el sandbox de Wompi y muestra que es un pago de prueba. Usa las tarjetas de prueba que publica Wompi en su documentación de sandbox para simular pagos aprobados y rechazados.