Saltar al contenido

Referencia de la API

Sesiones de checkout

Enlaces a la página de pago donde tu cliente registra su tarjeta y, si quieres, se suscribe.

Crear una sesión de checkout

POST/v1/checkout-sessions

Crea el enlace a la página de pago de Paygumi donde tu cliente registra su tarjeta (modo SETUP) o, además, se suscribe a un plan (modo SUBSCRIPTION). Redirige a tu usuario a url (o envíasela): es la única vez que la recibes, porque Paygumi guarda solo el hash del token.

  • Cliente: customer_id (existente en el entorno de la API key; si no, 404 customer_not_found) o customer con los datos para crearlo al completar (no ambos: 422 customer_required). Un customer.external_id ya registrado → 409 customer_external_id_taken con su id en resource_id.
  • success_url y cancel_url: URLs absolutas http(s), sin fragmento; https en producción (invalid_success_url, invalid_cancel_url). Al completar, Paygumi redirige a success_url?session_id=cs_…; confirma el resultado con GET /v1/checkout-sessions/{id} (o el webhook), no solo por la URL.
  • expires_at: por defecto 24 h; entre 30 min y 7 días (invalid_expires_at).
  • El entorno debe tener credenciales de Wompi verificadas: si no, 409 tenant_not_ready.
  • Modo SUBSCRIPTION: plan_id obligatorio (422 plan_required), del entorno (404 plan_not_found) y ACTIVE (409 plan_archived); si el cliente existente ya tiene una suscripción viva al plan, 409 subscription_exists con su id en resource_id. metadata se copia a la suscripción. Al completar, Paygumi registra la tarjeta, crea la suscripción (TRIALING si el plan tiene prueba; si no, ACTIVE con el primer cobro SCHEDULED) y la deja en subscription_id.
  • Modo SETUP con plan_id → 422 plan_not_allowed.

Con Idempotency-Key, el reintento devuelve la misma sesión con Idempotent-Replayed: true y url: null (el token nunca se guarda); si perdiste la URL, cancela la sesión y crea otra.

Autenticación: Authorization: Bearer <API key>. Acepta Idempotency-Key.

Parámetros

Parámetros de Crear una sesión de checkout
ParámetroEnTipoDescripción
Idempotency-Keycabecerastring

Clave elegida por el cliente (1–255 caracteres ASCII visibles; se recomienda un UUID v4) para reintentar un POST sin repetir su efecto. Es única por tenant y entorno de la API key. La respuesta (2xx o 4xx) se guarda 24 h; las 5xx no se guardan.

  • Misma clave y misma petición (método, ruta con query y body idénticos byte a byte): se devuelve la respuesta guardada, con Idempotent-Replayed: true, sin volver a ejecutar.
  • Misma clave con otra petición → 422 idempotency_key_reused.
  • Misma clave mientras la primera sigue en curso → 409 idempotency_key_in_use (reintenta en unos segundos).
  • Clave mal formada → 422 invalid_idempotency_key; body de más de 1 MiB → 413.

Ejemplo: 3f0c1d7e-8b1a-4f3e-9a51-6d2b7c9e0a14

Cuerpo (application/json, CreateCheckoutSessionRequest)

Campos del cuerpo de Crear una sesión de checkout
CampoTipoDescripción
modeobligatoriostring
SETUP (solo registrar el medio de pago) o SUBSCRIPTION (registrarlo y suscribir a plan_id), sin distinguir mayúsculas.

Ejemplo: setup

customer_idstring
Cliente existente (cus_…).
customerobject
Datos para crear el cliente al completar; los errores llevan param customer.<campo>.
customer.external_idobligatoriostring

Ejemplo: user_42

customer.emailobligatoriostring (email)
customer.full_namestring
customer.phonestring
E.164 (+573001234567) o número colombiano de 10 dígitos.
customer.legal_id_typestring

Valores: CC, CE, NIT, PP

customer.legal_id_numberstring
customer.metadataobject<string, string>
plan_idstring
Obligatorio en modo SUBSCRIPTION (plan ACTIVE del entorno); no se admite en SETUP.
success_urlobligatoriostring (uri)

Ejemplo: https://tuapp.co/billing/ok

cancel_urlobligatoriostring (uri)

Ejemplo: https://tuapp.co/billing

expires_atstring (date-time)
Por defecto ahora + 24 h; entre 30 min y 7 días.
metadataobject<string, string>
Hasta 20 llaves; en modo SUBSCRIPTION se copia a la suscripción.

Respuestas

201Sesión creada con su url (Cache-Control: no-store), o la repetición sin url.

Esquema CheckoutSession

Campos de la respuesta 201
CampoTipoDescripción
idobligatoriostring

Ejemplo: cs_01JB86R800ABCDEFGHJKMNPQRS

environmentobligatoriostring

Valores: SANDBOX, PRODUCTION

modeobligatoriostring
SETUP registra o reemplaza la tarjeta. SUBSCRIPTION además suscribe al cliente a plan_id.

Valores: SETUP, SUBSCRIPTION

statusobligatoriostring
Estado efectivo; una sesión OPEN vencida se lee EXPIRED.

Valores: OPEN, COMPLETED, EXPIRED, CANCELED

urlobligatoriostring | null
{CHECKOUT_BASE_URL}/c/{token}. Solo en la respuesta de creación; null en el resto (y en la repetición por Idempotency-Key).

Ejemplo: https://checkout.paygumi.com/c/3q2-7wEmWbIu4pS1Jx7bS1Kc0yQe9Gm9cXyZ0aBcDeF

customer_idobligatoriostring | null
null si el cliente se crea al completar y aún no se completó.
plan_idobligatoriostring | null
payment_method_idobligatoriostring | null
Medio de pago registrado al completar.
subscription_idobligatoriostring | null
Suscripción creada al completar en modo SUBSCRIPTION.
success_urlobligatoriostring
cancel_urlobligatoriostring
metadataobligatorioobject<string, string>
failed_attemptsobligatoriointeger
Tarjetas rechazadas en la sesión (con 5, se cancela).
expires_atobligatoriostring (date-time)
RFC 3339 en UTC.
created_atobligatoriostring (date-time)
RFC 3339 en UTC.
completed_atobligatoriostring (date-time) | null
  • Idempotent-Replayed: true si la respuesta es la guardada de una petición anterior con la misma Idempotency-Key.

Errores

400

JSON mal formado o tipos inválidos (p. ej. decimales donde va un entero) (code invalid_body).

401

Credencial ausente, inválida, expirada o revocada (code unauthorized).

404

El recurso no existe o es de otro tenant (nunca 403, para no filtrar existencia).

409

Conflicto. code: already_member, api_key_limit_exceeded, last_owner, invitation_expired, invitation_not_pending, webhook_endpoint_limit_exceeded, plan_name_taken (param name), customer_external_id_taken (con resource_id y param external_id; en POST /v1/checkout-sessions, customer.external_id), last_payment_method_in_use, payment_method_not_active, idempotency_key_in_use, tenant_not_ready (el entorno no tiene credenciales de Wompi verificadas), checkout_session_completed, checkout_session_expired, checkout_session_canceled, plan_archived, subscription_exists (con resource_id), subscription_version_conflict (reintenta), payment_method_required, subscription_not_pausable, subscription_not_paused, subscription_not_changeable, subscription_cancel_at_period_end_not_allowed, subscription_cancel_not_scheduled, portal_disabled (el tenant deshabilitó el portal en el entorno).

422

La entrada no cumple las reglas (type invalid_request; param indica el campo).

429

Demasiadas peticiones (type rate_limited, code rate_limited): más de 100 peticiones por segundo con la misma API key. Reintenta cuando indique Retry-After.

Otros

Error con el formato estándar.

Todos con el formato de error estándar.

Petición (cURL)
curl -X POST 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": "setup",
  "success_url": "https://tuapp.co/billing/ok",
  "cancel_url": "https://tuapp.co/billing"
}'
Respuesta 201
{
  "id": "cs_01JB86R800ABCDEFGHJKMNPQRS",
  "environment": "SANDBOX",
  "mode": "SETUP",
  "status": "OPEN",
  "url": "https://checkout.paygumi.com/c/3q2-7wEmWbIu4pS1Jx7bS1Kc0yQe9Gm9cXyZ0aBcDeF",
  "customer_id": "string",
  "plan_id": "string",
  "payment_method_id": "string",
  "subscription_id": "string",
  "success_url": "string",
  "cancel_url": "string",
  "metadata": {},
  "failed_attempts": 0,
  "expires_at": "2026-11-01T05:00:00Z",
  "created_at": "2026-11-01T05:00:00Z",
  "completed_at": "2026-11-01T05:00:00Z"
}

Consultar una sesión de checkout

GET/v1/checkout-sessions/{id}

Estado efectivo de la sesión (una OPEN vencida responde EXPIRED), sin url. Completada: payment_method_id y customer_id (también cuando el cliente se creó al completar). De otro entorno → 404.

Autenticación: Authorization: Bearer <API key>.

Parámetros

Parámetros de Consultar una sesión de checkout
ParámetroEnTipoDescripción
idobligatoriorutastring
Id de la sesión (cs_…). Uno mal formado responde 404.

Ejemplo: cs_01JB86R800ABCDEFGHJKMNPQRS

Respuestas

200La sesión.

Esquema CheckoutSession

Campos de la respuesta 200
CampoTipoDescripción
idobligatoriostring

Ejemplo: cs_01JB86R800ABCDEFGHJKMNPQRS

environmentobligatoriostring

Valores: SANDBOX, PRODUCTION

modeobligatoriostring
SETUP registra o reemplaza la tarjeta. SUBSCRIPTION además suscribe al cliente a plan_id.

Valores: SETUP, SUBSCRIPTION

statusobligatoriostring
Estado efectivo; una sesión OPEN vencida se lee EXPIRED.

Valores: OPEN, COMPLETED, EXPIRED, CANCELED

urlobligatoriostring | null
{CHECKOUT_BASE_URL}/c/{token}. Solo en la respuesta de creación; null en el resto (y en la repetición por Idempotency-Key).

Ejemplo: https://checkout.paygumi.com/c/3q2-7wEmWbIu4pS1Jx7bS1Kc0yQe9Gm9cXyZ0aBcDeF

customer_idobligatoriostring | null
null si el cliente se crea al completar y aún no se completó.
plan_idobligatoriostring | null
payment_method_idobligatoriostring | null
Medio de pago registrado al completar.
subscription_idobligatoriostring | null
Suscripción creada al completar en modo SUBSCRIPTION.
success_urlobligatoriostring
cancel_urlobligatoriostring
metadataobligatorioobject<string, string>
failed_attemptsobligatoriointeger
Tarjetas rechazadas en la sesión (con 5, se cancela).
expires_atobligatoriostring (date-time)
RFC 3339 en UTC.
created_atobligatoriostring (date-time)
RFC 3339 en UTC.
completed_atobligatoriostring (date-time) | null

Errores

401

Credencial ausente, inválida, expirada o revocada (code unauthorized).

404

El recurso no existe o es de otro tenant (nunca 403, para no filtrar existencia).

429

Demasiadas peticiones (type rate_limited, code rate_limited): más de 100 peticiones por segundo con la misma API key. Reintenta cuando indique Retry-After.

Otros

Error con el formato estándar.

Todos con el formato de error estándar.

Petición (cURL)
curl https://api.paygumi.com/v1/checkout-sessions/{id} \
  -H "Authorization: Bearer pgm_test_..."
Respuesta 200
{
  "id": "cs_01JB86R800ABCDEFGHJKMNPQRS",
  "environment": "SANDBOX",
  "mode": "SETUP",
  "status": "OPEN",
  "url": "https://checkout.paygumi.com/c/3q2-7wEmWbIu4pS1Jx7bS1Kc0yQe9Gm9cXyZ0aBcDeF",
  "customer_id": "string",
  "plan_id": "string",
  "payment_method_id": "string",
  "subscription_id": "string",
  "success_url": "string",
  "cancel_url": "string",
  "metadata": {},
  "failed_attempts": 0,
  "expires_at": "2026-11-01T05:00:00Z",
  "created_at": "2026-11-01T05:00:00Z",
  "completed_at": "2026-11-01T05:00:00Z"
}

Cancelar una sesión de checkout

POST/v1/checkout-sessions/{id}/cancel

Invalida el enlace. Idempotente si ya estaba CANCELED. Completada → 409 checkout_session_completed; vencida → 409 checkout_session_expired. Acepta Idempotency-Key.

Autenticación: Authorization: Bearer <API key>. Acepta Idempotency-Key.

Parámetros

Parámetros de Cancelar una sesión de checkout
ParámetroEnTipoDescripción
idobligatoriorutastring
Id de la sesión (cs_…). Uno mal formado responde 404.

Ejemplo: cs_01JB86R800ABCDEFGHJKMNPQRS

Idempotency-Keycabecerastring

Clave elegida por el cliente (1–255 caracteres ASCII visibles; se recomienda un UUID v4) para reintentar un POST sin repetir su efecto. Es única por tenant y entorno de la API key. La respuesta (2xx o 4xx) se guarda 24 h; las 5xx no se guardan.

  • Misma clave y misma petición (método, ruta con query y body idénticos byte a byte): se devuelve la respuesta guardada, con Idempotent-Replayed: true, sin volver a ejecutar.
  • Misma clave con otra petición → 422 idempotency_key_reused.
  • Misma clave mientras la primera sigue en curso → 409 idempotency_key_in_use (reintenta en unos segundos).
  • Clave mal formada → 422 invalid_idempotency_key; body de más de 1 MiB → 413.

Ejemplo: 3f0c1d7e-8b1a-4f3e-9a51-6d2b7c9e0a14

Respuestas

200La sesión cancelada.

Esquema CheckoutSession

Campos de la respuesta 200
CampoTipoDescripción
idobligatoriostring

Ejemplo: cs_01JB86R800ABCDEFGHJKMNPQRS

environmentobligatoriostring

Valores: SANDBOX, PRODUCTION

modeobligatoriostring
SETUP registra o reemplaza la tarjeta. SUBSCRIPTION además suscribe al cliente a plan_id.

Valores: SETUP, SUBSCRIPTION

statusobligatoriostring
Estado efectivo; una sesión OPEN vencida se lee EXPIRED.

Valores: OPEN, COMPLETED, EXPIRED, CANCELED

urlobligatoriostring | null
{CHECKOUT_BASE_URL}/c/{token}. Solo en la respuesta de creación; null en el resto (y en la repetición por Idempotency-Key).

Ejemplo: https://checkout.paygumi.com/c/3q2-7wEmWbIu4pS1Jx7bS1Kc0yQe9Gm9cXyZ0aBcDeF

customer_idobligatoriostring | null
null si el cliente se crea al completar y aún no se completó.
plan_idobligatoriostring | null
payment_method_idobligatoriostring | null
Medio de pago registrado al completar.
subscription_idobligatoriostring | null
Suscripción creada al completar en modo SUBSCRIPTION.
success_urlobligatoriostring
cancel_urlobligatoriostring
metadataobligatorioobject<string, string>
failed_attemptsobligatoriointeger
Tarjetas rechazadas en la sesión (con 5, se cancela).
expires_atobligatoriostring (date-time)
RFC 3339 en UTC.
created_atobligatoriostring (date-time)
RFC 3339 en UTC.
completed_atobligatoriostring (date-time) | null
  • Idempotent-Replayed: true si la respuesta es la guardada de una petición anterior con la misma Idempotency-Key.

Errores

401

Credencial ausente, inválida, expirada o revocada (code unauthorized).

404

El recurso no existe o es de otro tenant (nunca 403, para no filtrar existencia).

409

Conflicto. code: already_member, api_key_limit_exceeded, last_owner, invitation_expired, invitation_not_pending, webhook_endpoint_limit_exceeded, plan_name_taken (param name), customer_external_id_taken (con resource_id y param external_id; en POST /v1/checkout-sessions, customer.external_id), last_payment_method_in_use, payment_method_not_active, idempotency_key_in_use, tenant_not_ready (el entorno no tiene credenciales de Wompi verificadas), checkout_session_completed, checkout_session_expired, checkout_session_canceled, plan_archived, subscription_exists (con resource_id), subscription_version_conflict (reintenta), payment_method_required, subscription_not_pausable, subscription_not_paused, subscription_not_changeable, subscription_cancel_at_period_end_not_allowed, subscription_cancel_not_scheduled, portal_disabled (el tenant deshabilitó el portal en el entorno).

429

Demasiadas peticiones (type rate_limited, code rate_limited): más de 100 peticiones por segundo con la misma API key. Reintenta cuando indique Retry-After.

Otros

Error con el formato estándar.

Todos con el formato de error estándar.

Petición (cURL)
curl -X POST https://api.paygumi.com/v1/checkout-sessions/{id}/cancel \
  -H "Authorization: Bearer pgm_test_..." \
  -H "Idempotency-Key: 3f0c1d7e-8b1a-4f3e-9a51-6d2b7c9e0a14"
Respuesta 200
{
  "id": "cs_01JB86R800ABCDEFGHJKMNPQRS",
  "environment": "SANDBOX",
  "mode": "SETUP",
  "status": "OPEN",
  "url": "https://checkout.paygumi.com/c/3q2-7wEmWbIu4pS1Jx7bS1Kc0yQe9Gm9cXyZ0aBcDeF",
  "customer_id": "string",
  "plan_id": "string",
  "payment_method_id": "string",
  "subscription_id": "string",
  "success_url": "string",
  "cancel_url": "string",
  "metadata": {},
  "failed_attempts": 0,
  "expires_at": "2026-11-01T05:00:00Z",
  "created_at": "2026-11-01T05:00:00Z",
  "completed_at": "2026-11-01T05:00:00Z"
}