Create subscriptions for your customer

Create a subscription that bills your customer on a fixed schedule. Charge it automatically, or issue an invoice for each period and collect it yourself. A subscription never charges on its own. On each billing cycle, Fintoc creates an Invoice for the amount your customer owes. Fintoc then collects that invoice, or leaves it open for you to collect. The subscription schedules the charge; the invoice is the charge. Attempts, retries, and payment links all live on the invoice. Handle invoice.* events as part of the integration, not as an add-on. See Manage invoices. You can create a subscription in two ways:

With a Checkout Session. Your customer enrolls a payment method at the Fintoc-hosted checkout page, and Fintoc creates the subscription with that payment method attached. Use it when your customer has to authorize the payment method.
With the Subscriptions API. You create the subscription on your backend, with no checkout and no customer interaction. Use it when your customer already has an enrolled payment method, or when you plan to issue invoices without charging. See Create a subscription with the API.

To create a subscription with a Checkout Session, you complete four steps:

On your backend, create a Checkout Session with flow: subscription.
Redirect the customer to complete the enrollment at the Fintoc-hosted checkout page.
Handle post-enrollment and recurring payment events (webhooks).
Handle the invoices the subscription issues on every billing cycle.

This guide ends once you have tested the subscription. From there, Manage invoices covers the invoices the subscription issues on every billing cycle, and Update the payment method on a subscription covers changing the payment method it charges.

The v2 Checkout Session endpoints require API version 2026-02-01 or later. Fintoc pins your account to the version current on your first API request. If your account is pinned to an earlier version, send the Fintoc-Version: 2026-02-01 header on checkout session requests. This lets you test them without affecting the rest of your integration. See Authentication for details.

The following diagram shows how Fintoc interacts with both your backend and your frontend:

Create a Checkout Session

The Checkout Session object represents your intent to enroll a payment method for recurring charges, and to create a subscription with a fixed amount and periodicity. Using your Secret Key, create a Checkout Session on your backend with flow set to subscription. 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": "subscription",
    "amount": 350000,
    "currency": "CLP",
    "success_url": "https://merchant.com/success",
    "cancel_url": "https://merchant.com/cancel",
    "payment_method_types": [
      "pac"
    ],
    "customer_data": {
      "tax_id": {
        "type": "cl_rut",
        "value": "11.111.111-1"
      },
      "name": "Felipe Castro",
      "email": "jon@snow.com",
      "metadata": {}
    },
    "line_items": [
      {
        "price_data": {
          "currency": "CLP",
          "unit_amount": 350000,
          "product_data": {
            "name": "Plan 1"
          },
          "recurring": {
            "interval": "month",
            "interval_count": 1
          }
        },
        "quantity": 1
      }
    ],
    "metadata": {
      "subscription_external_id": "sub_987654321"
    }
  }'

Node

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

const fintoc = new Fintoc('YOUR_TEST_SECRET_API_KEY');

const checkoutSession = await fintoc.v2.checkoutSessions.create({
  flow: 'subscription',
  amount: 350000,
  currency: 'CLP',
  success_url: 'https://merchant.com/success',
  cancel_url: 'https://merchant.com/cancel',
  payment_method_types: ['pac'],
  customer_data: {
    tax_id: {
      type: 'cl_rut',
      value: '11.111.111-1'
    },
    name: 'Felipe Castro',
    email: 'jon@snow.com',
    metadata: {}
  },
  line_items: [
    {
      price_data: {
        currency: 'CLP',
        unit_amount: 350000,
        product_data: {
          name: 'Plan 1'
        },
        recurring: {
          interval: 'month',
          interval_count: 1
        }
      },
      quantity: 1
    }
  ],
  metadata: {
    subscription_external_id: 'sub_987654321'
  }
});

from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_API_KEY')

checkout_session = client.v2.checkout_sessions.create(
    flow='subscription',
    amount=350000,
    currency='CLP',
    success_url='https://merchant.com/success',
    cancel_url='https://merchant.com/cancel',
    payment_method_types=['pac'],
    customer_data={
        'tax_id': {
            'type': 'cl_rut',
            'value': '11.111.111-1',
        },
        'name': 'Felipe Castro',
        'email': 'jon@snow.com',
        'metadata': {},
    },
    line_items=[
        {
            'price_data': {
                'currency': 'CLP',
                'unit_amount': 350000,
                'product_data': {
                    'name': 'Plan 1',
                },
                'recurring': {
                    'interval': 'month',
                    'interval_count': 1,
                },
            },
            'quantity': 1,
        }
    ],
    metadata={
        'subscription_external_id': 'sub_987654321',
    },
)

Fintoc responds with the Checkout Session object. Store its id and redirect_url to continue the flow:

{
  "id": "cs_li5531onlFDi235",
  "object": "checkout_session",
  "mode": "test",
  "flow": "subscription",
  "status": "created",
  "amount": 350000,
  "currency": "CLP",
  "payment_method_types": ["pac"],
  "customer": {
    "id": "cus_NffrFeUfNV2Hib",
    "object": "customer",
    "name": "Felipe Castro",
    "email": "jon@snow.com",
    "metadata": {},
    "tax_id": {
      "type": "cl_rut",
      "value": "11.111.111-1"
    }
  },
  "line_items": [
    {
      "price": {
        "product": {
          "name": "Plan 1",
          "description": "Fixed-amount monthly plan"
        },
        "currency": "CLP",
        "unit_amount": 350000,
        "recurring": {
          "interval": "month",
          "interval_count": 1
        }
      },
      "quantity": 1
    }
  ],
  "metadata": {
    "subscription_external_id": "sub_987654321"
  },
  "success_url": "https://merchant.com/success",
  "cancel_url": "https://merchant.com/cancel",
  "redirect_url": "https://pay.fintoc.com/checkout/cs_li5531onlFDi235"
}

The response includes a redirect_url attribute. In the next step, you redirect the customer to this location to complete the subscription. The following table describes the parameters you send when creating a Checkout Session:

Parameter	Example	Description
`amount`	350000	Required. A positive integer representing the value to charge, in the smallest currency unit (for example, `1000` for `$1000 CLP`, since CLP has no minor unit, or `2476` for `$24.76 MXN`, since MXN has a minor unit). See the currencies page for details.
`currency`	`CLP`	Required. Three-letter ISO 4217 currency code for the recurring payments. One of `CLP` or `MXN`.
`flow`	`subscription`	Required. Flow type for the session. One of `payment`, `setup`, or `subscription`.
`success_url`	`https://merchant.com/success`	Required. URL to redirect the customer to after a successful enrollment.
`cancel_url`	`https://merchant.com/cancel`	Required. URL to redirect the customer to if they cancel the enrollment and return to your website.
`customer`	`cus_3B2bODrQFje7ZVkT69xyaTSDwXQ`	Required if no `customer_data`. ID of an existing `Customer`.
`customer_data`	`(object)`	Required if no `customer`. Data for inline customer creation. 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_types`	`["pac"]`	List of allowed payment methods during enrollment. One or more of `pac` (charges on bank accounts in Chile), `direct_debit` (charges on bank accounts in Mexico), and `card`.
`line_items`	`(array)`	Required. Array of items the customer subscribes to. Each item contains `quantity` and either `price` or `price_data`.
`metadata`	`{"subscription_external_id": "sub_987654321"}`	Set of key-value pairs you can attach to an object. Useful for storing additional information about the object in a structured format.

Include customer data (required for subscriptions)

When creating a Checkout Session with flow: subscription, you must include customer information. You can do this either by referencing an existing customer ID (customer) or by sending customer_data to create one inline:

Attribute	Type	Description
`tax_id`	`object`	Required if no `email`. Object that identifies the customer at a fiscal or regulatory level. The `type` is `cl_rut` for a Chilean tax ID (RUT) or `mx_rfc` for a 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 address of the customer.
`metadata`	`object`	Custom data that stores additional information about the customer, for example internal IDs, CRM references, or tags.

Include an items list (required for subscriptions)

When creating a Checkout Session with flow: subscription, you must include the items the customer subscribes to. This information lets Fintoc display the items on the checkout page and show only the payment methods available for specific products.

Attribute	Type	Description
`quantity`	`integer`	Required. Number of units of this item being purchased.
`price_data`	`object`	Required. Data used to generate a new recurring price inline.

Each item in line_items must include price_data.

`price_data` object

Attribute	Type	Description
`product_data`	`object`	Required. Data used to generate a new `Product` object inline.
`currency`	`string`	Three-letter ISO 4217 currency code for the subscription. One of `CLP` or `MXN`.
`unit_amount`	`integer`	Required. A positive integer representing the price per unit, in the smallest currency unit (for example, `1000` for `$1000 CLP`, since CLP has no minor unit, or `2476` for `$24.76 MXN`, since MXN has a minor unit).
`recurring`	`object`	Required. Recurring configuration. `interval` is one of `day`, `week`, `month`, or `year`, and `interval_count` is the number of intervals between charges (for example, `1` for monthly when `interval` is `month`).

`product_data` object

Attribute	Type	Description
`name`	`string`	Required. Name of the product or service being purchased.
`image_url`	`string`	Image URL for the product. Must be an HTTPS URL. Recommended aspect ratio: 9:4.

Redirect the customer to complete the enrollment

Next, redirect the customer to the Fintoc-hosted checkout page using the redirect_url. After the customer completes the enrollment, Fintoc redirects the customer back to your site: to the success_url on success, or to the cancel_url if they cancel. Client

window.location.assign(REDIRECT_URL_FROM_YOUR_BACKEND);

Handle post-session events

Once a Checkout Session finishes, you handle the result in your frontend and complete the subscription in your backend. For your backend, you use the events that Fintoc sends through webhooks.

Complete the subscription on your backend

Fintoc sends a checkout_session.finished event when the session completes. In a subscription flow, this event includes information about the session and references to the subscription and payment_method created during enrollment.

{
  "id": "evt_a4xK32BanKWYn",
  "object": "event",
  "type": "checkout_session.finished",
  "data": {
    "id": "cs_li5531onlFDi235",
    "flow": "subscription",
    "customer": {
      "id": "cus_NffrFeUfNV2Hib",
      "object": "customer",
      "name": "Felipe Castro",
      "email": "jon@snow.com",
      "metadata": {},
      "tax_id": {
        "type": "cl_rut",
        "value": "11.111.111-1"
      }
    },
    "payment_method_types": ["pac"],
    "status": "finished",
    "payment_status": "succeeded",
    "subscription": "sub_NffrFeUfNV2Hib",
    "payment_method": "pm_NffrFeUfNV2Hib"
  }
}

You should handle the following post-session events:

Event	Description	Action
`checkout_session.finished`	Sent when a subscription `Checkout Session` reaches a final state.	Store the created IDs (`subscription`, `payment_method`, `customer`). With `charge_automatically`, wait for `invoice.payment_succeeded` before you grant your customer access: the subscription is still `incomplete` at this point.
`checkout_session.expired`	Sent when a session expires.	Offer the customer another attempt to subscribe.
`payment_intent.succeeded`	Sent when a payment intent succeeds, like a charge on a bank account or card.	Confirm to your customer that the subscription charge succeeded.
`payment_intent.failed`	Sent when a payment intent fails.	Offer the customer another attempt to pay the subscription.

Create a subscription with the API

When your customer does not need to enroll a payment method in a checkout, create the subscription directly with Create a subscription. You need an existing customer and the items the subscription bills on every cycle. The collection_method decides how Fintoc collects every invoice the subscription generates:

charge_automatically, the default, charges a payment_method on every billing cycle. The payment method is required.
send_invoice leaves every invoice open for you to collect. The payment method is optional.

Charge automatically against a payment method

Pass the payment_method Fintoc charges on every billing cycle. It must belong to the customer, be active, and be a pac or a card. Subscriptions do not support bank_transfer. Server

curl --request POST "https://api.fintoc.com/v2/subscriptions" \
  --header "Authorization: YOUR_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "customer": "cus_NffrFeUfNV2Hib",
    "payment_method": "pm_NffrFeUfNV2Hib",
    "collection_method": "charge_automatically",
    "items": [
      {
        "price_data": {
          "currency": "CLP",
          "unit_amount": 350000,
          "product_data": {
            "name": "Plan 1"
          },
          "recurring": {
            "interval": "month",
            "interval_count": 1
          }
        },
        "quantity": 1
      }
    ],
    "metadata": {
      "subscription_external_id": "sub_987654321"
    }
  }'

Node

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

const fintoc = new Fintoc('YOUR_SECRET_API_KEY');

const subscription = await fintoc.v2.subscriptions.create({
  customer: 'cus_NffrFeUfNV2Hib',
  payment_method: 'pm_NffrFeUfNV2Hib',
  collection_method: 'charge_automatically',
  items: [
    {
      price_data: {
        currency: 'CLP',
        unit_amount: 350000,
        product_data: {
          name: 'Plan 1'
        },
        recurring: {
          interval: 'month',
          interval_count: 1
        }
      },
      quantity: 1
    }
  ],
  metadata: {
    subscription_external_id: 'sub_987654321'
  }
});

from fintoc import Fintoc

client = Fintoc('YOUR_SECRET_API_KEY')

subscription = client.v2.subscriptions.create(
    customer='cus_NffrFeUfNV2Hib',
    payment_method='pm_NffrFeUfNV2Hib',
    collection_method='charge_automatically',
    items=[
        {
            'price_data': {
                'currency': 'CLP',
                'unit_amount': 350000,
                'product_data': {
                    'name': 'Plan 1',
                },
                'recurring': {
                    'interval': 'month',
                    'interval_count': 1,
                },
            },
            'quantity': 1,
        }
    ],
    metadata={
        'subscription_external_id': 'sub_987654321'
    }
)

Parameter	Example	Description
`customer`	`cus_NffrFeUfNV2Hib`	Required. ID of the `Customer` the subscription bills.
`items`	See the example above	Required. Items the subscription bills for on every billing cycle. Each item takes the same `price_data` and `product_data` objects as a checkout session’s `line_items`. Set each `unit_amount` in the smallest currency unit. Up to 10 items, all sharing the same `interval` and `interval_count`.
`payment_method`	`pm_NffrFeUfNV2Hib`	Payment method Fintoc charges on every billing cycle. Required with `charge_automatically`, optional with `send_invoice`. Must belong to `customer`, be `active`, and be a `pac` or a `card`.
`collection_method`	`charge_automatically`	How Fintoc collects every invoice the subscription generates. One of `charge_automatically` or `send_invoice`. Defaults to `charge_automatically`.
`trial_end`	`2026-10-01T00:00:00Z`	ISO 8601 timestamp in UTC at which a trial ends, at least one day in the future. During the trial the subscription is `trialing` and Fintoc issues no invoice. Fintoc anchors the billing cycle to `trial_end` and issues the first invoice then. Omit for no trial.
`metadata`	`{ "subscription_external_id": "sub_987654321" }`	Set of key-value pairs for storing additional information.

Fintoc responds with the created subscription:

{
  "id": "sub_NffrFeUfNV2Hib",
  "object": "subscription",
  "billing_cycle_anchor": "2026-08-28T15:00:00Z",
  "collection_method": "charge_automatically",
  "created_at": "2026-08-28T15:00:00Z",
  "customer": "cus_NffrFeUfNV2Hib",
  "items": [
    {
      "id": "si_2c4mDfkPLLrLTCJ3wPCEHGYpkVf",
      "object": "subscription_item",
      "price": {
        "currency": "CLP",
        "unit_amount": 350000,
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "product": {
          "id": "prod_2c4mDgwQqkNwMHnXSc4DBjkbcWz",
          "object": "product",
          "name": "Plan 1",
          "description": null,
          "image_url": null,
          "metadata": {},
          "mode": "live",
          "created_at": "2026-08-28T15:00:00Z"
        }
      },
      "quantity": 1
    }
  ],
  "metadata": { "subscription_external_id": "sub_987654321" },
  "mode": "live",
  "payment_method": "pm_NffrFeUfNV2Hib",
  "status": "incomplete",
  "trial_end": null
}

The subscription starts incomplete, not active. Fintoc finalizes the initial invoice during subscription creation and charges the payment method. The subscription becomes active once that first payment succeeds. Track the outcome with the invoice.* events described in Manage invoices.

Issue invoices without charging

Set collection_method to send_invoice and leave out payment_method. Fintoc issues one invoice per billing cycle and leaves each one open, so the subscription never charges anyone on its own. Server

curl --request POST "https://api.fintoc.com/v2/subscriptions" \
  --header "Authorization: YOUR_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "customer": "cus_NffrFeUfNV2Hib",
    "collection_method": "send_invoice",
    "items": [
      {
        "price_data": {
          "currency": "CLP",
          "unit_amount": 350000,
          "product_data": {
            "name": "Plan 1"
          },
          "recurring": {
            "interval": "month",
            "interval_count": 1
          }
        },
        "quantity": 1
      }
    ]
  }'

The subscription starts active when you create it, and the initial invoice stays open. active does not mean your customer paid. With send_invoice there is no charge to wait for, so Fintoc skips the incomplete status. Track the status of each invoice to know what your customer owes. You can attach a payment method later with Update a subscription, which lets you charge open invoices on demand. For the ways to settle an open invoice, see Collect the invoices yourself instead of charging automatically.

Test your integration

To confirm that your integration works correctly, you can simulate subscriptions and scheduled recurring payments without moving any money.

1) Create a subscription Checkout Session using test user credentials

Using your test mode Secret Key, create a Checkout Session with flow: subscription on your backend. Then complete the enrollment on the Fintoc-hosted checkout page with the following credentials: Test credentials

Username (RUT): 11.111.111-1
Password: jonsnow

2) Handle simulated scheduled payments of the subscription

In test mode, Fintoc simulates scheduled subscription payments so you can verify success and failure handling without moving money. You handle simulated payments through the same invoice.* and payment_intent.* events described in Manage invoices. A successful charge emits invoice.payment_succeeded, invoice.paid, and payment_intent.succeeded. A failed charge emits invoice.payment_failed and payment_intent.failed.

Test mode is not yet available for recurring payments in Mexico.

​Create a Checkout Session

​Include customer data (required for subscriptions)

​Include an items list (required for subscriptions)

​price_data object

​product_data object

​Redirect the customer to complete the enrollment

​Handle post-session events

​Complete the subscription on your backend

​Create a subscription with the API

​Charge automatically against a payment method

​Issue invoices without charging

​Test your integration

​1) Create a subscription Checkout Session using test user credentials

​2) Handle simulated scheduled payments of the subscription

Create a Checkout Session

Include customer data (required for subscriptions)

Include an items list (required for subscriptions)

`price_data` object

`product_data` object

Redirect the customer to complete the enrollment

Handle post-session events

Complete the subscription on your backend

Create a subscription with the API

Charge automatically against a payment method

Issue invoices without charging

Test your integration

1) Create a subscription Checkout Session using test user credentials

2) Handle simulated scheduled payments of the subscription