Save a payment method for future charges

Save a customer’s payment method once and charge it later for on-demand or variable-amount payments, without creating a recurring subscription. Unlike the subscription flow, the setup flow does not couple enrollment with recurring billing, so you decide when and how much to charge. Set up a payment method and charge it later in four steps:

On your backend, create a Checkout Session with flow: setup.
Redirect your customer to complete the enrollment at the Fintoc-hosted checkout page.
Handle post-session events to save the payment_method and customer.
Charge the saved payment method on demand, by creating an invoice or a Payment Intent.

The following diagram shows how the setup flow works:

Create a Checkout Session

The Checkout Session with the setup flow represents your intent to save a payment method for future charges, without creating a recurring subscription. Using your Secret Key, create a Checkout Session on your backend with flow set to setup: Server

curl --request POST "https://api.fintoc.com/v2/checkout_sessions" \
  --header "Authorization: YOUR_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "flow": "setup",
    "currency": "CLP",
    "success_url": "https://merchant.com/success",
    "cancel_url": "https://merchant.com/cancel",
    "customer_data": {
      "tax_id": {
        "type": "cl_rut",
        "value": "11.111.111-1"
      },
      "name": "Felipe Castro",
      "email": "jon@snow.com"
    },
    "metadata": {}
  }'

Node

const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_SECRET_API_KEY');

const checkoutSession = await fintoc.v2.checkoutSessions.create({
  flow: 'setup',
  currency: 'CLP',
  success_url: 'https://merchant.com/success',
  cancel_url: 'https://merchant.com/cancel',
  customer_data: {
    tax_id: {
      type: 'cl_rut',
      value: '11.111.111-1'
    },
    name: 'Felipe Castro',
    email: 'jon@snow.com'
  },
  metadata: {}
});

from fintoc import Fintoc

client = Fintoc('YOUR_SECRET_API_KEY')

checkout_session = client.v2.checkout_sessions.create(
    flow='setup',
    currency='CLP',
    success_url='https://merchant.com/success',
    cancel_url='https://merchant.com/cancel',
    customer_data={
        'tax_id': {
            'type': 'cl_rut',
            'value': '11.111.111-1'
        },
        'name': 'Felipe Castro',
        'email': 'jon@snow.com'
    },
    metadata={}
)

After creating the Checkout Session, Fintoc responds with the session details and a redirect_url:

{
  "id": "cs_li5531onlFDi235",
  "object": "checkout_session",
  "flow": "setup",
  "status": "created",
  "currency": "CLP",
  "customer": {
    "id": "cus_NffrFeUfNV2Hib",
    "object": "customer",
    "email": "jon@snow.com",
    "metadata": {},
    "name": "Felipe Castro",
    "tax_id": {
      "type": "cl_rut",
      "value": "11.111.111-1"
    }
  },
  "success_url": "https://merchant.com/success",
  "cancel_url": "https://merchant.com/cancel",
  "redirect_url": "https://pay.fintoc.com/checkout/cs_li5531onlFDi235",
  "metadata": {}
}

Parameter	Example	Description
`flow`	`setup`	Required. Flow type for the session. One of `payment`, `setup`, or `subscription`. Use `setup` to save a payment method without charging.
`currency`	`CLP`	Required. Three-letter ISO 4217 currency code. One of `CLP` or `MXN`.
`success_url`	`https://merchant.com/success`	Required. URL to redirect the customer after a successful enrollment.
`cancel_url`	`https://merchant.com/cancel`	Required. URL to redirect the customer if they cancel the enrollment.
`payment_method_types`	`["pac"]`	Payment methods available for the enrollment. One or more of `pac` (Chilean direct debit), `direct_debit` (Mexico), or `card`.
`customer`	`cus_3B2bODrQFje7ZVkT69xyaTSDwXQ`	Required if no `customer_data`. ID of an existing `Customer`.
`customer_data`	`{ tax_id: {...}, ... }`	Required if no `customer`. Data for inline customer creation. Send at least one of `email` or `tax_id`. If a `Customer` with the same `tax_id` already exists, the request returns a `409 Conflict` error. To reuse an existing `Customer`, send its `id` in `customer` instead of `customer_data`.
`payment_method_options`	`{ pac: { ... } }`	Options specific to each payment method, keyed by values in `payment_method_types` (for example, `pac`). For `pac`, restrict the `sender_account` with `types` (`checking_account`), `institution_id`, or `holder_id`; for `card`, restrict `kinds` (`credit`, `debit`). To apply no restriction, omit the option instead of sending an empty array because an empty array allows nothing.
`metadata`	`{ "order": "987654321" }`	Set of key-value pairs for storing additional information.

Difference from the subscription flowWhen you create a Checkout Session with flow: setup, Fintoc enrolls the customer’s payment method and creates a PaymentMethod, but does not create a subscription or schedule any recurring charges. You control when and how much to charge by creating future payment intents.

Include customer data

When creating a Checkout Session for setup, you must include customer information.

Attribute	Type	Description
`tax_id`	`object`	Required if no `email`. Object that identifies the customer at a fiscal or regulatory level. The `type` is one of `cl_rut` (Chilean tax ID, RUT) or `mx_rfc` (Mexican tax ID, RFC), and `value` is the tax identifier as a string. See the Customer object. If a `Customer` with the same `tax_id` already exists, the request returns a `409 Conflict` error. To reuse an existing `Customer`, send its `id` in `customer` instead of `customer_data`.
`name`	`string`	Full name of the customer.
`email`	`string`	Required if no `tax_id`. Email used to notify the customer about the enrollment and charges.
`metadata`	`object`	Set of key-value pairs for storing additional information.

Redirect the customer to complete the enrollment

Next, redirect the customer to the redirect_url from the response. The customer sees the Fintoc-hosted checkout page where they complete the enrollment. After the customer completes the enrollment, Fintoc automatically redirects them to your success_url or cancel_url, depending on the outcome. Client

window.location.assign(REDIRECT_URL_FROM_YOUR_BACKEND);

Handle post-session events

Always use webhooks to determine the final outcome. Customers may close the tab, lose connection, or never reach your success_url.

Checkout Session events

When the enrollment completes, Fintoc sends a checkout_session.finished event with the customer and payment_method information:

{
  "id": "evt_a4xK32BanKWYn",
  "object": "event",
  "type": "checkout_session.finished",
  "data": {
    "id": "cs_li5531onlFDi235",
    "object": "checkout_session",
    "mode": "live",
    "flow": "setup",
    "status": "finished",
    "currency": "CLP",
    "customer": {
      "id": "cus_NffrFeUfNV2Hib",
      "name": "Felipe Castro",
      "email": "jon@snow.com",
      "tax_id": {
        "type": "cl_rut",
        "value": "11.111.111-1"
      }
    },
    "payment_method": "pm_NffrFeUfNV2Hib",
    "metadata": {},
    "success_url": "https://merchant.com/success",
    "cancel_url": "https://merchant.com/cancel"
  }
}

Payment Method events

Fintoc also sends a payment_method.activated event. The event’s data field contains a PaymentMethod like this:

{
  "id": "pm_NffrFeUfNV2Hib",
  "object": "payment_method",
  "card": null, 
  "created_at": "2021-10-15T15:22:11.474Z",
  "customer": "cus_NffrFeUfNV2Hib",
  "mode": "live",
  "metadata": {},
  "pac": {
    "account_holder_id": "11.111.111-1",
    "account_number": "000000000000",
    "account_type": "checking_account",
    "institution": {
      "id": "cl_banco_falabella",
      "country": "cl",
      "name": "Banco Falabella"
    },
    "status": "active"
  },
  "type": "pac"
}

Store both the customer ID and the payment_method ID. You need them to create charges later.

Events summary

You should subscribe to all the following post-session events:

Event	Description	Recommended action
`checkout_session.finished`	Session successfully completed. Method enrolled.	Store `customer` + `payment_method`.
`checkout_session.expired`	Session expired before the customer completed enrollment.	Allow the customer to retry.
`payment_method.activated`	Payment method is active and ready for charges.	Create charges against this method when needed.
`payment_method.canceled`	Payment method is canceled and not available for charges.	Stop creating charges against the method.

Create a charge against the saved payment method

Once the payment method is active, you can charge it in two ways:

Create an invoice and let Fintoc collect it. The invoice records what your customer owes, keeps the history of every charge attempt, and gives you a payment link to fall back on. Use it when the charge settles a debt, including recurring collection.
Create a Payment Intent directly. Use it for a one-off charge that you don’t need to track as a debt.

Both paths end in a payment_intent. The difference is where the payment_intent lives: a charge made through an invoice stays anchored to the invoice, so you can retry it, switch payment methods, and reconcile it against the amount owed.

Charge the payment method through an invoice

Collecting an invoice takes two calls: you create the invoice, and then you finalize it. Fintoc never finalizes an invoice you create yourself.

1) Create the invoice

Create the Invoice for the customer, with default_payment_method set to the payment method you saved: Server

curl --request POST "https://api.fintoc.com/v2/invoices" \
  --header "Authorization: YOUR_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "customer": "cus_NffrFeUfNV2Hib",
    "default_payment_method": "pm_NffrFeUfNV2Hib",
    "collection_method": "charge_automatically",
    "lines": [
      {
        "name": "Monthly plan",
        "amount": 150000,
        "currency": "CLP",
        "quantity": 1
      }
    ],
    "metadata": {
      "order_id": "order_98765"
    }
  }'

Node

const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_SECRET_API_KEY');

const invoice = await fintoc.v2.invoices.create({
  customer: 'cus_NffrFeUfNV2Hib',
  default_payment_method: 'pm_NffrFeUfNV2Hib',
  collection_method: 'charge_automatically',
  lines: [
    {
      name: 'Monthly plan',
      amount: 150000,
      currency: 'CLP',
      quantity: 1
    }
  ],
  metadata: {
    order_id: 'order_98765'
  }
});

from fintoc import Fintoc

client = Fintoc('YOUR_SECRET_API_KEY')

invoice = client.v2.invoices.create(
    customer='cus_NffrFeUfNV2Hib',
    default_payment_method='pm_NffrFeUfNV2Hib',
    collection_method='charge_automatically',
    lines=[
        {
            'name': 'Monthly plan',
            'amount': 150000,
            'currency': 'CLP',
            'quantity': 1,
        }
    ],
    metadata={
        'order_id': 'order_98765'
    }
)

Parameter	Example	Description
`customer`	`cus_NffrFeUfNV2Hib`	Required. ID of the `Customer` the invoice bills.
`lines`	`[{ "name": "Monthly plan", "amount": 150000, "currency": "CLP", "quantity": 1 }]`	Required. Line items to include in the invoice. Each line needs `name`, `amount`, `currency`, and `quantity`; `amount` is in the smallest currency unit. All lines share the same currency, and their sum becomes the invoice `total`.
`default_payment_method`	`pm_NffrFeUfNV2Hib`	The saved payment method Fintoc charges when you finalize the invoice. Required with `charge_automatically`. Must belong to `customer`.
`collection_method`	`charge_automatically`	How Fintoc collects the invoice. One of `charge_automatically`, which charges `default_payment_method` on finalization, or `send_invoice`, which leaves the invoice open for you to collect. Defaults to `charge_automatically`.
`metadata`	`{ "order_id": "order_98765" }`	Set of key-value pairs for storing additional information. Use `metadata` or the invoice `id` to reconcile the charge, instead of the amount.

Fintoc responds with the invoice in draft status:

{
  "id": "inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe",
  "object": "invoice",
  "attempt_count": 0,
  "collection_method": "charge_automatically",
  "created_at": "2026-08-10T15:22:11.474Z",
  "currency": "CLP",
  "customer": "cus_NffrFeUfNV2Hib",
  "default_payment_method": "pm_NffrFeUfNV2Hib",
  "external_payment": false,
  "hosted_invoice_url": null,
  "lines": [
    {
      "id": "il_2bVdX0PqJs6RhNu9FmZlTo2EyKq",
      "object": "line_item",
      "name": "Monthly plan",
      "description": null,
      "amount": 150000,
      "currency": "CLP",
      "period_end": null,
      "period_start": null,
      "quantity": 1
    }
  ],
  "metadata": { "order_id": "order_98765" },
  "mode": "live",
  "next_payment_attempt_at": null,
  "payments": [],
  "status": "draft",
  "subscription": null,
  "total": 150000
}

A draft invoice charges nothing. Use the draft status to review the amount or change the items with Add lines and Update a line item before you collect.

2) Finalize the invoice to charge it

Finalize the invoice to move it to open. Because collection_method is charge_automatically, Fintoc charges default_payment_method after finalization: Server

curl --request POST "https://api.fintoc.com/v2/invoices/inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe/finalize" \
  --header "Authorization: YOUR_SECRET_API_KEY"

The charge is asynchronous: the invoice stays open with a pending payment until the payment resolves. Track the outcome with invoice.payment_succeeded or invoice.payment_failed; Fintoc sends those invoice events alongside payment_intent.succeeded or payment_intent.failed.

3) Retry a failed charge

A failed charge leaves the invoice open, so the amount your customer owes stays open on the invoice. Retry the charge with Pay an invoice, against the same payment method or against another active payment method of the same customer: Server

curl --request POST "https://api.fintoc.com/v2/invoices/inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe/pay" \
  --header "Authorization: YOUR_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "payment_method": "pm_OtherMethodOfTheCustomer"
  }'

Omit payment_method to charge the invoice’s default_payment_method. Fintoc appends every attempt to the invoice’s payments array with its own payment_intent and status, so the invoice holds the full history of how you tried to collect it. To settle an invoice you collected outside Fintoc, by bank transfer or in cash, call the same endpoint with external_payment set to true. Fintoc moves the invoice to paid without charging anything, and reports external_payment as true.

Collect the invoice without charging the saved method

To let your customer pay instead of charging them, create the invoice with collection_method set to send_invoice. Fintoc then leaves the invoice open when you finalize it, instead of charging it, and default_payment_method becomes optional: Server

curl --request POST "https://api.fintoc.com/v2/invoices" \
  --header "Authorization: YOUR_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "customer": "cus_NffrFeUfNV2Hib",
    "collection_method": "send_invoice",
    "lines": [
      {
        "name": "Monthly plan",
        "amount": 150000,
        "currency": "CLP",
        "quantity": 1
      }
    ]
  }'

Call Finalize an invoice to move it to open. Once the invoice reaches open, its hosted_invoice_url points to a Fintoc-hosted payment page. Your customer can pay there with the payment methods enabled on your organization’s account, without needing a saved payment method. Send that link to your customer through your own channel, such as email or WhatsApp. Fintoc does not contact your customer through any channel.

Handle invoice events

Subscribe to the following events to track the invoice:

Event	Description	Recommended action
`invoice.created`	Sent when you create the invoice.	Store the invoice `id` against your own record of the amount owed.
`invoice.finalized`	Sent when the invoice becomes `open` and ready for payment.	Store the `hosted_invoice_url`. Send it to your customer only if you are not charging automatically, or if the charge fails.
`invoice.payment_created`	Sent when a payment on the invoice starts, either from your charge or from your customer using the `hosted_invoice_url`.	Treat the event as informational. An invoice accepts only one payment at a time.
`invoice.payment_succeeded`	Sent when Fintoc collects the invoice payment.	Confirm the payment to your customer.
`invoice.paid`	Sent on every transition to `paid`, whether Fintoc collected the invoice or you marked it as paid outside Fintoc.	Settle the amount owed in your records. Read `external_payment` to tell whether the money went through Fintoc.
`invoice.payment_failed`	Sent when a payment attempt on the invoice fails.	Retry with Pay an invoice, or send the `hosted_invoice_url`.
`invoice.voided`	Sent when you void the invoice and Fintoc disables its `hosted_invoice_url`.	Update your records.

Charge the payment method with a Payment Intent

Charge the saved payment_method directly by creating a Payment Intent with the payment_method and customer IDs: Server

curl --request POST "https://api.fintoc.com/v2/payment_intents" \
  --header "Authorization: YOUR_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "amount": 150000,
    "currency": "CLP",
    "customer": "cus_NffrFeUfNV2Hib",
    "payment_method": "pm_NffrFeUfNV2Hib",
    "metadata": {
      "order_id": "order_98765"
    }
  }'

Node

const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_SECRET_API_KEY');

const paymentIntent = await fintoc.v2.paymentIntents.create({
  amount: 150000,
  currency: 'CLP',
  customer: 'cus_NffrFeUfNV2Hib',
  payment_method: 'pm_NffrFeUfNV2Hib',
  metadata: {
    order_id: 'order_98765'
  }
});

from fintoc import Fintoc

client = Fintoc('YOUR_SECRET_API_KEY')

payment_intent = client.v2.payment_intents.create(
    amount=150000,
    currency='CLP',
    customer='cus_NffrFeUfNV2Hib',
    payment_method='pm_NffrFeUfNV2Hib',
    metadata={
        'order_id': 'order_98765'
    }
)

Parameter	Example	Description
`amount`	`150000`	Required. A positive integer representing the amount to charge in the smallest currency unit (for example, `150000` for `CLP 150000`, since CLP has no minor unit, or `10000` for `MXN 100.00`).
`currency`	`CLP`	Required. Three-letter ISO 4217 currency code. One of `CLP` or `MXN`.
`customer`	`cus_NffrFeUfNV2Hib`	Required. ID of the `Customer` to charge.
`payment_method`	`pm_NffrFeUfNV2Hib`	Required. The saved payment method ID.
`metadata`	`{ "order_id": "order_98765" }`	Set of key-value pairs for storing additional information.

Fintoc responds with the created Payment Intent:

{
  "id": "pi_34i0T5AWRfIDMOJnhq9BgxXUiyt",
  "object": "payment_intent",
  "status": "created",
  "amount": 150000,
  "currency": "CLP",
  "customer": "cus_NffrFeUfNV2Hib",
  "payment_method": "pm_NffrFeUfNV2Hib",
  "metadata": {
    "order_id": "order_98765"
  }
}

Handle payment events

Fintoc sends these events for every charge, whether you created the charge through an invoice or as a standalone Payment Intent. Subscribe to them to track the payment outcome:

Event	Description	Recommended action
`payment_intent.succeeded`	The charge was successful.	Fulfill the order and confirm to the customer.
`payment_intent.failed`	The charge failed.	Retry the charge or ask for another payment method.

Test your integration

Using your test mode API Secret Key, create Checkout Sessions that simulate the full setup and payment flow without moving any money.

1) Create a setup Checkout Session using test credentials

Create a Checkout Session with flow: setup using your test mode Secret Key. Complete the enrollment flow on the Fintoc-hosted page using the following credentials: Test credentials:

PAC

Username (RUT): 11.111.111-1
Password: jonsnow

Select the account based on the final outcome you want to test:

Account number	Type of MFA	Correct code
813990168	Security device	`000000`
422159212	Mobile Application - Success	`N/A`
5233137377	Mobile Application - Failure	`N/A`
170086177	SMS	`0000`
746326042	Coordinate Card	`['00', '00', '00']`

Card

Use these test cards for card setup flows in Chile:

Card number	Expiration date	CVV	Holder name	3DS challenge code	Final result
4111111111111111	Any future date	Any	Any	-	✅ Succeeded
4456524869770255	Any future date	Any	Any	1234	✅ Succeeded if code is correct
4574441215190335	Any future date	Any	Any	-	❌ Failed due to invalid credentials
4349003000047015	Any future date	Any	Any	-	❌ Failed due to rejected transaction

2) Verify the saved payment method

After completing the test enrollment, you should receive the checkout_session.finished and payment_method.activated webhook events. Verify that:

The payment_method ID is present in the event payload.
The customer ID matches the customer you enrolled.

3) Create a test charge against the saved method

Using the customer and payment_method IDs from step 2, create a Payment Intent against the saved method. Verify that:

You receive the payment_intent.succeeded event.
The amount matches what you sent.
The payment method used is the saved PAC or card.

Then test the invoice path with the same IDs: create an invoice with default_payment_method set to the saved method, finalize it, and verify that:

You receive invoice.created, invoice.finalized, invoice.payment_created, invoice.payment_succeeded, and invoice.paid, along with payment_intent.succeeded.
The invoice ends in paid status, with the attempt recorded in payments and your metadata persisted.

Test mode does not yet support saving a Payment Method in Mexico.

​Create a Checkout Session

​Include customer data

​Redirect the customer to complete the enrollment

​Handle post-session events

​Checkout Session events

​Payment Method events

​Events summary

​Create a charge against the saved payment method

​Charge the payment method through an invoice

​1) Create the invoice

​2) Finalize the invoice to charge it

​3) Retry a failed charge

​Collect the invoice without charging the saved method

​Handle invoice events

​Charge the payment method with a Payment Intent

​Handle payment events

​Test your integration

​1) Create a setup Checkout Session using test credentials

​PAC

​Card

​2) Verify the saved payment method

​3) Create a test charge against the saved method

Create a Checkout Session

Include customer data

Redirect the customer to complete the enrollment

Handle post-session events

Checkout Session events

Payment Method events

Events summary

Create a charge against the saved payment method

Charge the payment method through an invoice

1) Create the invoice

2) Finalize the invoice to charge it

3) Retry a failed charge

Collect the invoice without charging the saved method

Handle invoice events

Charge the payment method with a Payment Intent

Handle payment events

Test your integration

1) Create a setup Checkout Session using test credentials

PAC

Card

2) Verify the saved payment method

3) Create a test charge against the saved method