Saltar al contenido principal
Crea un flujo que guarde el método de pago de un cliente durante un pago o a través de una sesión de setup independiente. Para flujos de pago donde los clientes pagan con frecuencia, como apps de transporte o delivery, puedes permitir que tus clientes guarden un método de pago para pagos futuros. Un método de pago guardado puede ser una tarjeta o una cuenta bancaria, de modo que sus siguientes pagos requieran menos pasos. Puedes guardar el método de pago de un cliente de dos maneras:
  1. Guardar durante un pago: crea una Checkout Session con flow en payment y save_payment_method en enabled. Tu cliente obtiene la opción de guardar el método de pago para pagos futuros.
  2. Guardar sin un pago actual: crea una Checkout Session con flow en setup para registrar un método de pago sin procesar un pago.

Opción 1: Guardar durante un pago (recomendado)

El cliente paga y su método de pago se guarda en un solo paso.

Crea o elige un Customer

Cada método de pago guardado debe pertenecer a un Customer. Si ya tienes uno, reutiliza su id. De lo contrario, puedes crearlo primero con la API de Customers o enviar customer_data en la Checkout Session para crear el Customer en línea. Servidor
Node
Fintoc responde con el Customer creado:
Guarda el id devuelto (por ejemplo, cus_3B2bODrQFje7ZVkT69xyaTSDwXQ). Si ya existe un Customer con el mismo tax_id, la solicitud devuelve un error 409 Conflict. Para reutilizar un Customer existente, envía su id en customer en lugar de customer_data.

Crea una Checkout Session con save_payment_method

Crea una Checkout Session con el ID del customer, flow en payment y save_payment_method en enabled. Fintoc procesa el pago y, si tu cliente elige guardar el método de pago durante el flujo, almacena sus credenciales para uso futuro. Servidor
Node
Fintoc responde con el CheckoutSession creado, incluyendo su redirect_url:

Redirige al cliente

Usa el redirect_url devuelto en la respuesta para redirigir a tu cliente a la página alojada por Fintoc, donde completa el pago y puede elegir guardar sus credenciales para pagos futuros. Cliente

Maneja los eventos posteriores al pago

Siempre usa webhooks para determinar el resultado final. Tu cliente puede cerrar la pestaña, perder conexión o nunca llegar a tu success_url.

Eventos de Checkout Session

  • checkout_session.finished: Enviado cuando una Checkout Session alcanza un estado final exitoso. El evento incluye el resultado del pago y, si tu cliente optó por hacerlo, el payment_method guardado. Ejemplo del objeto data:

Eventos de Payment Method

Si tu cliente eligió guardar el método, Fintoc también envía un evento payment_method.activated. El campo data del evento contiene un PaymentMethod como este:
Suscríbete a los siguientes eventos posteriores a la sesión:

Opción 2: Guarda un método sin un pago actual

Crea una sesión de Setup

El objeto Checkout Session representa tu intención de guardar un método de pago sin procesar un pago. Usando tu Secret Key, crea una Checkout Session desde tu backend con flow en setup: Servidor
Node
Fintoc responde con el CheckoutSession creado, incluyendo su redirect_url:
Envía payment_method_options para preseleccionar un banco para tu clientePuedes crear la Checkout Session con un banco específico enviando su institution_id dentro de sender_account en payment_method_options. Tu cliente entonces solo podrá guardar una cuenta bancaria de esa institución. También puedes enviar el tax ID chileno (RUT) del cliente como holder_id, para que el flujo lo prellene.Recomendamos esta opción cuando tu cliente selecciona su banco en tu flujo antes de que crees la sesión, para que no tenga que seleccionar un banco dos veces.También puedes restringir el enrolamiento por tipo de tarjeta o tipo de cuenta. Envía kinds (credit, debit) dentro de payment_method_options.card para limitar los tipos de tarjeta. Envía types (checking_account) dentro de payment_method_options.pac.sender_account para limitar los tipos de cuenta. Para no aplicar ninguna restricción, omite la opción en lugar de enviar un arreglo vacío: un arreglo vacío no permite nada.

Redirige al cliente

Después de crear una sesión, recibes un redirect_url que usas para redirigir a tu cliente y que pueda registrar su cuenta bancaria como método de pago guardado. Cliente

Maneja los eventos posteriores a la sesión

Suscríbete a checkout_session.finished, checkout_session.expired y payment_method.activated para el flujo independiente de setup.

Crea una sesión de pago con un método de pago guardado

Si tu cliente tiene un método de pago bank_transfer guardado, puedes crear una Checkout Session de pago que use el método guardado. Fintoc redirige a tu cliente directamente al paso de aprobación bancaria, sin pedirle que inicie sesión con sus credenciales bancarias. Servidor
Node
Fintoc responde con el CheckoutSession creado, incluyendo su redirect_url:

Redirige al cliente

Usa el redirect_url para redirigir a tu cliente a la página alojada por Fintoc, donde va directamente al paso de aprobación bancaria sin iniciar sesión con sus credenciales bancarias. Cliente

Maneja los eventos posteriores al pago

Después del pago, Fintoc envía checkout_session.finished, checkout_session.expired, payment_intent.succeeded, o payment_intent.failed, según el resultado:

Prueba tu integración

Usando tu Secret Key de modo de prueba, puedes crear Checkout Sessions que simulan resultados exitosos y fallidos sin mover dinero. Esto te permite validar tu flujo completo de setup y pago 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 setup o pago
  • Los webhooks para eventos posteriores a la sesión que guardan el customer, el payment_method y el resultado del pago
    • Después de un setup o pago exitoso que guarda un payment_method, prueba creando una sesión de pago con el método guardado del cliente
Para aprender cómo disparar escenarios específicos, usa las credenciales de prueba y valores especiales de prueba descritos en nuestra guía de pruebas. Para un flujo bank_transfer en modo de prueba, abre el redirect_url, selecciona el banco de prueba e inicia sesión con las credenciales de prueba user_good y pass_good. Esta combinación simula un registro y pago exitosos. Después de una ejecución exitosa, Fintoc envía un evento checkout_session.finished con status en finished:
Si tu cliente optó por hacerlo, Fintoc también envía un evento payment_method.activated con status en active: