Portal del cliente

Deja que tus clientes vean sus pagos, actualicen su tarjeta, paguen un cobro rechazado o cancelen, sin construir esas pantallas.

El portal del cliente (checkout.paygumi.com/portal) es donde tu cliente gestiona su suscripción por su cuenta, con la marca de tu empresa:

Ver sus suscripciones: plan, estado, monto y próxima fecha de cobro.
Ver su historial de pagos.
Actualizar su tarjeta.
Pagar ahora un cobro rechazado.
Cancelar (y deshacer la cancelación mientras el periodo no termine).
Si lo permites: cambiar de plan y pausar.

Tu cliente no tiene cuenta en Paygumi: quien lo autentica eres tú. Por eso entra con una sesión de portal que crea tu backend.

Crear la sesión

Pon en tu app un botón como "Gestionar mi suscripción". Al hacer clic, tu backend crea la sesión y redirige al usuario:

curl https://api.paygumi.com/v1/portal-sessions \
  -H "Authorization: Bearer pgm_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_42",
    "return_url": "https://tuapp.co/cuenta"
  }'

{
  "id": "ps_01JB86R800ABCDEFGHJKMNPQRS",
  "environment": "SANDBOX",
  "customer_id": "cus_01JB86R800ABCDEFGHJKMNPQRS",
  "url": "https://checkout.paygumi.com/portal/s/3q2-7wEXAMPLEtokenEXAMPLEtokenEXAMPLEtoke",
  "return_url": "https://tuapp.co/cuenta",
  "expires_at": "2026-11-01T05:05:00Z",
  "created_at": "2026-11-01T05:00:00Z"
}

Redirige a url con un 303 See Other.

Identifica al cliente con customer_id o con tu external_id (uno de los dos).
return_url es a dónde lleva el botón "Volver" del portal. Si no la envías, se usa la URL de retorno por defecto que configuraste en el panel.
El enlace vence en 5 minutos y sirve una sola vez. Créalo justo en el clic; no lo envíes por correo ni lo guardes.
Al abrirlo, el portal da a tu cliente un acceso de 60 minutos. Al vencer, vuelve a tu app para entrar de nuevo.

Qué puede hacer tu cliente

Lo decides en el panel, en Configuración → Portal del cliente, por entorno:

Opción	Valores
Portal habilitado	Sí / no. Deshabilitado, crear la sesión responde `409 portal_disabled`.
Cancelación	Deshabilitada, al final del periodo o inmediata.
Motivos de cancelación	Lista de motivos a preguntar (o ninguno).
Cambio de plan	Sí / no, y a qué planes. Se aplica al cierre del periodo.
Pausa	Sí / no.
URL de retorno por defecto	A dónde vuelve el cliente si la sesión no trae `return_url`.
URL de soporte	Enlace de ayuda de tu empresa.

Las reglas se validan en Paygumi, no solo en la pantalla: tu cliente no puede hacer nada que no permitiste.

Las acciones del portal generan los mismos webhooks que las de tu API (subscription.updated, subscription.canceled, subscription.plan_changed, payment_method.added…), con initiated_by: "customer_portal". Si el cliente canceló, data.cancellation trae el motivo:

{
  "type": "subscription.canceled",
  "initiated_by": "customer_portal",
  "data": {
    "subscription": { "id": "sub_01JB86R800ABCDEFGHJKMNPQRS", "status": "canceled", "access_status": "revoked" },
    "cancellation": { "reason": "Muy caro", "comment": "Lo retomo en enero" }
  }
}

Cuando el cliente actualiza su tarjeta y tenía un cobro rechazado, Paygumi lo reintenta de inmediato y recibes payment.approved o payment.declined.

Portal del cliente

Crear la sesión

Qué puede hacer tu cliente

Cómo te enteras