- En tu backend, crea una Checkout Session con
flow: setup. - Redirige a tu cliente para completar el registro en la página de checkout alojada por Fintoc.
- Maneja los eventos posteriores a la sesión para guardar el
payment_methodycustomer. - Cobra el método de pago guardado bajo demanda, creando una invoice o un Payment Intent.

Crea una Checkout Session
El Checkout Session con el flujosetup representa tu intención de guardar un método de pago para cobros futuros, sin crear una suscripción recurrente.
Usando tu Secret Key, crea una Checkout Session en tu backend con flow en setup:
Servidor
Node
redirect_url:
Diferencia con el flujo de suscripciónCuando creas una Checkout Session con
flow: setup, Fintoc registra el método de pago del cliente y crea un PaymentMethod, pero no crea una subscription ni agenda cobros recurrentes. Tú controlas cuándo y cuánto cobrar creando payment intents futuros.Incluir datos del cliente
Al crear una Checkout Session para setup, debes incluir información del cliente.Redirige al cliente para completar el registro
A continuación, redirige al cliente alredirect_url de la respuesta. El cliente ve la página de checkout alojada por Fintoc, donde completa el registro.
Después de que el cliente complete el registro, Fintoc lo redirige automáticamente a tu success_url o cancel_url, según el resultado.
Cliente
Maneja los eventos posteriores a la sesión
Siempre usa webhooks para determinar el resultado final. Los clientes pueden cerrar la pestaña, perder conexión o nunca llegar a tusuccess_url.
Eventos de Checkout Session
Cuando el registro se completa, Fintoc envía un eventocheckout_session.finished con la información del customer y payment_method:
Eventos de Payment Method
Fintoc también envía un eventopayment_method.activated. El campo data del evento contiene un PaymentMethod como este:
customer como el ID del payment_method. Los necesitas para crear cargos más adelante.
Resumen de eventos
Debes suscribirte a todos los siguientes eventos posteriores a la sesión:Crear un cargo contra el método de pago guardado
Una vez que el método de pago estáactive, puedes cobrarlo de dos formas:
- Crear una invoice y dejar que Fintoc la cobre. La invoice registra lo que tu cliente debe, guarda el historial de cada intento de cobro y te deja un link de pago como respaldo. Úsala cuando el cobro salde una deuda, incluida la recaudación recurrente.
- Crear un Payment Intent directamente. Úsalo para un cobro puntual que no necesitas seguir como deuda.
payment_intent. La diferencia es dónde vive ese payment_intent: un cobro hecho a través de una invoice queda anclado a la invoice, así que puedes reintentarlo, cambiar de método de pago y conciliarlo contra el monto que se debe.
Cobra el método de pago a través de una invoice
Cobrar una invoice toma dos llamadas: creas la invoice y después la finalizas. Fintoc nunca finaliza una invoice que creaste tú.
1) Crea la invoice
Crea la Invoice para elcustomer, con default_payment_method en el método de pago que guardaste:
Servidor
Node
Fintoc responde con la invoice en estado
draft:
draft no cobra nada. Usa el estado draft para revisar el monto o cambiar los ítems con Add lines y Update a line item antes de cobrar.
2) Finaliza la invoice para cobrarla
Finaliza la invoice para pasarla aopen. Como el collection_method es charge_automatically, Fintoc cobra el default_payment_method después de finalizarla:
Servidor
open con un pago pending hasta que el pago se resuelve. Sigue el resultado con invoice.payment_succeeded o invoice.payment_failed; Fintoc envía esos eventos de invoice junto a payment_intent.succeeded o payment_intent.failed.
3) Reintenta un cobro fallido
Un cobro fallido deja la invoiceopen, así que el monto que tu cliente debe queda abierto en la invoice. Reintenta el cobro con Pagar una invoice, contra el mismo método de pago o contra otro método activo del mismo customer:
Servidor
payment_method para cobrar el default_payment_method de la invoice. Fintoc agrega cada intento al arreglo payments de la invoice, con su propio payment_intent y status, así que la invoice guarda el historial completo de cómo intentaste cobrarla.
Para saldar una invoice que cobraste fuera de Fintoc, por transferencia o en efectivo, llama al mismo endpoint con external_payment en true. Fintoc pasa la invoice a paid sin cobrar nada, y reporta external_payment como true.
Cobra la invoice sin cargar el método guardado
Para que tu cliente pague en vez de cobrarle, crea la invoice concollection_method en send_invoice. Fintoc entonces deja la invoice open cuando la finalizas, en vez de cobrarla, y el default_payment_method pasa a ser opcional:
Servidor
open. Cuando la invoice llega a open, su hosted_invoice_url apunta a una página de pago alojada por Fintoc. Tu cliente puede pagar ahí con los métodos de pago habilitados en la cuenta de tu organización, sin necesitar un método de pago guardado. Envíale ese link por tu propio canal, como email o WhatsApp. Fintoc no contacta a tu cliente por ningún canal.
Maneja los eventos de invoice
Suscríbete a los siguientes eventos para seguir la invoice:Cobra el método de pago con un Payment Intent
Cobra elpayment_method guardado directamente creando un Payment Intent con los IDs del payment_method y customer:
Servidor
Node
Fintoc responde con el Payment Intent creado:
Maneja los eventos de pago
Fintoc envía estos eventos para todo cobro, ya sea que hayas creado el cobro a través de una invoice o como un Payment Intent suelto. Suscríbete a ellos para rastrear el resultado del pago:Prueba tu integración
Usando tu Secret Key de modo de prueba, crea Checkout Sessions que simulan el flujo completo de setup y pago sin mover dinero.1) Crea una Checkout Session de setup usando credenciales de prueba
Crea una Checkout Session conflow: setup usando tu Secret Key de modo de prueba. Completa el flujo de registro en la página alojada por Fintoc usando las siguientes credenciales:
Credenciales de prueba:
PAC
- Usuario (RUT):
11.111.111-1 - Contraseña:
jonsnow
Tarjeta
Usa estas tarjetas de prueba para los flujos de setup con tarjeta en Chile:2) Verifica el método de pago guardado
Después de completar el registro de prueba, deberías recibir los eventos webhookcheckout_session.finished y payment_method.activated. Verifica que:
- El ID del
payment_methodesté presente en el payload del evento. - El ID del
customercoincida con el cliente que registraste.
3) Crea un cargo de prueba contra el método guardado
Usando los IDs delcustomer y payment_method del paso 2, crea un Payment Intent contra el método guardado. Verifica que:
- Recibas el evento
payment_intent.succeeded. - El monto coincida con el que enviaste.
- El método de pago usado sea el PAC o tarjeta guardada.
default_payment_method en el método guardado, finalízala y verifica que:
- Recibas
invoice.created,invoice.finalized,invoice.payment_created,invoice.payment_succeededeinvoice.paid, junto apayment_intent.succeeded. - La invoice quede en estado
paid, con el intento registrado enpaymentsy tumetadatapersistido.
El modo de prueba aún no soporta guardar un Payment Method en México.