Crea suscripciones para tu cliente

Crea una suscripción que le cobre a tu cliente con una periodicidad fija. Cóbrala automáticamente, o emite una invoice por período y cóbrala tú mismo. Una suscripción nunca cobra por sí misma. En cada ciclo de facturación, Fintoc crea una Invoice por el monto que tu cliente debe. Después Fintoc la cobra, o la deja abierta para que la cobres tú. La suscripción programa el cobro; la invoice es el cobro. Los intentos, los reintentos y los links de pago viven en la invoice. Maneja los eventos invoice.* como parte de la integración, no como un agregado. Consulta Gestionar invoices. Puedes crear una suscripción de dos formas:

Con un Checkout Session. Tu cliente inscribe un método de pago en la página de checkout alojada por Fintoc, y Fintoc crea la suscripción con ese método de pago asociado. Úsalo cuando tu cliente tiene que autorizar el método de pago.
Con la API de Subscriptions. Creas la suscripción en tu backend, sin checkout y sin interacción del cliente. Úsalo cuando tu cliente ya tiene un método de pago inscrito, o cuando piensas emitir invoices sin cobrar. Consulta Crear una suscripción con la API.

Para crear una suscripción con un Checkout Session, completas cuatro pasos:

En tu backend, crea un Checkout Session con flow: subscription.
Redirige al cliente para completar el registro en la página de checkout alojada por Fintoc.
Maneja los eventos posteriores al registro y de pagos recurrentes (webhooks).
Maneja las invoices que la suscripción emite en cada ciclo de facturación.

Esta guía termina cuando ya probaste la suscripción. De ahí en adelante, Gestionar invoices cubre las invoices que la suscripción emite en cada ciclo de facturación, y Actualizar el método de pago de una suscripción cubre cómo cambiar el método de pago que cobra.

Los endpoints v2 de Checkout Session requieren la versión de API 2026-02-01 o posterior. Fintoc fija tu cuenta en la versión vigente al momento de tu primera solicitud. Si tu cuenta está fijada en una versión anterior, envía el header Fintoc-Version: 2026-02-01 en las solicitudes de checkout session. Así puedes probarlas sin afectar el resto de tu integración. Consulta Autenticación para más detalles.

El siguiente diagrama muestra cómo Fintoc interactúa tanto con tu backend como con tu frontend:

Crea una Checkout Session

El objeto Checkout Session representa tu intención de registrar un método de pago para cobros recurrentes y de crear una suscripción con un monto y periodicidad fijos. Usando tu Secret Key, crea un Checkout Session en tu backend con flow en subscription. 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": "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 responde con el objeto Checkout Session. Guarda su id y redirect_url para continuar el flujo:

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

La respuesta incluye un atributo redirect_url. En el siguiente paso, redirige al cliente a esta ubicación para completar la suscripción. La siguiente tabla describe los parámetros que envías al crear un Checkout Session:

Parámetro	Ejemplo	Descripción
`amount`	350000	Requerido. Un entero positivo que representa el valor a cobrar, en la unidad menor de la moneda (por ejemplo, `1000` para `$1000 CLP`, ya que CLP no tiene unidad menor, o `2476` para `$24.76 MXN`, ya que MXN tiene unidad menor). Consulta la página de monedas para más detalles.
`currency`	`CLP`	Requerido. Código ISO 4217 de tres letras de la moneda para los pagos recurrentes. Uno de `CLP` o `MXN`.
`flow`	`subscription`	Requerido. Tipo de flujo para la sesión. Uno de `payment`, `setup` o `subscription`.
`success_url`	`https://merchant.com/success`	Requerido. URL a la que redirigir al cliente después de un registro exitoso.
`cancel_url`	`https://merchant.com/cancel`	Requerido. URL a la que redirigir al cliente si cancela el registro y vuelve a tu sitio.
`customer`	`cus_3B2bODrQFje7ZVkT69xyaTSDwXQ`	Requerido si no hay `customer_data`. ID de un `Customer` existente.
`customer_data`	`(object)`	Requerido si no hay `customer`. Datos para crear un customer en línea. Si ya existe un `Customer` con el mismo `tax_id`, la solicitud devuelve un error `409 Conflict`. Para reutilizar un `Customer` existente, envía su `id` en `customer` en lugar de `customer_data`.
`payment_method_types`	`["pac"]`	Lista de métodos de pago permitidos durante el registro. Uno o más de `pac` (cargos en cuentas bancarias en Chile), `direct_debit` (cargos en cuentas bancarias en México) y `card`.
`line_items`	`(array)`	Requerido. Arreglo de ítems a los que se suscribe el cliente. Cada ítem contiene `quantity` y ya sea `price` o `price_data`.
`metadata`	`{"subscription_external_id": "sub_987654321"}`	Conjunto de pares clave-valor que puedes adjuntar a un objeto. Útil para almacenar información adicional sobre el objeto en un formato estructurado.

Incluir datos del cliente (requerido para suscripciones)

Al crear un Checkout Session con flow: subscription, debes incluir información del cliente. Puedes hacerlo ya sea referenciando un ID de customer existente (customer) o enviando customer_data para crear uno en línea:

Atributo	Tipo	Descripción
`tax_id`	`object`	Requerido si no hay `email`. Objeto que identifica al cliente a nivel fiscal o regulatorio. El `type` es `cl_rut` para un tax ID chileno (RUT) o `mx_rfc` para un tax ID mexicano (RFC), y `value` es el identificador fiscal como string. Consulta el objeto Customer. Si ya existe un `Customer` con el mismo `tax_id`, la solicitud devuelve un error `409 Conflict`. Para reutilizar un `Customer` existente, envía su `id` en `customer` en lugar de `customer_data`.
`name`	`string`	Nombre completo del cliente.
`email`	`string`	Requerido si no hay `tax_id`. Dirección de email del cliente.
`metadata`	`object`	Datos personalizados que almacenan información adicional sobre el cliente, por ejemplo IDs internos, referencias de CRM o etiquetas.

Incluir una lista de ítems (requerido para suscripciones)

Al crear un Checkout Session con flow: subscription, debes incluir los ítems a los que se suscribe el cliente. Esta información permite a Fintoc mostrar los ítems en la página de checkout y mostrar solo los métodos de pago disponibles para productos específicos.

Atributo	Tipo	Descripción
`quantity`	`integer`	Requerido. Número de unidades de este ítem que se compra.
`price_data`	`object`	Requerido. Datos usados para generar un nuevo precio recurrente en línea.

Cada ítem en line_items debe incluir price_data.

Objeto `price_data`

Atributo	Tipo	Descripción
`product_data`	`object`	Requerido. Datos usados para generar un nuevo objeto `Product` en línea.
`currency`	`string`	Código ISO 4217 de tres letras de la moneda para la suscripción. Uno de `CLP` o `MXN`.
`unit_amount`	`integer`	Requerido. Un entero positivo que representa el precio por unidad, en la unidad menor de la moneda (por ejemplo, `1000` para `$1000 CLP`, ya que CLP no tiene unidad menor, o `2476` para `$24.76 MXN`, ya que MXN tiene unidad menor).
`recurring`	`object`	Requerido. Configuración recurrente. `interval` es uno de `day`, `week`, `month` o `year`, y `interval_count` es el número de intervalos entre cobros (por ejemplo, `1` para mensual cuando `interval` es `month`).

Objeto `product_data`

Atributo	Tipo	Descripción
`name`	`string`	Requerido. Nombre del producto o servicio que se compra.
`image_url`	`string`	URL de imagen del producto. Debe ser una URL HTTPS. Relación de aspecto recomendada: 9:4.

Redirige al cliente para completar el registro

A continuación, redirige al cliente a la página de checkout alojada por Fintoc usando el redirect_url. Después de que el cliente complete el registro, Fintoc lo redirige de vuelta a tu sitio: al success_url en caso de éxito, o al cancel_url si cancela. Cliente

window.location.assign(REDIRECT_URL_FROM_YOUR_BACKEND);

Maneja los eventos posteriores a la sesión

Una vez que un Checkout Session finaliza, manejas el resultado en tu frontend y completas la suscripción en tu backend. Para tu backend, usas los eventos que Fintoc envía a través de webhooks.

Completa la suscripción en tu backend

Fintoc envía un evento checkout_session.finished cuando la sesión se completa. En un flujo de suscripción, este evento incluye información sobre la sesión y referencias a la subscription y al payment_method creados durante el registro.

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

Debes manejar los siguientes eventos posteriores a la sesión:

Evento	Descripción	Acción
`checkout_session.finished`	Enviado cuando un `Checkout Session` de suscripción alcanza un estado final.	Guarda los ids creados (`subscription`, `payment_method`, `customer`). Con `charge_automatically`, espera el `invoice.payment_succeeded` antes de darle acceso a tu cliente: en este punto la suscripción todavía está `incomplete`.
`checkout_session.expired`	Enviado cuando una sesión expira.	Ofrece al cliente otro intento de suscribirse.
`payment_intent.succeeded`	Enviado cuando un payment intent es exitoso, como un cargo en una cuenta bancaria o tarjeta.	Confirma a tu cliente que el cargo de la suscripción fue exitoso.
`payment_intent.failed`	Enviado cuando un payment intent falla.	Ofrece al cliente otro intento de pagar la suscripción.

Crear una suscripción con la API

Cuando tu cliente no necesita inscribir un método de pago en un checkout, crea la suscripción directamente con Crear una suscripción. Necesitas un customer existente y los items que la suscripción cobra en cada ciclo. El collection_method decide cómo Fintoc cobra cada invoice que genera la suscripción:

charge_automatically, el valor por defecto, cobra un payment_method en cada ciclo de facturación. El método de pago es requerido.
send_invoice deja cada invoice open para que la cobres tú. El método de pago es opcional.

Cobra automáticamente contra un método de pago

Envía el payment_method que Fintoc cobra en cada ciclo de facturación. Debe pertenecer al customer, estar active y ser pac o card. Las suscripciones no soportan bank_transfer. Servidor

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

Parámetro	Ejemplo	Descripción
`customer`	`cus_NffrFeUfNV2Hib`	Requerido. ID del `Customer` al que la suscripción le cobra.
`items`	Ver el ejemplo de arriba	Requerido. Ítems que la suscripción cobra en cada ciclo de facturación. Cada ítem usa los mismos objetos `price_data` y `product_data` que los `line_items` de un checkout session. Define cada `unit_amount` en la unidad menor de la moneda. Hasta 10 ítems, todos con el mismo `interval` e `interval_count`.
`payment_method`	`pm_NffrFeUfNV2Hib`	Método de pago que Fintoc cobra en cada ciclo de facturación. Requerido con `charge_automatically`, opcional con `send_invoice`. Debe pertenecer al `customer`, estar `active` y ser `pac` o `card`.
`collection_method`	`charge_automatically`	Cómo Fintoc cobra cada invoice que genera la suscripción. Uno de `charge_automatically` o `send_invoice`. Por defecto es `charge_automatically`.
`trial_end`	`2026-10-01T00:00:00Z`	Timestamp ISO 8601 en UTC en el que termina un período de prueba, al menos un día en el futuro. Durante la prueba la suscripción está `trialing` y Fintoc no emite invoices. Fintoc ancla el ciclo de facturación a `trial_end` y emite la primera invoice ahí. Omítelo si no hay prueba.
`metadata`	`{ "subscription_external_id": "sub_987654321" }`	Conjunto de pares clave-valor para guardar información adicional.

Fintoc responde con la suscripción creada:

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

La suscripción nace incomplete, no active. Fintoc finaliza la invoice inicial durante la creación de la suscripción y cobra el método de pago. La suscripción pasa a active cuando ese primer pago tiene éxito. Sigue el resultado con los eventos invoice.* descritos en Gestionar invoices.

Emite invoices sin cobrar

Pon el collection_method en send_invoice y no envíes payment_method. Fintoc emite una invoice por ciclo de facturación y deja cada una open, así que la suscripción nunca le cobra a nadie por su cuenta. Servidor

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

La suscripción nace active al crearla, y la invoice inicial queda open. active no significa que tu cliente haya pagado. Con send_invoice no hay cobro que esperar, así que Fintoc se salta el estado incomplete. Sigue el status de cada invoice para saber qué te debe tu cliente. Puedes asociar un método de pago después con Actualizar una suscripción, lo que te permite cobrar las invoices abiertas bajo demanda. Para las formas de saldar una invoice abierta, consulta Cobrar las invoices tú mismo en vez de cobrar automáticamente.

Prueba tu integración

Para confirmar que tu integración funciona correctamente, puedes simular suscripciones y pagos recurrentes programados sin mover dinero.

1) Crea una Checkout Session de suscripción usando credenciales de usuario de prueba

Usando tu Secret Key de modo de prueba, crea un Checkout Session con flow: subscription en tu backend. Luego completa el registro en la página de checkout alojada por Fintoc con las siguientes credenciales: Credenciales de prueba

Usuario (RUT): 11.111.111-1
Contraseña: jonsnow

2) Maneja pagos programados simulados de la suscripción

En modo de prueba, Fintoc simula los pagos programados de la suscripción para que puedas verificar el manejo del éxito y de la falla sin mover dinero. Los pagos simulados los manejas a través de los mismos eventos invoice.* y payment_intent.* descritos en Gestionar invoices. Un cargo exitoso emite invoice.payment_succeeded, invoice.paid y payment_intent.succeeded. Un cargo fallido emite invoice.payment_failed y payment_intent.failed.

El modo de prueba aún no está disponible para pagos recurrentes en México.

​Crea una Checkout Session

​Incluir datos del cliente (requerido para suscripciones)

​Incluir una lista de ítems (requerido para suscripciones)

​Objeto price_data

​Objeto product_data

​Redirige al cliente para completar el registro

​Maneja los eventos posteriores a la sesión

​Completa la suscripción en tu backend

​Crear una suscripción con la API

​Cobra automáticamente contra un método de pago

​Emite invoices sin cobrar

​Prueba tu integración

​1) Crea una Checkout Session de suscripción usando credenciales de usuario de prueba

​2) Maneja pagos programados simulados de la suscripción

Crea una Checkout Session

Incluir datos del cliente (requerido para suscripciones)

Incluir una lista de ítems (requerido para suscripciones)

Objeto `price_data`

Objeto `product_data`

Redirige al cliente para completar el registro

Maneja los eventos posteriores a la sesión

Completa la suscripción en tu backend

Crear una suscripción con la API

Cobra automáticamente contra un método de pago

Emite invoices sin cobrar

Prueba tu integración

1) Crea una Checkout Session de suscripción usando credenciales de usuario de prueba

2) Maneja pagos programados simulados de la suscripción