Portal del cliente

Enlaces al portal donde tu cliente gestiona su suscripción.

Crear una sesión del portal del cliente

POST/v1/portal-sessions

Crea el enlace de un solo uso al portal ({CHECKOUT_BASE_URL}/portal/s/{token}) para que tu cliente gestione su suscripción. Créalo justo cuando el usuario hace clic en "Gestionar mi suscripción" y redirígelo con un 303: vence en 5 minutos y sirve una sola vez. No lo envíes por correo.

Cliente: customer_id o external_id (uno de los dos: 422 customer_required), del entorno de la API key (si no, 404 customer_not_found).
return_url: a dónde vuelve el botón "Volver"; por defecto, el default_return_url del portal (sin ninguno → 422 return_url_required). URL absoluta http(s) sin fragmento, https en producción (422 invalid_return_url).
Portal deshabilitado en el entorno → 409 portal_disabled.

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

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

Parámetros

Parámetros de Crear una sesión del portal del cliente
Parámetro	En	Tipo	Descripción
`Idempotency-Key`	cabecera	string	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, `CreatePortalSessionRequest`)

customer_id o external_id (uno de los dos).

Campos del cuerpo de Crear una sesión del portal del cliente
Campo	Tipo	Descripción
`customer_id`	string	Ejemplo: `cus_01JB86R800ABCDEFGHJKMNPQRS`
`external_id`	string	Ejemplo: `user_42`
`return_url`	string (uri)	Ejemplo: `https://app.acme.co/cuenta`

Respuestas

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

Esquema PortalSession

Campos de la respuesta 201
Campo	Tipo	Descripción
`id`obligatorio	string	Ejemplo: `ps_01JB86R800ABCDEFGHJKMNPQRS`
`environment`obligatorio	string	Valores: `SANDBOX,` `PRODUCTION`
`customer_id`obligatorio	string
`url`obligatorio	string \| null	`{CHECKOUT_BASE_URL}/portal/s/{token}`: solo en la respuesta de creación; `null` en la repetición con `Idempotency-Key`. Ejemplo: `https://checkout.paygumi.com/portal/s/3q2-7wEXAMPLEtokenEXAMPLEtokenEXAMPLEtoke`
`return_url`obligatorio	string (uri)
`expires_at`obligatorio	string (date-time)	RFC 3339 en UTC.
`created_at`obligatorio	string (date-time)	RFC 3339 en UTC.

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/portal-sessions \
  -H "Authorization: Bearer pgm_test_..." \
  -H "Idempotency-Key: 3f0c1d7e-8b1a-4f3e-9a51-6d2b7c9e0a14" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "cus_01JB86R800ABCDEFGHJKMNPQRS",
  "external_id": "user_42",
  "return_url": "https://app.acme.co/cuenta"
}'

Respuesta 201