> ## 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 Iniciación de Pagos de Fintoc

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

<Frame>
  <img src="https://mintcdn.com/fintoc-49b8bee8/YQmOnq8Zegydl6oL/images/40e0b1888c86590031351e94422f1d5e23207fcb2f795a93eb76cbb6c780a9eb-accept-payment-diagram.png?fit=max&auto=format&n=YQmOnq8Zegydl6oL&q=85&s=653e7ae98608d0462ec14d67546c6ca5" width="1824" height="1046" data-path="images/40e0b1888c86590031351e94422f1d5e23207fcb2f795a93eb76cbb6c780a9eb-accept-payment-diagram.png" />
</Frame>

# Opcional: instala nuestro SDK de backend

<InstallSDK />

# 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_data": {
      "tax_id": {
        "type": "cl_rut",
        "value": "12088191"
      },
      "name": "Felipe Castro",
      "email": "name@example.com",
      "metadata": {}
    },
    "billing_items": [
      {
        "price_data": {
          "product_data": {
            "name": "T‑Shirt A",
            "description": "Limited edition"
          },
          "unit_amount": 350000
        },
        "quantity": 1
      }
    ],
    "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.<br />Si tu pago usa pesos chilenos, un monto de CLP 2476 se representa como 2476.<br />Si tu pago usa pesos mexicanos, un monto de MXN 24.76 se representa como 2476.<br />[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.                                                                                                                                                                                                                                  |

<Info>
  **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.
</Info>

## 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 **requerido** que identifica al cliente a nivel fiscal o regulatorio.<br />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. |
| `name`     | `string` | Nombre completo opcional del cliente.                                                                                                                                                                                                                                                                      |
| `email`    | `string` | Correo opcional del cliente vinculado a una Checkout Session. Se usa para notificar al usuario en caso de un reembolso.                                                                                                                                                                                    |
| `metadata` | `object` | Datos personalizados opcionales que pueden almacenar información adicional sobre el cliente (p. ej., IDs internos, referencias de CRM o etiquetas)                                                                                                                                                         |

## Preseleccionar Métodos 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",
    "flow": "payment",
    "success_url": "https://merchant.com/success",
    "cancel_url": "https://merchant.com/987654321",
    "payment_method_types": ["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": {}
    },
    "billing_items": [
      {
        "price_data": {
          "product_data": {
            "name": "T‑Shirt A",
            "description": "Limited edition"
          },
          "unit_amount": 350000,
          "recurrence": null
        },
        "quantity": 1
      }
    ]
  }'
```

```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_method_types`   | `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_initiation` (transferencias bancarias) y `card` |
| `payment_method_options` | `hash`             | Arreglo opcional de configuraciones para cada método de pago disponible                                                                                                       |

<Frame caption="**Izquierda:** Vista predeterminada que muestra todos los métodos disponibles (transferencia bancaria y tarjetas) cuando no se define el parámetro `payment_method`. **Derecha**: Flujo preseleccionado de `bank transfer` para Banco Estado, mostrando directamente el formulario de pago específico de la institución.">
  <img src="https://mintcdn.com/fintoc-49b8bee8/SkvJJ-DZ5D4yC6tQ/images/effced12c9374dc996f5d970cd2feb4045814933dcf0e4204d94dcd2746f2244-payment-methods.png?fit=max&auto=format&n=SkvJJ-DZ5D4yC6tQ&q=85&s=80525a7dbf2d3060240de80027475dff" width="500px" data-path="images/effced12c9374dc996f5d970cd2feb4045814933dcf0e4204d94dcd2746f2244-payment-methods.png" />
</Frame>

<Info>
  **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 de 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.
</Info>

## 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",
  "amount": 350000,
  "cancel_url": "https://merchant.com/987654321",
  "created_at": "2024-06-04T15:32:46.721Z",
	"success_url": "https://merchant.com/success",
  "currency": "CLP",
  "customer_data": {
    "email": "name@example.com",
    "metadata": {},
    "name": "Felipe Castro",
    "tax_id": {
      "type": "cl_rut",
      "value": "12088191"
    }
  },
  "metadata": {},
  "mode": "test",
  "object": "checkout_session",
  "status": "created",
  "updated_at": "2024-06-04T15:32:46.721Z",
  "redirect_url": "https://checkout.fintoc.com/checkout_session_01HXY3Z7X5YQ54V8G2E1KJQAVF"
}
```

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.

# Elige cómo abrir el widget de Fintoc

El Widget de Fintoc es el componente del lado del cliente con el que tus clientes interactuarán para realizar pagos usando Fintoc. Maneja la validación de credenciales, autenticación multifactor y gestión de errores para todas las instituciones financieras soportadas.

Tienes dos opciones para abrir el widget:

## Opción 1: Abre el widget en tu frontend

Si quieres mostrar el Widget de Fintoc directamente en tu página de checkout (sin redirigir al usuario), usa el `session_token` devuelto en la respuesta de la API al crear una **Checkout Session**.

Usa tu [Public Key](/es/v2023-11-15/docs/home/api-keys) y el Session Token para configurar el widget.

```html theme={null}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta name="viewport" content="width=device-width,initial-scale=1.0, maximum-scale=1.0">
    <title>Fintoc Demo</title>
    <script src="https://js.fintoc.com/v1/"></script>
  </head>
  <body>
    <script>
      window.onload = () => {
        const widget = Fintoc.create({
          sessionToken: 'cs_XXXXXXXX_sec_YYYYYYYY',
          product: 'payments',
          publicKey: 'YOUR_PUBLIC_KEY',
          onSuccess: () => {},
        });
        widget.open();
      };
    </script>
  </body>
</html>
```

Si estás recibiendo pagos en México, define el parámetro `country` como `mx`.

Para más opciones de configuración y uso avanzado, consulta la [guía del Widget](/es/v2023-11-15/docs/resources/widget).

<Info>
  **Usa nuestro Widget Webview si estás creando una aplicación móvil**

  Si estás integrando Fintoc en una aplicación iOS o Android, puedes usar nuestra [integración Webview.](/es/v2023-11-15/docs/resources/widget/widget-webview-integration-old)
</Info>

## Opción 2: Abre el widget mediante una Página de Redirección

Alternativamente, puedes redirigir a los usuarios a una página de pago alojada por Fintoc. Después de completar el pago, serán redirigidos automáticamente a tu sitio.

Para usar este método, incluye los parámetros `success_url` y `cancel_url` al crear la **Checkout Session**. La respuesta de la API incluirá una `redirect_url` que puedes usar para enviar al usuario a la página de pago.

Según el resultado del pago, el usuario será redirigido a la URL de éxito o cancelación.

Para más detalles, consulta la [guía de integración de la Página de Redirección](/es/v2023-11-15/docs/payments/redirect-page).

# 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 frontend usarás el callback del widget, y para tu backend usarás los eventos enviados por webhooks.

<Info>
  **Usa eventos de webhooks para completar pagos**

  Tu cliente podría cerrar la ventana del navegador o salir de la app antes de que se ejecute el callback `onSuccess` del widget. Por esta razón, siempre debes usar el evento `checkout_session.finished` para manejar acciones posteriores al pago 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.
</Info>

## Maneja el resultado del pago en tu frontend

Una vez que un Pago asociado a la Checkout Session finaliza exitosamente, el widget ejecuta el callback `onSuccess`. Necesitas pasar esta función al widget al momento de crearlo.

Con este callback, puedes decidir qué hacer con el frontend de tu usuario una vez que el pago esté completo, por ejemplo:

* Redirigir al usuario a una vista post-venta o post-pago
* Mostrar al usuario una pantalla de éxito.

<Info>
  **No uses este callback como confirmación de pago**

  No deberías confiar en el callback `onSuccess` como confirmación de un pago exitoso, ya que el frontend es un entorno inseguro y un tercero malicioso podría ejecutar una función JavaScript que simule que la transferencia se ejecutó exitosamente.

  Para un mecanismo de validación más completo, recomendamos encarecidamente [integrar webhooks](/es/v2023-11-15/docs/resources/webhooks-walkthrough) y suscribirte al evento `checkout_session.finished`. Al implementar webhooks, puedes asegurar actualizaciones oportunas y precisas sobre los estados de pago, mejorando la seguridad y confiabilidad generales de tu proceso de confirmación de pago.
</Info>

### Maneja errores

No solo necesitas manejar pagos exitosos porque los pagos también pueden fallar. Por ejemplo, que tu cliente no tenga fondos en su cuenta bancaria para completar el pago.

Cuando un pago falla o es rechazado por tu cliente, el widget ejecuta el callback `onExit`. Con este callback, puedes manejar errores en tu frontend. Por ejemplo, puedes invitar a tu cliente a usar otro método de pago.

## Completa el pago en tu backend

Fintoc envía un evento `checkout_session.finished` cuando el pago se completa. 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 el pago relacionado, y se ve así:

```json theme={null}
{
  "id": "evt_a4xK32BanKWYn",
  "object": "event",
  "type": "checkout_session.finished",
  "data": {
    id: "cs_li5531onlFDi235",
    created_at: "2025-06-15T15:22:11.474Z",
    object: "session",
    currency: "clp",
    amount: 1200,
    customer_email: "customer@example.com",
    expires_at: "2025-06-16T15:22:11.474Z",
    product: "payments",
    mode: "live",
    status: "finished",
    session_token: "cs_li5531onlFDi235_sec_a4xK32BanKWYn",
    type: "embedded",
    country: 'cl',
    metadata: {
    	order_id: "#12513"
  	},
    payment_methods: [
      'payment_intent'
    ],
    payment_method_options: {
      payment_intent: {
        holder_type: 'individual',
        recipient_account: {
          "holder_id": "183917137",
          "number": "123456",
          "type": "checking_account",
          "institution_id": "cl_banco_de_chile"
        },
        sender_account: {
          holder_id: {
            editable: 'false',
            value: 123456789
          },
          institution_id: {
            editable: 'false',
            value: 'cl_banco_estado'
          }
        }
      }
    },
    payment_intent: {
      "id": "pi_BO381oEATXonG6bj",
      "object": "payment_intent",
      "amount": 1200,
      "currency": "CLP",
      "status": "succeeded",
      "reference_id": "90123712",
      "transaction_date": "2025-06-15T15:22:11.474Z",
      "metadata": {
        order_id: "#12513"
      },
      "error_reason": null,
      "recipient_account": {
        "holder_id": "183917137",
        "number": "123456",
        "type": "checking_account",
        "institution_id": "cl_banco_de_chile"
      },
      "sender_account": {
        "holder_id": "192769065",
        "number": "123456",
        "type": "checking_account",
        "institution_id": "cl_banco_estado"
      },
      "created_at": "2021-10-15T15:23:11.474Z"
    }
  }
```

Debes manejar los siguientes eventos al usar nuestro producto de Iniciación de Pagos:

| 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 final 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. Es útil para confirmar pagos que estaban previamente en estado pendiente    | Confirma la orden del cliente                    |
| `payment_intent.failed`     | Enviado cuando el pago relacionado con una checkout session falla. Se usa para determinar el estado final de pagos que estaban previamente en estado pendiente | Ofrece al cliente otro intento de 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 `id` y `status` del payment\_intent:

```json theme={null}
{
  "id": "evt_a4xK32BanKWYn",
  "object": "event",
  "type": "checkout_session.finished",
  "data": {
    "id": "cus_NV2HibNV2HibNV2Hib",
    "amount": 350000,
    "business_profile": {},
    "cancel_url": "https://merchant.example/cancel",
		"success_url": "https://merchant.example/success",
    "created_at": "2021-10-15T15:22:11.474Z",
    "currency": "CLP",
    "customer": null,
    "customer_data": {
      "email": "user@example.com",
      "name": "Jane Doe",
      "tax_id": {
        "type": "cl_rut",
        "value": "285509548"
      },
      "metadata": {
        "crm_id": "A-771"
      }
    },
    "expires_at": "2024-11-12T14:41:25Z",
    "metadata": {
      "order_id": "#12513"
    },
    "mode": "test",
    "status": "finished",
    "redirect_url": "https://pay.fintoc.com/checkout/cs_123"
  }
}
```

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.    |

<Info>
  **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, 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.
</Info>