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

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

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"]
  }'

Node

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']
});

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:

{
  "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:

{
  "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

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"
  }'

Node

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'
});

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:

{
  "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, como se describe en 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, 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. 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 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.

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. 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.

​Caso A: Enviar un link de reenrolamiento

​Ventana de activación del PAC

​Maneja los eventos de reenrolamiento

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

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

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

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

​Casos borde

​Prueba tu integración

​1) Prueba el link de reenrolamiento

​2) Prueba el cambio por API