Skip to main content
Construye un flujo de pago que cobre pagos únicos en CLP o MXN a través de una página de checkout alojada por Fintoc. Para aceptar pagos con Fintoc, completas tres pasos:
  1. En tu backend, crea un Checkout Session usando tu secret key
  2. Redirige a tu cliente para completar el pago en la página de checkout alojada por Fintoc
  3. 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 el SDK del backend

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.

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 en el ejemplo a continuación: Servidor
Node
Fintoc responde con el objeto Checkout Session creado, incluyendo el redirect_url que usas para enviar al cliente al pago:

Business profile (opcional)

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 enviando un objeto customer_data (o customer con el id de un Customer existente). Esta información permite a Fintoc mostrar solo los métodos de pago disponibles para ese cliente específico. Por ejemplo, Fintoc oculta un banco cuando el monto excede su límite de transacción.
Flujos de pago específicos de banco para cuentas empresariales y montos altosEn Chile, algunos pagos bank_transfer requieren bancos con flujos de pago especiales: Banco Estado, Banco de Chile y Banco Santander. Fintoc limita la sesión a estos bancos cuando el pago excede los límites de transacción o el customer tiene un tax_id.value de empresa en lugar de persona natural. Puedes probar este flujo con la guía de prueba de métodos de pago alternativos.

Incluir una lista de ítems (opcional)

Al crear un Checkout Session, también puedes enviar los line_items, incluyendo información sobre los ítems de la sesión. Esto permite a Fintoc mostrar esta información en la página de checkout y mostrar solo los métodos de pago disponibles para productos específicos. Cada ítem debe tener:

El objeto price_data

El objeto product_data

El objeto price_data contiene un objeto product_data con información del producto: El ejemplo a continuación crea un Checkout Session con un solo line item: Servidor
Node
Fintoc responde con el objeto Checkout Session creado. Cada ítem de line_items incluye un price con los datos del product que enviaste:

Preseleccionar un método de pago (opcional)

Puedes crear un Checkout Session sin especificar métodos de pago. En este caso, los clientes 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 tipo o tipos de método de pago para la sesión. Por ejemplo, la solicitud a continuación establece el método bank_transfer y usa payment_method_options para preseleccionar la institución cl_banco_estado para el cliente. En este escenario, el flujo de pago presentado al cliente se limita a este método y banco específicos. Servidor
Node
Con card, el checkout también muestra Apple Pay en los dispositivos compatibles, tanto en modo live como en modo test. Fintoc responde con el objeto Checkout Session creado, haciendo eco del método e institución preseleccionados:

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

Uso de tu propia página de CheckoutCuando tienes tu propia página de checkout, debes establecer payment_method_types para redirigir a los clientes al checkout alojado por 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 clientes directamente al flujo de pago específico, en lugar de dejar que Fintoc gestione la experiencia de checkout completa.

Ofrece efectivo en sesiones en MXN

En sesiones en MXN, puedes ofrecer cash por sí solo o combinarlo con card y bank_transfer. Tu cliente elige cómo pagar en la página de checkout alojada por Fintoc. No puedes combinar cash con installments. Por ejemplo, la siguiente solicitud permite que tu cliente pague con tarjeta o en efectivo: Servidor
Fintoc responde con el objeto de la sesión, incluyendo cash en payment_method_types:
Si un pago con tarjeta o transferencia bancaria falla y cash está disponible en la sesión, tu cliente puede reintentar el pago en efectivo. Revisa Acepta pagos en efectivo en México para ver cómo funcionan los pagos en efectivo.

Aceptar solo algunas tarjetas (opcional)

Para aceptar solo tarjetas de algunos bancos, envía sus números de identificación bancaria (BIN) en payment_method_options.card.bins. Un BIN corresponde a los primeros 6 u 8 dígitos del número de una tarjeta e identifica al banco que la emitió. Por ejemplo, usa bins para ofrecer un descuento que un banco financia para sus propias tarjetas. La siguiente solicitud crea una sesión que acepta solo tarjetas que comienzan con 411111 o 455555: Servidor
Node
Fintoc responde con el objeto de la sesión, incluyendo bins en payment_method_options:
La restricción de bins sigue estas reglas:
  • bins es un arreglo no vacío de strings, cada uno con 6 u 8 dígitos. Si envías un arreglo vacío, un BIN con una longitud distinta o un BIN con caracteres que no son dígitos, Fintoc responde 400 Bad Request con el error invalid_payment_method_options.
  • bins aplica solo a sesiones del flujo payment.
  • bins restringe solo las tarjetas. Si la sesión también ofrece otro método de pago, como bank_transfer, tu cliente puede pagar con ese método.
  • Fintoc revisa la tarjeta cuando tu cliente la ingresa, no cuando creas la sesión. Si la tarjeta no comienza con uno de los BIN, el checkout la rechaza antes de cobrarla y le pide a tu cliente otra tarjeta.
  • Una sesión con bins no ofrece Apple Pay, Google Pay, tarjetas guardadas ni tarjetas Hites (hites en payment_method_options.card.types). En una sesión de Express Checkout, Fintoc rechaza el pago con Apple Pay, así que no envíes bins ahí.
Para probar la restricción en modo test, crea la sesión anterior y paga con la tarjeta de prueba de Chile 4111111111111111. El checkout rechaza cualquier tarjeta de prueba que comience con otros dígitos, como 4456524869770255.

Ofrece un descuento para algunas tarjetas

No puedes cambiar el amount de una Checkout Session después de crearla. Para ofrecer un descuento con las tarjetas de un banco, muéstrale a tu cliente dos formas de pagar. Indícale qué tarjetas tienen el descuento, porque el checkout no muestra tu promoción. Cuando tu cliente elija una forma de pagar, crea la sesión correspondiente:
  • Pago con descuento: una sesión con el amount con descuento, payment_method_types igual a ["card"] y los BIN que te entrega el banco en payment_method_options.card.bins.
  • Pago normal: una sesión con el amount completo y sin bins.
Define solo card en la sesión con descuento. Si no, tu cliente puede pagar el amount con descuento con otro método de pago. Usa como cancel_url de la sesión con descuento la página donde tu cliente elige cómo pagar. Así, un cliente sin tarjeta de ese banco puede volver y pagar el amount completo. Cuando tu cliente vuelva por cancel_url, expira la sesión con descuento para que no pueda pagarla después.

Respuesta al crear una Checkout Session

Después de hacer la solicitud para crear la Checkout Session, Fintoc responde con el objeto de la sesión:
La respuesta incluye el atributo redirect_url. En el siguiente paso, usarás este atributo para redirigir al cliente a completar el pago.

Redirige al cliente para completar el pago

A continuación, redirige a los clientes a la página de checkout alojada por Fintoc. Después de que completen el pago, Fintoc los redirige automáticamente de vuelta a tu sitio: al success_url después de un pago exitoso, o al cancel_url si cancelan. El checkout alojado por Fintoc no admite integraciones en iframe. No cargues el redirect_url en un iframe; redirige la página completa del navegador. Cliente
Si prefieres que tus clientes no salgan de tu sitio, renderiza la misma Checkout Session con el Widget embebido. Pasa el session_token de la sesión como la opción sessionToken del Widget. Revisa Integra el Widget en la web o Integración con WebView para apps móviles. No necesitas crear un Payment Intent para una Checkout Session. Fintoc crea el Payment Intent automáticamente cuando tu cliente inicia un intento de pago. El campo payment_resource de la sesión expone el Payment Intent y es null hasta ese momento.

Maneja los eventos posteriores al pago

Una vez que un Checkout Session finaliza, manejas el resultado del pago en tu frontend y completas el pago en tu backend. En tu backend, usa los eventos que Fintoc envía a través de 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. Sigue 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:
Fintoc emite estos eventos a lo largo del ciclo de vida del pago, incluyendo las rutas de falla y pendiente. Maneja cada uno:
Manejo de pagos asíncronos después de que termina el Checkout SessionEn algunos casos, el 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.Fintoc no envía un evento separado para este estado. Recibes checkout_session.finished con data.payment_resource.payment_intent.status en requires_action, así que informa al cliente que el pago está pendiente de aprobación. Cuando el pago alcanza su estado final, Fintoc envía payment_intent.succeeded o payment_intent.failed. Notifica al cliente el estado final cuando lo recibas.

Notificaciones por correo al cliente

Fintoc envía a tu cliente un comprobante de pago por correo después de un pago exitoso. Fintoc envía el comprobante cuando se cumple alguna de estas condiciones:
  • Envías customer_email al crear la Checkout Session.
  • Tu cliente ingresa un correo en la pantalla de pago exitoso y solicita el comprobante.
Si envías customer_email, Fintoc también lo usa para notificar a tu cliente sobre reembolsos. Para que Fintoc deje de enviar comprobantes de pago automáticamente, no incluyas customer_email al crear la Checkout Session. Tu cliente aún puede solicitar el comprobante desde la pantalla de pago exitoso. Sin customer_email, Fintoc tampoco envía notificaciones de reembolso. Para desactivar todos los comprobantes de pago de tu cuenta, incluidos los que tus clientes solicitan desde la pantalla de pago exitoso, contacta al soporte de Fintoc en soporte@fintoc.com.

Prueba tu integración

Usando tu secret key de modo de prueba, puedes crear pagos que simulan resultados exitosos y fallidos sin mover dinero. Esto te permite validar tu flujo de pago completo de extremo a extremo:
  • Tus solicitudes a la API del backend (creación de sesiones y manejo de respuestas)
  • El flujo de redirección desde tu frontend al redirect_url y de vuelta al success_url o cancel_url después del pago
  • Los webhooks para eventos posteriores al pago
Una sesión de prueba exitosa alcanza el status finished y dispara los webhooks checkout_session.finished y payment_intent.succeeded; una fallida dispara payment_intent.failed. Para disparar escenarios específicos, usa las credenciales de prueba y valores especiales de prueba descritos en nuestra guía de pruebas.