> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recurrente.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recurrente.com/_mcp/server.

# Cambiar Tarjeta de Suscripción

> Permite a tus suscriptores actualizar su método de pago via API

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` vía webhook o consultando el checkout y lo usas para actualizar la suscripción.

## Paso 1: Crear un checkout de tokenización

Crea un checkout con `mode: "setup"`. Este checkout solo tokeniza la tarjeta sin cobrar nada.

```bash
curl -X POST https://app.recurrente.com/api/checkouts \
  -H "X-SECRET-KEY: tu_llave_secreta" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "setup",
    "user_id": "us_ID_DEL_SUSCRIPTOR",
    "success_url": "https://tusitio.com/tarjeta-actualizada",
    "cancel_url": "https://tusitio.com/cancelado"
  }'
```

**Respuesta:**

```json
{
  "id": "ch_eegw9j5zgqoae3ms",
  "checkout_url": "https://app.recurrente.com/checkout-session/ch_eegw9j5zgqoae3ms"
}
```

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

> **Note**
>
> 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 método guardado viene dentro de `data.checkout.payment_method`:

```json
{
  "eventType": "setup_intent.succeeded",
  "data": {
    "event_type": "setup_intent.succeeded",
    "status": "succeeded",
    "checkout": {
      "id": "ch_eegw9j5zgqoae3ms",
      "status": "paid",
      "payment_method": {
        "id": "pay_m_nueva123",
        "type": "card",
        "card": {
          "last4": "5678",
          "network": "mastercard"
        }
      }
    }
  }
}
```

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

> **Note**
>
> 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:

```bash
curl -X PUT https://app.recurrente.com/api/subscriptions/su_ID_DE_LA_SUSCRIPCION \
  -H "X-SECRET-KEY: tu_llave_secreta" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_id": "pay_m_nueva123"
  }'
```

**Respuesta:**

```json
{
  "id": "su_nehndm7j",
  "status": "active",
  "description": "Suscripción Mensual",
  "default_payment_method": {
    "id": "pay_m_nueva123",
    "type": "card",
    "card": {
      "last4": "5678",
      "network": "mastercard"
    }
  }
}
```

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

> **Note**
>
> 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 ──│                          │
```