Update the payment method on a subscription

When a customer’s payment method fails, or when the customer wants to switch payment methods, you can update the payment method associated with a subscription. The update affects future billing cycles only. It does not charge open invoices. Collect open invoices separately using each invoice’s hosted_invoice_url, one per invoice. Two flows let you update a subscription’s payment method:

Case A (user-initiated): Send the customer a new enrollment link. Use this when the customer must authorize a new Chilean automatic debit (PAC) mandate or enter new card details.
Case B (merchant-initiated): Associate an already-active payment method directly through the API, with no customer interaction.

Case A: Send a re-enrollment link

Create a CheckoutSession with flow: "setup" and pass the existing subscription ID in subscription. The customer opens the link and enrolls a new payment method. For cards, Fintoc associates the payment method with the subscription when enrollment completes. For PAC, Fintoc associates the payment method once the mandate activates. Server

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 responds with the CheckoutSession object:

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

Redirect the customer to redirect_url so the customer completes the enrollment.

PAC activation window

For PAC, bank confirmation takes approximately 5 business days. The new payment method stays in pending status during this window, and Fintoc has not yet executed the swap. checkout_session.finished signals that the customer completed the enrollment flow, not that the swap occurred. Wait for subscription.payment_method_updated before you treat the new payment method as active. To check the activation state while the mandate is pending, call GET /v2/payment_methods/{id} and read 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"
  }
}

Handle re-enrollment events

Subscribe to the following events when you update a subscription’s payment method through a re-enrollment link:

Event	Description	Action
`checkout_session.finished`	The customer completed the enrollment flow.	Store the new `payment_method` ID. For cards the swap already occurred; for PAC, wait for `subscription.payment_method_updated`.
`checkout_session.expired`	The session expired before the customer completed enrollment.	Create a new session and send the customer the updated link.
`subscription.payment_method_updated`	The bank confirmed the new mandate. The subscription now charges against the new payment method.	Resume normal billing. Collect any open invoices using each invoice’s `hosted_invoice_url`.
`subscription.payment_method_update_failed`	The bank rejected the mandate activation. The subscription keeps its previous payment method.	Create a new session so the customer can re-enroll. Collect open invoices using each invoice’s `hosted_invoice_url`.

Case B: Associate an existing payment method

If the customer already has an active payment method on file, associate the payment method with a subscription directly, without a new enrollment link.

Swap the payment method on an existing subscription

Call PATCH /v2/subscriptions/{id} with the ID of the active payment method. The payment method must belong to the same customer as the subscription. Server

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 returns the updated Subscription:

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

The payment method’s mandate is already active, so the swap is immediate. The payment_method value in the response points to the new payment method. Fintoc also emits subscription.payment_method_updated.

Create a new subscription with an existing payment method

Creating a subscription against a payment method the customer already has is not an update, so it lives with the rest of subscription creation. Pass the payment_method to Create a subscription, as described in Charge automatically against a payment method.

Updating the payment method on a subscription does not pay open invoices

Updating the payment method changes which method Fintoc charges for future billing cycles. It does not pay open invoices from previous cycles. If the subscription has open invoices when the swap occurs, collect them separately using each invoice’s hosted_invoice_url, one per invoice.

Edge cases

One update at a time: Only one payment method update can be in progress per subscription. A second attempt while a PAC mandate is pending returns a payment_method_update_in_progress error (409 Conflict). Billing cycle during the activation window: If a billing cycle anchor falls while a new PAC mandate is still pending, Fintoc creates the invoice in open status without an automatic charge. Collect the invoice using its hosted_invoice_url. Cancellation during activation: If you cancel the subscription while a PAC mandate awaits bank confirmation, the swap does not execute. Fintoc creates and stores the new payment method on the customer’s record, but does not associate the payment method with any subscription.

Test your integration

Using your test mode Secret Key, run both flows against a test subscription without moving money.

1) Test the re-enrollment link

Create the setup Checkout Session with the subscription of an existing test subscription, then complete the enrollment on the Fintoc-hosted page with the test credentials listed in Save a payment method for future charges. Verify that:

You receive checkout_session.finished, carrying the new payment_method ID.
You receive subscription.payment_method_updated, and your integration treats the new payment method as active only after this event.
Get a subscription reports the new payment_method.

Do not treat the swap as done on checkout_session.finished alone. That is the failure the PAC activation window describes.

2) Test the API swap

Enroll a second payment method for the same test customer, then swap it in with Update a subscription. Verify that:

The response reports the new payment_method and keeps the subscription active.
You receive subscription.payment_method_updated.
A second update while another one is still in progress returns payment_method_update_in_progress with 409 Conflict.

​Case A: Send a re-enrollment link

​PAC activation window

​Handle re-enrollment events

​Case B: Associate an existing payment method

​Swap the payment method on an existing subscription

​Create a new subscription with an existing payment method

​Updating the payment method on a subscription does not pay open invoices

​Edge cases

​Test your integration

​1) Test the re-enrollment link

​2) Test the API swap