Hay tres pasos para aceptar pagos recurrentes usando Fintoc:

En tu backend, crea una Checkout Session con flow: subscription
Redirige a tu usuario a completar la inscripción en la página de checkout alojada por Fintoc
Maneja los eventos posteriores a la inscripción y los pagos recurrentes (webhooks)

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

Crea una sesión

El objeto Checkout Session representa tu intención de inscribir un método de pago para cobros recurrentes (PAC) y de crear una subscription con un monto y periodicidad fijos. Usando tu Secret Key, crea una Checkout Session en tu backend con flow definido como subscription.

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/987654321",
    "payment_method_types": [
      "pac"
    ],
    "customer_data": {
      "tax_id": {
        "type": "cl_rut",
        "value": "12088191"
      },
      "name": "Felipe Castro",
      "email": "name@example.com",
      "metadata": {}
    },
    "line_items": [
      {
        "price_data": {
          "currency": "CLP",
          "unit_amount": 350000,
          "product_data": {
            "name": "SoyFocus plan"
          },
          "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_KEY');

const checkoutSession = await fintoc.checkoutSessions.create({
  amount: 1000,
  currency: 'mxn',
  customer_email: 'name@example.com'
});

from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_API_KEY')

checkout_session = client.checkout_sessions.create(
  amount=1000,
  currency='clp',
  customer_email='name@example.com'
)

require 'net/http'
require 'uri'
require 'json'

checkout_session = {
  amount: 1000,
  currency: 'clp',
  customer_email: 'name@example.com'
}

uri = URI("https://api.fintoc.com/v1/checkout_sessions")

header = {
  Accept: 'application/json', Authorization: 'YOUR_TEST_SECRET_API_KEY'
}

http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = checkout_session.to_json

response = http.request(request)

Parámetro	Ejemplo	Descripción
`amount`	2476	Monto de dinero que debe pagarse. Se representa como un entero sin decimales en la unidad más pequeña posible de la moneda que estás usando. Si tu pago usa pesos chilenos, un monto de CLP 2476 se representa como 2476. Si tu pago usa pesos mexicanos, un monto de MXN 24.76 se representa como 2476. Lee aquí para aprender más.
`currency`	CLP	Moneda que se está usando para los pagos recurrentes. Actualmente Fintoc solo soporta CLP.
`flow`	`subscription`	Tipo requerido del flujo para la sesión. Los tipos disponibles son `payment`, `setup` y `subscription`
`success_url`	`https://merchant.com/success`	URL requerida a la que se redirige al usuario en caso de pago exitoso.
`cancel_url`	`https://merchant.com/987654321`	URL requerida a la que se redirige al usuario en caso de que decida cancelar el pago y volver a tu sitio web.
`customer`	`cus_alm1321knjl1233`	Id de un cliente ya creado. Uno de `customer` o `customer_data` es requerido.
`customer_data`	`(object)`	Datos para la creación inline del cliente. Uno de `customer` o `customer_data` es requerido.
`payment_method_types`	`["pac"]`	Lista opcional de métodos de pago permitidos durante la inscripción. pac representa cobros en una cuenta bancaria.
`line_items`	`(array)`	Items requeridos de la subscription.
`metadata`	`{"order": "987654321"}`	Conjunto opcional de pares clave-valor que puedes adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado.

Incluir Datos del Cliente (Requerido para subscriptions)

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

Atributo	Tipo	Descripción
`tax_id`	`object`	Objeto requerido que identifica al cliente a nivel fiscal o regulatorio. Incluye un campo `type` que indica el formato o identificador específico del país (por ejemplo, “`cl_rut`” para el RUT chileno) y un campo `value` que contiene el número de identificación tributaria real como string.
`name`	`string`	Nombre completo opcional del cliente.
`email`	`string`	Correo opcional del cliente vinculado a una Checkout Session. Se usa para notificar al usuario en caso de un reembolso.
`metadata`	`object`	Datos personalizados opcionales que pueden almacenar información adicional sobre el cliente (p. ej., IDs internos, referencias de CRM o etiquetas)

Incluir una lista de Items (Requerido para subscriptions)

Al crear una Checkout Session, también puedes incluir información sobre los items de la sesión. Esto permite que Fintoc muestre esta información en la página de checkout y muestre solo los métodos de pago disponibles para productos específicos.

Atributo	Tipo	Descripción
`quantity`	`integer`	Número requerido de unidades de este item que se están comprando.
`price_data`	`object`	Datos usados para generar un nuevo precio recurrente inline. Uno de price o price_data es requerido.

Cada line_item necesita uno de price_data o price.

Objeto price_data

Atributo	Tipo	Descripción
`product_data`	`object`	Datos usados para generar un nuevo objeto Product inline. Uno de product o product_data es requerido.
`currency`	string	Moneda usada para la subscription. Actualmente solo soportamos CLP.
`unit_amount`	`integer`	Precio requerido por unidad del item, expresado en la unidad más pequeña de la moneda (p. ej., CLP sin decimales).
`recurring`	`(object)`	Configuración requerida de recurrencia (p. ej. interval: month, interval_count: 1).

Objeto product_data

Atributo	Tipo	Descripción
`name`	`string`	Nombre requerido del producto o servicio que se está comprando.

Respuesta al crear una Checkout Session

Después de hacer la solicitud para crear la Checkout Session, Fintoc debería responder con algo como esto:

{
  "id": "cs_li5531onlFDi235",
  "flow": "subscription",
  "customer": {
      "name": "Felipe Castro",
      "email": "name@example.com",
      "metadata": {},
      "tax_id": {
        "type": "cl_rut",
        "value": "12088191"
      }
    },
  "line_items": [
    {
      "price": {
        "product": {
          "name": "Plan A",
          "description": "Pago recurrente monto fijo"
        },
        "currency": "CLP",
        "unit_amount": 350000,
        "recurring": {
          "interval": "month",
          "interval_count": 1
        }
      },
      "quantity": 1
    }
  ],
  "success_url": "https://merchant.example/success",
  "cancel_url": "https://merchant.example/cancel",
  "redirect_url": "https://pay.fintoc.com/checkout/cs_123"
}

En la respuesta, deberías recibir el atributo url. En el siguiente paso, usarás este atributo para redirigir al usuario a completar la subscription.

Redirige al usuario a completar el pago

A continuación, redirigirás a los usuarios a la página de Checkout de Fintoc. Después de completar el pago, serán redirigidos automáticamente a tu sitio. Según el resultado, el usuario será redirigido a la URL de éxito o cancelación.

Maneja los eventos posteriores a la sesión

Una vez que una Checkout Session finaliza, manejas el resultado en tu frontend y completas la subscription en tu backend. Para tu backend, usarás los eventos enviados por webhooks.

Completa la subscription en tu backend

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

{
  "id": "evt_a4xK32BanKWYn",
  "object": "event",
  "type": "checkout_session.finished",
  "data": {
    "id": "cs_li5531onlFDi235",
    "flow": "subscription",
    "customer": {
      "name": "Felipe Castro",
      "email": "name@example.com",
      "metadata": {},
      "tax_id": {
        "type": "cl_rut",
        "value": "12088191"
      }
    },
    "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 una Checkout Session de subscription alcanza un estado final	Activa la subscription en tu lado según el estado final, y almacena los ids creados (`subscription`, `payment_method`, `customer`).
`checkout_session.expired`	Enviado cuando una sesión expira	Ofrece al cliente otro intento de suscribirse.
`payment_intent.succeeded`	Enviado cuando un payment intent se completa con éxito, como un cobro en una cuenta bancaria o tarjeta.	Confirma a tu cliente que el cobro de la subscription se realizó con éxito
`payment_intent.failed`	Enviado cuando un payment intent falla	Ofrece al cliente otro intento de pago de la subscription.

Prueba tu integración (Próximamente)

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

1) Crea una Checkout Session de subscription usando credenciales de usuarios de prueba

Usando tu Secret Key de API en modo prueba, crea una Checkout Session de flow: subscription en tu backend y completa el flujo de inscripción de la subscription en la página alojada por Fintoc usando las siguientes credenciales: Credenciales de prueba

Usuario (RUT): 41614850-3
Contraseña: jonsnow

2) Maneja pagos programados simulados de la subscription

En modo prueba, una vez que se crea la subscription, Fintoc activará inmediatamente payment intents exitosos y fallidos, permitiéndote probar el manejo de todos los eventos posteriores a la sesión.

Inicio

Recursos

Pagos

Transferencias

Domiciliación bancaria

Movimientos

Aceptar pagos recurrentes

Crea una sesión

Incluir Datos del Cliente (Requerido para subscriptions)

Incluir una lista de Items (Requerido para subscriptions)

Objeto price_data

Objeto product_data

Respuesta al crear una Checkout Session

Redirige al usuario a completar el pago

Maneja los eventos posteriores a la sesión

Completa la subscription en tu backend

Prueba tu integración (Próximamente)

1) Crea una Checkout Session de subscription usando credenciales de usuarios de prueba

2) Maneja pagos programados simulados de la subscription

​Crea una sesión

​Incluir Datos del Cliente (Requerido para subscriptions)

​Incluir una lista de Items (Requerido para subscriptions)

​Objeto price_data

​Objeto product_data

​Respuesta al crear una Checkout Session

​Redirige al usuario a completar el pago

​Maneja los eventos posteriores a la sesión

​Completa la subscription en tu backend

​Prueba tu integración (Próximamente)

​1) Crea una Checkout Session de subscription usando credenciales de usuarios de prueba

​2) Maneja pagos programados simulados de la subscription

Crea una sesión

Incluir Datos del Cliente (Requerido para subscriptions)

Incluir una lista de Items (Requerido para subscriptions)

Objeto price_data

Objeto product_data

Respuesta al crear una Checkout Session

Redirige al usuario a completar el pago

Maneja los eventos posteriores a la sesión

Completa la subscription en tu backend

Prueba tu integración (Próximamente)

1) Crea una Checkout Session de subscription usando credenciales de usuarios de prueba

2) Maneja pagos programados simulados de la subscription