> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Actualizar el método de pago de una suscripción

> Cambia el método de pago que cobra una suscripción de Fintoc, con un link de reenrolamiento para tu cliente o directamente por la API.

Cuando el método de pago de un cliente falla, o cuando el cliente quiere cambiarlo, puedes actualizar el método de pago asociado a una suscripción. La actualización afecta solo los ciclos de facturación futuros. No cobra las invoices abiertas. Cobra las invoices abiertas por separado usando el `hosted_invoice_url` de cada una, uno por invoice.

Hay dos flujos para actualizar el método de pago de una suscripción:

* **Caso A (iniciado por el usuario):** Envíale al cliente un nuevo link de enrolamiento. Úsalo cuando el cliente tiene que autorizar un nuevo mandato de Pago Automático de Cuentas (PAC) o ingresar los datos de una nueva tarjeta.
* **Caso B (iniciado por el comercio):** Asocia un método de pago que ya está activo directamente por la API, sin interacción del cliente.

## Caso A: Enviar un link de reenrolamiento

Crea un `CheckoutSession` con `flow: "setup"` y envía el ID de la suscripción existente en `subscription`. El cliente abre el link y enrola un nuevo método de pago. Para tarjetas, Fintoc asocia el método de pago a la suscripción cuando termina el enrolamiento. Para PAC, Fintoc asocia el método de pago cuando el mandato se activa.

**Servidor**

```bash theme={null}
curl --request POST "https://api.fintoc.com/v2/checkout_sessions" \
  --header "Authorization: YOUR_TEST_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "flow": "setup",
    "currency": "CLP",
    "subscription": "sub_456789abcdef",
    "success_url": "https://merchant.com/success",
    "cancel_url": "https://merchant.com/cancel",
    "customer": "cus_01234567",
    "payment_method_types": ["pac"]
  }'
```

```javascript Node theme={null}
const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_TEST_SECRET_API_KEY');

const checkoutSession = await fintoc.v2.checkoutSessions.create({
  flow: 'setup',
  currency: 'CLP',
  subscription: 'sub_456789abcdef',
  success_url: 'https://merchant.com/success',
  cancel_url: 'https://merchant.com/cancel',
  customer: 'cus_01234567',
  payment_method_types: ['pac']
});
```

```python theme={null}
from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_API_KEY')

checkout_session = client.v2.checkout_sessions.create(
    flow='setup',
    currency='CLP',
    subscription='sub_456789abcdef',
    success_url='https://merchant.com/success',
    cancel_url='https://merchant.com/cancel',
    customer='cus_01234567',
    payment_method_types=['pac'],
)
```

Fintoc responde con el objeto `CheckoutSession`:

```json theme={null}
{
  "id": "cs_li5531onlFDi235",
  "object": "checkout_session",
  "flow": "setup",
  "status": "created",
  "currency": "CLP",
  "mode": "test",
  "subscription": "sub_456789abcdef",
  "customer": {
    "id": "cus_01234567",
    "object": "customer",
    "name": "Test Customer 1",
    "email": "jon@snow.com",
    "metadata": {},
    "tax_id": {
      "type": "cl_rut",
      "value": "11.111.111-1"
    }
  },
  "payment_method_types": ["pac"],
  "success_url": "https://merchant.com/success",
  "cancel_url": "https://merchant.com/cancel",
  "redirect_url": "https://pay.fintoc.com/checkout/cs_li5531onlFDi235"
}
```

Redirige al cliente al `redirect_url` para que complete el enrolamiento.

### Ventana de activación del PAC

Para PAC, la confirmación del banco toma aproximadamente 5 días hábiles. El nuevo método de pago queda en estado `pending` durante esa ventana, y Fintoc todavía no ejecutó el cambio.

`checkout_session.finished` indica que el cliente completó el flujo de enrolamiento, no que el cambio ocurrió. Espera el `subscription.payment_method_updated` antes de tratar el nuevo método de pago como activo.

Para revisar el estado de activación mientras el mandato está pendiente, llama a `GET /v2/payment_methods/{id}` y lee `pac.status`:

```json theme={null}
{
  "id": "pm_000000000001",
  "object": "payment_method",
  "customer": "cus_01234567",
  "type": "pac",
  "pac": {
    "account_holder_id": "11.111.111-1",
    "account_number": "000000000000",
    "account_type": "checking_account",
    "institution": {
      "id": "cl_banco_de_chile",
      "country": "cl",
      "name": "Banco de Chile"
    },
    "status": "pending"
  }
}
```

### Maneja los eventos de reenrolamiento

Suscríbete a los siguientes eventos cuando actualizas el método de pago de una suscripción con un link de reenrolamiento:

| Evento                                      | Descripción                                                                                     | Acción                                                                                                                                 |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `checkout_session.finished`                 | El cliente completó el flujo de enrolamiento.                                                   | Guarda el ID del nuevo `payment_method`. Para tarjeta el cambio ya ocurrió; para PAC, espera el `subscription.payment_method_updated`. |
| `checkout_session.expired`                  | La sesión expiró antes de que el cliente completara el enrolamiento.                            | Crea una nueva sesión y envíale al cliente el link actualizado.                                                                        |
| `subscription.payment_method_updated`       | El banco confirmó el nuevo mandato. La suscripción ahora cobra contra el nuevo método de pago.  | Retoma la facturación normal. Cobra las invoices abiertas usando el `hosted_invoice_url` de cada una.                                  |
| `subscription.payment_method_update_failed` | El banco rechazó la activación del mandato. La suscripción mantiene su método de pago anterior. | Crea una nueva sesión para que el cliente reenrole. Cobra las invoices abiertas usando el `hosted_invoice_url` de cada una.            |

## Caso B: Asociar un método de pago existente

Si el cliente ya tiene un método de pago activo registrado, asócialo a una suscripción directamente, sin un nuevo link de enrolamiento.

### Cambia el método de pago de una suscripción existente

Llama a `PATCH /v2/subscriptions/{id}` con el ID del método de pago activo. El método de pago debe pertenecer al mismo customer que la suscripción.

**Servidor**

```bash theme={null}
curl --request PATCH "https://api.fintoc.com/v2/subscriptions/sub_456789abcdef" \
  --header "Authorization: YOUR_TEST_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "payment_method": "pm_000000000001"
  }'
```

```javascript Node theme={null}
const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_TEST_SECRET_API_KEY');

const subscription = await fintoc.v2.subscriptions.update('sub_456789abcdef', {
  payment_method: 'pm_000000000001'
});
```

```python theme={null}
from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_API_KEY')

subscription = client.v2.subscriptions.update(
    'sub_456789abcdef',
    payment_method='pm_000000000001',
)
```

Fintoc devuelve la `Subscription` actualizada:

```json theme={null}
{
  "id": "sub_456789abcdef",
  "object": "subscription",
  "billing_cycle_anchor": "2025-08-01T00:00:00Z",
  "collection_method": "charge_automatically",
  "created_at": "2025-08-01T12:00:00Z",
  "customer": "cus_01234567",
  "items": [
    {
      "id": "si_89abcdef0123",
      "object": "subscription_item",
      "price": {
        "currency": "CLP",
        "product": { "name": "Pro Plan" },
        "recurring": { "interval": "month", "interval_count": 1 },
        "unit_amount": 15000
      },
      "quantity": 1
    }
  ],
  "metadata": {},
  "mode": "test",
  "payment_method": "pm_000000000001",
  "status": "active",
  "trial_end": null
}
```

El mandato del método de pago ya está activo, así que el cambio es inmediato. El valor de `payment_method` en la respuesta apunta al nuevo método de pago. Fintoc también emite `subscription.payment_method_updated`.

### Crear una suscripción nueva con un método de pago existente

Crear una suscripción contra un método de pago que el cliente ya tiene no es una actualización, así que vive con el resto de la creación de suscripciones. Envía el `payment_method` a [Crear una suscripción](/es/api/payments-api/subscriptions/subscriptions-create), como se describe en [Cobra automáticamente contra un método de pago](/es/guides/payments/accept-recurring-payments#cobra-automáticamente-contra-un-método-de-pago).

## Actualizar el método de pago de una suscripción no paga las invoices abiertas

Actualizar el método de pago cambia qué método cobra Fintoc en los ciclos de facturación futuros. No paga las invoices abiertas de ciclos anteriores. Si la suscripción tiene invoices abiertas cuando ocurre el cambio, cóbralas por separado usando el `hosted_invoice_url` de cada una, uno por invoice.

## Casos borde

**Una actualización a la vez:** Solo puede haber una actualización de método de pago en curso por suscripción. Un segundo intento mientras un mandato PAC está `pending` devuelve un error `payment_method_update_in_progress` (`409 Conflict`).

**Ciclo de facturación durante la ventana de activación:** Si un ancla de ciclo de facturación cae mientras un nuevo mandato PAC todavía está `pending`, Fintoc crea la invoice en estado `open` sin cobro automático. Cobra la invoice usando su `hosted_invoice_url`.

**Cancelación durante la activación:** Si cancelas la suscripción mientras un mandato PAC espera la confirmación del banco, el cambio no se ejecuta. Fintoc crea y guarda el nuevo método de pago en el registro del cliente, pero no lo asocia a ninguna suscripción.

## Prueba tu integración

Usando tu [Secret Key de modo de prueba](/es/guides/resources/test-mode), ejecuta los dos flujos contra una suscripción de prueba sin mover dinero.

### 1) Prueba el link de reenrolamiento

Crea el `Checkout Session` de setup con el `subscription` de una suscripción de prueba existente, y completa el enrolamiento en la página alojada por Fintoc con las credenciales de prueba que están en [Guardar un método de pago para cobros futuros](/es/guides/payments/accept-recurring-payments/setup-a-payment-method-for-future-charges). Verifica que:

* Recibas el `checkout_session.finished`, con el ID del nuevo `payment_method`.
* Recibas el `subscription.payment_method_updated`, y que tu integración trate el nuevo método de pago como activo solo después de ese evento.
* [Obtener una suscripción](/es/api/payments-api/subscriptions/subscriptions-get) reporte el nuevo `payment_method`.

No des el cambio por hecho solo con el `checkout_session.finished`. Esa es la falla que describe la [ventana de activación del PAC](#ventana-de-activación-del-pac).

### 2) Prueba el cambio por API

Enrola un segundo método de pago para el mismo customer de prueba y cámbialo con [Actualizar una suscripción](/es/api/payments-api/subscriptions/subscriptions-update). Verifica que:

* La respuesta reporte el nuevo `payment_method` y mantenga la suscripción `active`.
* Recibas el `subscription.payment_method_updated`.
* Un segundo cambio mientras otro está en curso devuelva `payment_method_update_in_progress` con `409 Conflict`.