Hay tres pasos para aceptar pagos usando Fintoc:

En tu backend, crea un Checkout Session usando tu Secret Key
Redirige a tu usuario para 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 del backend

Python
Node

Si usas Python, puedes instalar nuestro SDK de Python para interactuar con nuestra API de manera más sencilla. El SDK maneja automáticamente la paginación, te permite verificar fácilmente los webhooks de Fintoc y ofrece muchas otras funciones útiles.

pip install fintoc

Si usas Node, puedes instalar nuestro SDK de Node para interactuar con nuestra API de manera más sencilla. El SDK maneja automáticamente la paginación, te permite verificar fácilmente los webhooks de Fintoc y ofrece muchas otras funciones útiles.

npm install fintoc

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 un Checkout Session desde tu backend con los parámetros requeridos: amount, currency, success_url y cancel_url, como el ejemplo a continuación:

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_data": {
      "tax_id": {
        "type": "cl_rut",
        "value": "12088191"
      },
      "name": "Felipe Castro",
      "email": "name@example.com",
      "metadata": {}
    },
    "billing_items": [
      {
        "price_data": {
          "product_data": {
            "name": "T‑Shirt A",
            "description": "Limited edition"
          },
          "unit_amount": 350000
        },
        "quantity": 1
      }
    ],
    "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 para redirigir al usuario en caso de pago exitoso.
`cancel_url`	`https://merchant.com/987654321`	URL requerida para redirigir al usuario en caso de que decida cancelar el pago y volver a tu sitio.
`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 submerchantTambié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 un 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 pago.

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 fiscal real como string.
`name`	`string`	Nombre completo opcional del cliente.
`email`	`string`	Email 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 (por ejemplo, IDs internos, referencias de CRM o etiquetas)

Preseleccionar un método de pago (Opcional)

Puedes crear un 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 hayas habilitado en Fintoc. Alternativamente, puedes definir explícitamente el método o métodos de pago para la sesión. Por ejemplo, en la solicitud a continuación, se establece 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 se limitará 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",
    "flow": "payment",
    "success_url": "https://merchant.com/success",
    "cancel_url": "https://merchant.com/987654321",
    "payment_method_types": ["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": {}
    },
    "billing_items": [
      {
        "price_data": {
          "product_data": {
            "name": "T‑Shirt A",
            "description": "Limited edition"
          },
          "unit_amount": 350000,
          "recurrence": null
        },
        "quantity": 1
      }
    ]
  }'

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_method_types`	`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_initiation` (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 establece el parámetro `payment_method`. Derecha: Flujo `transferencia bancaria` preseleccionado para Banco Estado, mostrando directamente el formulario de pago específico de la institución.

Uso de tu propia página de CheckoutCuando tienes tu propia página de checkout, debes establecer el payment_method para redirigir a los usuarios al Checkout de Fintoc después de que ya hayan seleccionado su método de pago preferido.Esto omite 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 gestione la experiencia de checkout completa.

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

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. El Widget de Fintoc es el componente del lado del cliente con el que tus clientes interactuarán para hacer pagos usando Fintoc. Maneja la validación de credenciales, autenticación multifactor y manejo de errores para todas las instituciones financieras soportadas. Tienes dos opciones para abrir el widget: Si quieres mostrar el Widget de Fintoc directamente en tu página de checkout (sin redirigir al usuario), usa el session_token devuelto en la respuesta de la API al crear una Checkout Session. Usa tu Public Key y el Session Token para configurar el widget.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta name="viewport" content="width=device-width,initial-scale=1.0, maximum-scale=1.0">
    <title>Fintoc Demo</title>
    <script src="https://js.fintoc.com/v1/"></script>
  </head>
  <body>
    <script>
      window.onload = () => {
        const widget = Fintoc.create({
          sessionToken: 'cs_XXXXXXXX_sec_YYYYYYYY',
          product: 'payments',
          publicKey: 'YOUR_PUBLIC_KEY',
          onSuccess: () => {},
        });
        widget.open();
      };
    </script>
  </body>
</html>

Si estás recibiendo pagos en México, establece el parámetro country en mx. Para más opciones de configuración y uso avanzado, consulta la guía del Widget.

Usa nuestro Widget Webview si estás creando una app móvilSi estás integrando Fintoc en una aplicación iOS o Android, puedes usar nuestra integración Webview.

Alternativamente, puedes redirigir a los usuarios a una página de pago alojada por Fintoc. Después de completar el pago, serán redirigidos automáticamente de vuelta a tu sitio. Para usar este método, incluye tanto los parámetros success_url como cancel_url al crear la Checkout Session. La respuesta de la API incluirá un redirect_url que puedes usar para enviar al usuario a la página de pago. Según el resultado del pago, el usuario será redirigido al URL de éxito o cancelación. Para más detalles, consulta la guía de integración con Redirect Page.

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 frontend usarás el callback del widget, y para tu backend usarás los eventos enviados por webhooks.

Usa eventos de webhooks para completar pagosTu cliente podría cerrar la ventana del navegador o salir de la app antes de que se ejecute el callback onSuccess del widget. Por esta razón, siempre debes usar el evento checkout_session.finished para manejar acciones posteriores al pago 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.

Maneja el resultado del pago en tu frontend

Una vez que un pago asociado a la Checkout Session finaliza exitosamente, el widget ejecuta el callback onSuccess. Necesitas pasar esta función al widget al momento de crearlo. Con este callback, puedes decidir qué hacer con el frontend de tu usuario una vez que el pago esté completo, por ejemplo:

Redirigir al usuario a una vista post-venta o post-pago
Mostrar al usuario una pantalla de éxito.

No uses este callback como confirmación de pagoNo deberías confiar en el callback onSuccess como confirmación de un pago exitoso, ya que el frontend es un entorno inseguro y un tercero malicioso podría ejecutar una función JavaScript que simule que la transferencia se ejecutó exitosamente.Para un mecanismo de validación más completo, recomendamos encarecidamente integrar webhooks y suscribirte al evento checkout_session.finished. Al implementar webhooks, puedes asegurar actualizaciones oportunas y precisas sobre los estados de pago, mejorando la seguridad y confiabilidad generales de tu proceso de confirmación de pago.

Maneja errores

No solo necesitas manejar pagos exitosos porque los pagos también pueden fallar. Por ejemplo, que tu cliente no tenga fondos en su cuenta bancaria para completar el pago. Cuando un pago falla o es rechazado por tu cliente, el widget ejecuta el callback onExit. Con este callback, puedes manejar errores en tu frontend. Por ejemplo, puedes invitar a tu cliente a usar otro método de pago.

Completa el pago en tu backend

Fintoc envía un evento checkout_session.finished cuando el pago se completa. 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 el pago relacionado y se ve así:

{
  "id": "evt_a4xK32BanKWYn",
  "object": "event",
  "type": "checkout_session.finished",
  "data": {
    id: "cs_li5531onlFDi235",
    created_at: "2025-06-15T15:22:11.474Z",
    object: "session",
    currency: "clp",
    amount: 1200,
    customer_email: "customer@example.com",
    expires_at: "2025-06-16T15:22:11.474Z",
    product: "payments",
    mode: "live",
    status: "finished",
    session_token: "cs_li5531onlFDi235_sec_a4xK32BanKWYn",
    type: "embedded",
    country: 'cl',
    metadata: {
    	order_id: "#12513"
  	},
    payment_methods: [
      'payment_intent'
    ],
    payment_method_options: {
      payment_intent: {
        holder_type: 'individual',
        recipient_account: {
          "holder_id": "183917137",
          "number": "123456",
          "type": "checking_account",
          "institution_id": "cl_banco_de_chile"
        },
        sender_account: {
          holder_id: {
            editable: 'false',
            value: 123456789
          },
          institution_id: {
            editable: 'false',
            value: 'cl_banco_estado'
          }
        }
      }
    },
    payment_intent: {
      "id": "pi_BO381oEATXonG6bj",
      "object": "payment_intent",
      "amount": 1200,
      "currency": "CLP",
      "status": "succeeded",
      "reference_id": "90123712",
      "transaction_date": "2025-06-15T15:22:11.474Z",
      "metadata": {
        order_id: "#12513"
      },
      "error_reason": null,
      "recipient_account": {
        "holder_id": "183917137",
        "number": "123456",
        "type": "checking_account",
        "institution_id": "cl_banco_de_chile"
      },
      "sender_account": {
        "holder_id": "192769065",
        "number": "123456",
        "type": "checking_account",
        "institution_id": "cl_banco_estado"
      },
      "created_at": "2021-10-15T15:23:11.474Z"
    }
  }

Debes manejar los siguientes eventos al usar nuestro producto de Iniciación de Pagos:

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 final 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 a una checkout session es exitoso. Es útil para confirmar pagos que previamente estaban en estado pendiente	Confirma la orden del cliente
`payment_intent.failed`	Enviado cuando el pago relacionado a una checkout session falla. Se usa para determinar el estado final de pagos que previamente estaban en estado pendiente	Ofrece al cliente otro intento de pago.

Redirige al usuario para 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 de vuelta a tu sitio. Según el resultado del pago, el usuario será redirigido al 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 id y status del payment_intent:

{
  "id": "evt_a4xK32BanKWYn",
  "object": "event",
  "type": "checkout_session.finished",
  "data": {
    "id": "cus_NV2HibNV2HibNV2Hib",
    "amount": 350000,
    "business_profile": {},
    "cancel_url": "https://merchant.example/cancel",
		"success_url": "https://merchant.example/success",
    "created_at": "2021-10-15T15:22:11.474Z",
    "currency": "CLP",
    "customer": null,
    "customer_data": {
      "email": "user@example.com",
      "name": "Jane Doe",
      "tax_id": {
        "type": "cl_rut",
        "value": "285509548"
      },
      "metadata": {
        "crm_id": "A-771"
      }
    },
    "expires_at": "2024-11-12T14:41:25Z",
    "metadata": {
      "order_id": "#12513"
    },
    "mode": "test",
    "status": "finished",
    "redirect_url": "https://pay.fintoc.com/checkout/cs_123"
  }
}

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 a una checkout session es exitoso.	Confirma la orden del cliente
`payment_intent.failed`	Enviado cuando el pago relacionado a una checkout session falla.	Ofrece al cliente otro intento de pago.

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 aprobación de más de un representante.En estos casos, 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 del estado final del pago tan pronto como se confirme.

Inicio

Recursos

Pagos

Transferencias

Movimientos

Aceptar un pago

Opcional: instala nuestro SDK del backend

Crea una sesión

Incluir datos del cliente (Opcional)

Preseleccionar un método de pago (Opcional)

Respuesta al crear una Checkout Session

Elige cómo abrir el widget de Fintoc

Opción 1: abrir el widget en tu frontend

Opción 2: abrir el widget vía Redirect Page

Maneja los eventos posteriores al pago

Maneja el resultado del pago en tu frontend

Maneja errores

Completa el pago en tu backend

Redirige al usuario para completar el pago

Maneja los eventos posteriores al pago

Completa el pago en tu backend

​Opcional: instala nuestro SDK del backend

​Crea una sesión

​Incluir datos del cliente (Opcional)

​Preseleccionar un método de pago (Opcional)

​Respuesta al crear una Checkout Session

​Elige cómo abrir el widget de Fintoc

​Opción 1: abrir el widget en tu frontend

​Opción 2: abrir el widget vía Redirect Page

​Maneja los eventos posteriores al pago

​Maneja el resultado del pago en tu frontend

​Maneja errores

​Completa el pago en tu backend

​Redirige al usuario para completar el pago

​Maneja los eventos posteriores al pago

​Completa el pago en tu backend

Opcional: instala nuestro SDK del backend

Crea una sesión

Incluir datos del cliente (Opcional)

Preseleccionar un método de pago (Opcional)

Respuesta al crear una Checkout Session

Elige cómo abrir el widget de Fintoc

Opción 1: abrir el widget en tu frontend

Opción 2: abrir el widget vía Redirect Page

Maneja los eventos posteriores al pago

Maneja el resultado del pago en tu frontend

Maneja errores

Completa el pago en tu backend

Redirige al usuario para completar el pago

Maneja los eventos posteriores al pago

Completa el pago en tu backend