Hay tres pasos para aceptar pagos usando Fintoc:

En tu backend, crea una Checkout Session usando tu Secret Key
Redirige a tu usuario a completar el pago en la página de checkout alojada por Fintoc
Maneja los eventos posteriores al pago

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

Opcional: instala nuestro SDK de backend

Crea una sesión

El objeto Checkout Session representa tu intención de cobrar un pago a un cliente y rastrea los cambios de estado a lo largo del proceso de pago. Usando tu Secret Key, crea una Checkout Session desde tu backend con los parámetros requeridos: amount, currency, success_url y cancel_url como en el ejemplo siguiente:

curl --request POST "https://api.fintoc.com/v2/checkout_sessions" \
  --header "Authorization: YOUR_TEST_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "amount": 350000,
    "currency": "CLP",
    "success_url": "https://merchant.com/success",
    "cancel_url": "https://merchant.com/987654321",
    "customer": {
      "tax_id": {
        "type": "cl_rut",
        "value": "12088191"
      },
      "name": "Felipe Castro",
      "email": "name@example.com",
      "metadata": {}
    },
    "metadata": {
      "order": "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 requerido 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 requerida que se está usando para el pago. Actualmente soportamos CLP y MXN.
`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.
`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.

Envía el objeto Business Profile si estás procesando pagos para un subcomercioTambién puedes agregar el objeto business_profile al crear una sesión para personalizar el nombre mostrado como “Destinatario” en el flujo de pago.Lee aquí para aprender más.

Incluir Datos del Cliente (Opcional)

Al crear una Checkout Session, puedes incluir información del cliente. Esto permite que Fintoc muestre solo los métodos de pago disponibles para ese cliente específico, como verificar si el monto excede el límite de transacción para un banco seleccionado en el método de iniciación de pagos.

Atributo	Tipo	Descripción
`tax_id`	`object`	Objeto 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. Uno de `tax_id` o `email` es requerido
`name`	`string`	Nombre completo opcional del cliente.
`email`	`string`	Correo del cliente vinculado a una Checkout Session. Se usa para notificar al usuario en caso de un reembolso. Uno de tax_id o email es requerido
`metadata`	`object`	Datos personalizados opcionales que pueden almacenar información adicional sobre el cliente (p. ej., IDs internos, referencias de CRM o etiquetas)

Flujos de pago específicos por banco para cuentas empresariales y montos altosEn pagos bank_transfer en Chile, si el pago está por encima de los límites de transacción o envías un customer con un tax_id.value de una empresa en lugar de una persona natural, Fintoc permitirá solo los bancos que tienen flujos de pago especiales para este tipo de transacciones (Banco Estado, Banco de Chile y Banco Santander). Puedes probarlo usando estas credenciales.

Preseleccionar un Método de Pago (Opcional)

Puedes crear una Checkout Session sin especificar métodos de pago. En este caso, los usuarios pueden seleccionar entre todas las opciones disponibles en la página de checkout alojada por Fintoc, según los parámetros de la sesión (amount, customer, currency) y los métodos de pago que has habilitado en Fintoc. Alternativamente, puedes definir explícitamente el método o los métodos de pago para la sesión. Por ejemplo, en la solicitud a continuación, se define el método payment_initiation, combinado con payment_method_options, donde la institución cl_banco_estado está preseleccionada para el usuario. En este escenario, el flujo de pago presentado al usuario estará limitado a este método y banco específicos.

curl --request POST "https://api.fintoc.com/v2/checkout_sessions" \
  --header "Authorization: YOUR_TEST_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "amount": 350000,
    "currency": "CLP",
    "success_url": "https://merchant.com/success",
    "cancel_url": "https://merchant.com/987654321",
    "payment_methods": ["payment_initiation"],
    "payment_method_options": {
      "payment_initiation": {
        "institution_id": "cl_banco_estado"
      }
    },
    "customer_data": {
      "tax_id": {
        "type": "cl_rut",
        "value": "12088191"
      },
      "name": "Felipe Castro",
      "email": "name@example.com",
      "metadata": {}
    }
  }'

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)

Atributo	Tipo	Descripción
`payment_methods`	`array of strings`	Definición opcional del método o métodos de pago disponibles para la sesión. Los métodos disponibles actualmente son `payment_intent` (transferencias bancarias) y `card`
`payment_method_options`	`hash`	Arreglo opcional de configuraciones para cada método de pago disponible

Izquierda: Vista predeterminada que muestra todos los métodos disponibles (transferencia bancaria y tarjetas) cuando no se define el parámetro `payment_method`. Centro: Flujo preseleccionado de `bank transfer` para Banco Estado, mostrando directamente el formulario de pago específico de la institución. Derecha: Flujo `card` preseleccionado.

Usar tu propia Página de CheckoutCuando tienes tu propia página de checkout, debes definir el payment_method para redirigir a los usuarios al checkout alojado por Fintoc después de que ya hayan seleccionado su método de pago preferido.Esto se salta la pantalla de selección de método de pago de Fintoc y dirige a los usuarios directamente al flujo de pago específico, en lugar de dejar que Fintoc maneje toda la experiencia de checkout.

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",
  "object": "checkout_session",
  "mode": "test",
  "status": "created",
  "amount": 350000,
  "currency": "CLP",
  "created_at": "2024-06-04T15:32:46.721Z",
  "updated_at": "2024-06-04T15:32:46.721Z",
  "success_url": "https://merchant.com/success",
  "cancel_url": "https://merchant.com/987654321",
  "redirect_url": "https://checkout.fintoc.com/checkout_session_01HXY3Z7X5YQ54V8G2E1KJQAVF",
  "metadata": {},
  "customer": {
    "name": "Felipe Castro",
    "email": "name@example.com",
    "metadata": {},
    "tax_id": {
      "type": "cl_rut",
      "value": "12088191"
    }
  }
}

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

Redirige al usuario a completar el pago

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

Maneja los eventos posteriores al pago

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

Completa el pago en tu backend

Fintoc envía un evento checkout_session.finished y un payment_intent.succeeded cuando la sesión se completa y el pago es exitoso. Usa la guía de webhooks para recibir estos eventos y ejecutar acciones, como enviar un correo de confirmación de orden a tu cliente, registrar la venta en una base de datos o iniciar un flujo de envío. El evento checkout_session.finished incluye información sobre la sesión y el payment_intent:

{
  "id": "evt_a4xK32BanKWYn",
  "object": "event",
  "type": "checkout_session.finished",
  "data": {
    "id": "cs_li5531onlFDi235",
    "mode": "test",
    "amount": 350000,
    "object": "checkout_session",
    "status": "finished",
    "currency": "CLP",
    "metadata": {},
    "cancel_url": "https://merchant.com/987654321",
    "created_at": "2026-01-13T18:48:25Z",
    "expires_at": "2026-01-14T18:48:25Z",
    "success_url": "https://merchant.com/success",
    "redirect_url": "https://checkout.fintoc.com/checkout_session_01HXY3Z7X5YQ54V8G2E1KJQAVF",
    "session_token": null,
    "customer_email": null,
    "customer": {
      "name": "Felipe Castro",
      "email": "name@example.com",
      "metadata": {},
      "tax_id": {
        "type": "cl_rut",
        "value": "12088191"
      }
    },
    "payment_methods": [
      "payment_intent"
    ],
    "business_profile": {},
    "payment_resource": {
      "payment_intent": {
        "id": "pi_38DNJo3rbvGUzKFvCGZ6dxR1Kxx",
        "mode": "test",
        "amount": 350000,
        "object": "payment_intent",
        "status": "succeeded",
        "currency": "CLP",
        "metadata": {},
        "created_at": "2026-01-13T18:48:31Z",
        "expires_at": "2026-01-14T18:48:25Z",
        "error_reason": null,
        "payment_type": "bank_transfer",
        "reference_id": null,
        "widget_token": null,
        "customer_email": null,
        "sender_account": {
          "type": "checking_account",
          "number": "813990168",
          "holder_id": "415792638",
          "institution_id": "cl_banco_falabella"
        },
        "business_profile": {},
        "transaction_date": null,
        "recipient_account": null,
        "payment_type_options": {}
      }
    },
    "payment_method_options": {}
  }
}

Debes manejar los siguientes eventos posteriores al pago:

Evento	Descripción	Acción
`checkout_session.finished`	Enviado cuando un pago asociado a una Checkout Session alcanza un estado final	Completa la orden según el estado del pago
`checkout_session.expired`	Enviado cuando una sesión expira	Ofrece al cliente otro intento de pago.
`payment_intent.succeeded`	Enviado cuando el pago relacionado con una checkout session se completa con éxito.	Confirma la orden del cliente
`payment_intent.failed`	Enviado cuando el pago relacionado con una checkout session falla.	Ofrece al cliente otro intento de pago.
`payment_intent.requires_action`	Enviado cuando el pago relacionado con una checkout session necesita una acción del usuario. Se recibirá cuando una `bank transfer` desde una cuenta empresarial requiere la aprobación de más de un representante.	Informa al usuario la acción necesaria para aprobar el pago, según el `next_action` informado por el webhook de Fintoc.

Manejo de pagos asíncronos después de que termina la Checkout SessionEn algunos casos, la Checkout Session puede finalizar con un pago que aún no tiene un estado final, como requires_action. Esto puede ocurrir, por ejemplo, cuando una transferencia bancaria desde una cuenta empresarial requiere la aprobación de más de un representante.En estos casos, al recibir el payment_intent.requires_action debes informar al usuario que el pago está pendiente de aprobación. Una vez que recibas el evento payment_intent.succeeded o payment_intent.failed, debes notificar al usuario el estado final del pago tan pronto como se confirme.

Prueba tu integración

Usando tu Secret Key de API en modo prueba, puedes crear pagos que simulan resultados exitosos y fallidos sin mover dinero real. Esto te permite validar tu flujo de pago completo de extremo a extremo:

Tus solicitudes a la API del backend (crear sesiones y manejar respuestas)
El flujo de redirección desde tu frontend a la redirect_url y de vuelta a la success_url o cancel_url después del pago
Webhooks para eventos posteriores al pago

Para aprender cómo activar escenarios específicos, usa las credenciales de prueba y valores especiales de prueba descritos en nuestra guía de pruebas.

Inicio

Recursos

Pagos

Transferencias

Domiciliación bancaria

Movimientos

Aceptar un pago

Opcional: instala nuestro SDK de backend

Crea una sesión

Incluir Datos del Cliente (Opcional)

Preseleccionar un Método de Pago (Opcional)

Respuesta al crear una Checkout Session

Redirige al usuario a completar el pago

Maneja los eventos posteriores al pago

Completa el pago en tu backend

Prueba tu integración

​Opcional: instala nuestro SDK de backend

​Crea una sesión

​Incluir Datos del Cliente (Opcional)

​Preseleccionar un Método de Pago (Opcional)

​Respuesta al crear una Checkout Session

​Redirige al usuario a completar el pago

​Maneja los eventos posteriores al pago

​Completa el pago en tu backend

​Prueba tu integración

Opcional: instala nuestro SDK de backend

Crea una sesión

Incluir Datos del Cliente (Opcional)

Preseleccionar un Método de Pago (Opcional)

Respuesta al crear una Checkout Session

Redirige al usuario a completar el pago

Maneja los eventos posteriores al pago

Completa el pago en tu backend

Prueba tu integración