Guías

Cambiar Tarjeta de Suscripción

Cuando un suscriptor necesita cambiar la tarjeta con la que se le cobra una suscripción, el flujo tiene dos pasos:

  1. Tokenizar la nueva tarjeta — Creas un checkout en modo “setup” y le envías el enlace al cliente para que ingrese su nueva tarjeta.
  2. Actualizar la suscripción — Cuando el cliente completa el checkout, recibes el payment_method_id via webhook y lo usas para actualizar la suscripción.

Paso 1: Crear un checkout de tokenización

Crea un checkout con un item de monto 0 y charge_type: "one_time". Este checkout solo tokeniza la tarjeta sin cobrar nada.

$curl -X POST https://app.recurrente.com/api/checkouts \
>  -H "X-PUBLIC-KEY: tu_llave_publica" \
>  -H "X-SECRET-KEY: tu_llave_privada" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "items": [
>      {
>        "name": "Actualizar método de pago",
>        "currency": "GTQ",
>        "amount_in_cents": 0,
>        "charge_type": "one_time"
>      }
>    ],
>    "user_id": "us_ID_DEL_SUSCRIPTOR",
>    "success_url": "https://tusitio.com/tarjeta-actualizada",
>    "cancel_url": "https://tusitio.com/cancelado"
>  }'

Respuesta:

1{
2  "id": "ch_eegw9j5zgqoae3ms",
3  "checkout_url": "https://app.recurrente.com/checkout-session/ch_eegw9j5zgqoae3ms"
4}

Envía el checkout_url a tu cliente (por email, WhatsApp, dentro de tu app, etc.) para que ingrese su nueva tarjeta.

Incluye el user_id del suscriptor para que el checkout pre-llene sus datos (nombre, email, etc.).

Paso 2: Recibir el payment_method_id via webhook

Cuando el cliente completa el checkout, Recurrente envía un webhook setup_intent.succeeded a tu endpoint configurado. El payload incluye el payment_method_id de la nueva tarjeta:

1{
2  "id": "pa_abc123",
3  "status": "succeeded",
4  "type": "setup_intent.succeeded",
5  "payment_method": {
6    "id": "pay_m_nueva123",
7    "type": "card",
8    "card": {
9      "last4": "5678",
10      "network": "mastercard"
11    }
12  }
13}

Guarda el payment_method.id — lo necesitarás en el siguiente paso.

Si no tienes webhooks configurados, también puedes obtener el payment_method_id haciendo un GET /api/checkouts/{id} al checkout una vez que esté pagado. El campo payment_method.id estará en la respuesta.

Paso 3: Actualizar la suscripción con la nueva tarjeta

Usa el payment_method_id obtenido para actualizar la suscripción:

$curl -X PUT https://app.recurrente.com/api/subscriptions/su_ID_DE_LA_SUSCRIPCION \
>  -H "X-PUBLIC-KEY: tu_llave_publica" \
>  -H "X-SECRET-KEY: tu_llave_privada" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "payment_method_id": "pay_m_nueva123"
>  }'

Respuesta:

1{
2  "id": "su_nehndm7j",
3  "status": "active",
4  "description": "Suscripción Mensual",
5  "default_payment_method": {
6    "id": "pay_m_nueva123",
7    "type": "card",
8    "card": {
9      "last4": "5678",
10      "network": "mastercard"
11    }
12  }
13}

A partir de este momento, los siguientes cobros automáticos de la suscripción se harán con la nueva tarjeta.

Si la suscripción tiene un pago pendiente (por ejemplo, un cobro fallido), Recurrente intentará cobrarlo automáticamente con la nueva tarjeta al momento de actualizarla.

Resumen del flujo

Tu backend                    Recurrente                  Cliente
    │                              │                          │
    │── POST /api/checkouts ──────▶│                          │
    │◀── checkout_url ─────────────│                          │
    │                              │                          │
    │── Envía link al cliente ─────────────────────────────▶  │
    │                              │                          │
    │                              │◀── Ingresa nueva tarjeta─│
    │                              │                          │
    │◀── Webhook ──────────────────│                          │
    │    setup_intent.succeeded    │                          │
    │    (payment_method_id)       │                          │
    │                              │                          │
    │── PUT /api/subscriptions ───▶│                          │
    │    (payment_method_id)       │                          │
    │◀── Suscripción actualizada ──│                          │