> ## Documentation Index > Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt > Use this file to discover all available pages before exploring further. # Aceptar un pago > Aprende a usar la API de Fintoc para aceptar pagos únicos Hay tres pasos para aceptar pagos usando Fintoc: 1. En tu backend, crea una `Checkout Session` usando tu **Secret Key** 2. Redirige a tu usuario a 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 nuestro SDK de backend # 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](/es/v2023-11-15/docs/home/api-keys), crea una `Checkout Session` desde tu backend con los parámetros requeridos: `amount`, `currency`, `success_url` y `cancel_url` como en el ejemplo siguiente: ```curl theme={null} 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": { "tax_id": { "type": "cl_rut", "value": "12088191" }, "name": "Felipe Castro", "email": "name@example.com", "metadata": {} }, "metadata": { "order": "987654321" } }' ``` ```javascript Node theme={null} 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' }); ``` ```python theme={null} 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' ) ``` ```ruby theme={null} 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](/es/v2023-11-15/docs/home/currencies). | | `currency` | CLP | Moneda **requerida** que se está usando para el pago. Actualmente soportamos CLP y MXN. | | `success_url` | `https://merchant.com/success` | URL **requerida** a la que se redirige al usuario en caso de pago exitoso. | | `cancel_url` | `https://merchant.com/987654321` | URL **requerida** a la que se redirige al usuario en caso de que decida cancelar el pago y volver a tu sitio web. | | `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 subcomercio** Tambié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 una `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](/es/v2023-11-15/docs/payments/overview-payment-initiation/transaction-limits) para un banco seleccionado en el método de iniciación de pagos. | Atributo | Tipo | Descripción | | :--------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tax_id` | `object` | Objeto 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 tributaria real como string.
**Uno de `tax_id` o `email` es requerido** | | `name` | `string` | Nombre completo opcional del cliente. | | `email` | `string` | Correo del cliente vinculado a una Checkout Session. Se usa para notificar al usuario en caso de un reembolso.
**Uno de tax\_id o email es requerido** | | `metadata` | `object` | Datos personalizados opcionales que pueden almacenar información adicional sobre el cliente (p. ej., IDs internos, referencias de CRM o etiquetas) | **Flujos de pago específicos por banco para cuentas empresariales y montos altos** En pagos bank\_transfer en Chile, si el pago está por encima de los [límites de transacción](/es/v2023-11-15/docs/payments/overview-payment-initiation/transaction-limits) o envías un `customer` con un `tax_id.value` de una empresa en lugar de una persona natural, Fintoc permitirá solo los bancos que tienen flujos de pago especiales para este tipo de transacciones (Banco Estado, Banco de Chile y Banco Santander). Puedes probarlo usando [estas credenciales](/es/v2023-11-15/docs/payments/payment-initiation-test-your-integration#testing-with-banco-estados-compraqui-payment-flow). ## Preseleccionar un Método de Pago (Opcional) Puedes crear una `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 has habilitado en Fintoc. Alternativamente, puedes definir explícitamente el método o los métodos de pago para la sesión. Por ejemplo, en la solicitud a continuación, se define 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 estará limitado a este método y banco específicos. ```curl theme={null} 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", "payment_methods": ["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": {} } }' ``` ```javascript Node theme={null} 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' }); ``` ```python theme={null} 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' ) ``` ```ruby theme={null} 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_methods` | `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_intent` (transferencias bancarias) y `card` | | `payment_method_options` | `hash` | Arreglo opcional de configuraciones para cada método de pago disponible | **Usar tu propia Página de Checkout** Cuando tienes tu propia página de checkout, debes definir el `payment_method` para redirigir a los usuarios al checkout alojado por Fintoc después de que ya hayan seleccionado su método de pago preferido. Esto se salta 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 maneje toda la experiencia de checkout. ## 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: ```json theme={null} { "id": "cs_li5531onlFDi235", "object": "checkout_session", "mode": "test", "status": "created", "amount": 350000, "currency": "CLP", "created_at": "2024-06-04T15:32:46.721Z", "updated_at": "2024-06-04T15:32:46.721Z", "success_url": "https://merchant.com/success", "cancel_url": "https://merchant.com/987654321", "redirect_url": "https://checkout.fintoc.com/checkout_session_01HXY3Z7X5YQ54V8G2E1KJQAVF", "metadata": {}, "customer": { "name": "Felipe Castro", "email": "name@example.com", "metadata": {}, "tax_id": { "type": "cl_rut", "value": "12088191" } } } ``` 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. ## Redirige al usuario a 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 a tu sitio. Según el resultado del pago, el usuario será redirigido a la 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](/es/v2023-11-15/docs/resources/webhooks-walkthrough) 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`: ```json theme={null} { "id": "evt_a4xK32BanKWYn", "object": "event", "type": "checkout_session.finished", "data": { "id": "cs_li5531onlFDi235", "mode": "test", "amount": 350000, "object": "checkout_session", "status": "finished", "currency": "CLP", "metadata": {}, "cancel_url": "https://merchant.com/987654321", "created_at": "2026-01-13T18:48:25Z", "expires_at": "2026-01-14T18:48:25Z", "success_url": "https://merchant.com/success", "redirect_url": "https://checkout.fintoc.com/checkout_session_01HXY3Z7X5YQ54V8G2E1KJQAVF", "session_token": null, "customer_email": null, "customer": { "name": "Felipe Castro", "email": "name@example.com", "metadata": {}, "tax_id": { "type": "cl_rut", "value": "12088191" } }, "payment_methods": [ "payment_intent" ], "business_profile": {}, "payment_resource": { "payment_intent": { "id": "pi_38DNJo3rbvGUzKFvCGZ6dxR1Kxx", "mode": "test", "amount": 350000, "object": "payment_intent", "status": "succeeded", "currency": "CLP", "metadata": {}, "created_at": "2026-01-13T18:48:31Z", "expires_at": "2026-01-14T18:48:25Z", "error_reason": null, "payment_type": "bank_transfer", "reference_id": null, "widget_token": null, "customer_email": null, "sender_account": { "type": "checking_account", "number": "813990168", "holder_id": "415792638", "institution_id": "cl_banco_falabella" }, "business_profile": {}, "transaction_date": null, "recipient_account": null, "payment_type_options": {} } }, "payment_method_options": {} } } ``` 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 con una checkout session se completa con éxito. | Confirma la orden del cliente | | `payment_intent.failed` | Enviado cuando el pago relacionado con una checkout session falla. | Ofrece al cliente otro intento de pago. | | `payment_intent.requires_action` | Enviado cuando el pago relacionado con una checkout session necesita una acción del usuario.
Se recibirá cuando una `bank transfer` desde una cuenta empresarial requiere la aprobación de más de un representante. | Informa al usuario la acción necesaria para aprobar el pago, según el `next_action` informado por el webhook de Fintoc. | **Manejo de pagos asíncronos después de que termina la Checkout Session** En 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 la aprobación de más de un representante. En estos casos, al recibir el `payment_intent.requires_action` 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 el estado final del pago tan pronto como se confirme. # Prueba tu integración Usando tu [Secret Key de API en modo prueba](/es/v2023-11-15/docs/resources/test-mode), puedes crear pagos que simulan resultados exitosos y fallidos sin mover dinero real. Esto te permite validar tu flujo de pago completo de extremo a extremo: * Tus solicitudes a la API del backend (crear sesiones y manejar respuestas) * El flujo de redirección desde tu frontend a la `redirect_url` y de vuelta a la `success_url` o `cancel_url` después del pago * Webhooks para eventos posteriores al pago Para aprender cómo activar escenarios específicos, usa las **credenciales de prueba** y valores especiales de prueba descritos en nuestra [guía de pruebas](/es/v2023-11-15/docs/payments/payment-initiation-test-your-integration).