Skip to main content
Guarda el método de pago de un cliente una vez y cóbralo más tarde para pagos on-demand o de monto variable, sin crear una suscripción recurrente. A diferencia del flujo de suscripción, el flujo de setup no acopla el registro con facturación recurrente, por lo que tú decides cuándo y cuánto cobrar. Configura un método de pago y cóbralo más tarde en cuatro pasos:
  1. En tu backend, crea una Checkout Session con flow: setup.
  2. Redirige a tu cliente para completar el registro en la página de checkout alojada por Fintoc.
  3. Maneja los eventos posteriores a la sesión para guardar el payment_method y customer.
  4. Cobra el método de pago guardado bajo demanda, creando una invoice o un Payment Intent.
El siguiente diagrama muestra cómo funciona el flujo de setup:

Crea una Checkout Session

El Checkout Session con el flujo setup 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
Después de crear la Checkout Session, Fintoc responde con los detalles de la sesión y un 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 al redirect_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 tu success_url.

Eventos de Checkout Session

Cuando el registro se completa, Fintoc envía un evento checkout_session.finished con la información del customer y payment_method:

Eventos de Payment Method

Fintoc también envía un evento payment_method.activated. El campo data del evento contiene un PaymentMethod como este:
Guarda tanto el ID del 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.
Los dos caminos terminan en un 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ú.
fintoc-invoice-creation-diagram

1) Crea la invoice

Crea la Invoice para el customer, con default_payment_method en el método de pago que guardaste: Servidor
Node
Fintoc responde con la invoice en estado draft:
Una invoice en 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 a open. Como el collection_method es charge_automatically, Fintoc cobra el default_payment_method después de finalizarla: Servidor
El cobro es asíncrono: la invoice queda 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 invoice open, 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
Omite 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 con collection_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
Llama a Finalizar una invoice para pasarla a 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 el payment_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 con flow: 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
Selecciona la cuenta según el resultado final que quieras probar:

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 webhook checkout_session.finished y payment_method.activated. Verifica que:
  • El ID del payment_method esté presente en el payload del evento.
  • El ID del customer coincida con el cliente que registraste.

3) Crea un cargo de prueba contra el método guardado

Usando los IDs del customer 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.
Después prueba el camino de la invoice con los mismos IDs: crea una invoice con default_payment_method en el método guardado, finalízala y verifica que:
  • Recibas invoice.created, invoice.finalized, invoice.payment_created, invoice.payment_succeeded e invoice.paid, junto a payment_intent.succeeded.
  • La invoice quede en estado paid, con el intento registrado en payments y tu metadata persistido.
El modo de prueba aún no soporta guardar un Payment Method en México.