Aceptar un pago

Construye un flujo de pago que cobre pagos únicos en CLP o MXN a través de una página de checkout alojada por Fintoc. Para aceptar pagos con Fintoc, completas tres pasos:

En tu backend, crea un Checkout Session usando tu Secret Key
Redirige a tu cliente para completar el pago en la página de checkout alojada por Fintoc
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 el SDK del backend

Python
Node

Si usas Python, puedes instalar nuestro SDK de Python para interactuar con nuestra API de manera más sencilla. El SDK maneja automáticamente la paginación, te permite verificar fácilmente los webhooks de Fintoc y ofrece muchas otras funciones útiles.

pip install fintoc

Si usas Node, puedes instalar nuestro SDK de Node para interactuar con nuestra API de manera más sencilla. El SDK maneja automáticamente la paginación, te permite verificar fácilmente los webhooks de Fintoc y ofrece muchas otras funciones útiles.

npm install fintoc

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, crea un Checkout Session desde tu backend con los parámetros requeridos: amount, currency, success_url y cancel_url, como en el ejemplo a continuación: Servidor

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/cancel",
    "customer_data": {
      "tax_id": {
        "type": "cl_rut",
        "value": "11.111.111-1"
      },
      "name": "Felipe Castro",
      "email": "jon@snow.com",
      "metadata": {}
    },
    "metadata": {
      "order": "987654321"
    }
  }'

Node

const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_TEST_SECRET_API_KEY');

const checkoutSession = await fintoc.checkoutSessions.create({
  amount: 350000,
  currency: 'CLP',
  success_url: 'https://merchant.com/success',
  cancel_url: 'https://merchant.com/cancel',
  customer_data: {
    tax_id: {
      type: 'cl_rut',
      value: '11.111.111-1'
    },
    name: 'Felipe Castro',
    email: 'jon@snow.com',
    metadata: {}
  },
  metadata: {
    order: '987654321'
  }
});

from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_API_KEY')

checkout_session = client.checkout_sessions.create(
    amount=350000,
    currency='CLP',
    success_url='https://merchant.com/success',
    cancel_url='https://merchant.com/cancel',
    customer_data={
        'tax_id': {
            'type': 'cl_rut',
            'value': '11.111.111-1'
        },
        'name': 'Felipe Castro',
        'email': 'jon@snow.com',
        'metadata': {}
    },
    metadata={
        'order': '987654321'
    }
)

Fintoc responde con el objeto Checkout Session creado, incluyendo el redirect_url que usas para enviar al cliente al pago:

{
  "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/cancel",
  "redirect_url": "https://pay.fintoc.com/checkout/cs_li5531onlFDi235",
  "metadata": {
    "order": "987654321"
  },
  "customer": {
    "id": "cus_3B2bODrQFje7ZVkT69xyaTSDwXQ",
    "object": "customer",
    "name": "Felipe Castro",
    "email": "jon@snow.com",
    "metadata": {},
    "tax_id": {
      "type": "cl_rut",
      "value": "11.111.111-1"
    }
  }
}

Parámetro	Ejemplo	Descripción
`amount`	350000	Requerido. Un entero positivo que representa el monto a cobrar, en la unidad menor de la moneda. CLP no tiene unidad menor, por lo que `350000` significa CLP 350000. MXN usa centavos, por lo que `350000` significa MXN 3500.00. Lee más sobre monedas.
`currency`	CLP o MXN	Requerido. Código ISO 4217 de tres letras de la moneda. Fintoc soporta `CLP` y `MXN`; consulta las monedas soportadas para ver la lista completa.
`success_url`	`https://merchant.com/success`	Requerido. URL a la cual Fintoc redirige al cliente después de un pago exitoso.
`cancel_url`	`https://merchant.com/cancel`	Requerido. URL a la cual Fintoc redirige al cliente si cancela el pago y vuelve a tu sitio.
`metadata`	`{"order": "987654321"}`	Conjunto de pares clave-valor que puedes adjuntar a un objeto, útil para almacenar información adicional en un formato estructurado.

Business profile (opcional)

Envía el objeto Business Profile si estás procesando pagos para un submerchantTambié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 un Checkout Session, puedes incluir información del cliente enviando un objeto customer_data (o customer con el id de un Customer existente). Esta información permite a Fintoc mostrar solo los métodos de pago disponibles para ese cliente específico. Por ejemplo, Fintoc oculta un banco cuando el monto excede su límite de transacción.

Atributo	Tipo	Descripción
`tax_id`	`object`	Requerido si no hay `email`. 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 un tax ID chileno (RUT) o `mx_rfc` para un tax ID mexicano (RFC). También incluye un campo `value` que contiene el identificador fiscal como string. 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`.
`name`	`string`	Nombre completo del cliente.
`email`	`string`	Requerido si no hay `tax_id`. Dirección de email del cliente.
`metadata`	`object`	Datos personalizados que almacenan información adicional sobre el cliente, como IDs internos, referencias de CRM o etiquetas.

Flujos de pago específicos de banco para cuentas empresariales y montos altosEn Chile, algunos pagos bank_transfer requieren bancos con flujos de pago especiales: Banco Estado, Banco de Chile y Banco Santander. Fintoc limita la sesión a estos bancos cuando el pago excede los límites de transacción o el customer tiene un tax_id.value de empresa en lugar de persona natural. Puedes probar este flujo con estas credenciales.

Incluir una lista de ítems (opcional)

Al crear un Checkout Session, también puedes enviar los line_items, incluyendo información sobre los ítems de la sesión. Esto permite a Fintoc mostrar esta información en la página de checkout y mostrar solo los métodos de pago disponibles para productos específicos. Cada ítem debe tener:

Atributo	Tipo	Descripción
`quantity`	`integer`	Requerido. Número de unidades de este ítem que se compra.
`price_data`	`object`	Requerido. Objeto con el precio del ítem y los detalles del producto.

El objeto `price_data`

Atributo	Tipo	Descripción
`product_data`	`object`	Requerido. Objeto con información sobre el producto, como su nombre e imagen.
`currency`	`string`	Requerido. Código ISO 4217 de tres letras de la moneda (por ejemplo, `CLP`, `MXN`).
`unit_amount`	`integer`	Requerido. Precio por unidad del ítem, en la unidad menor de la moneda. CLP no tiene unidad menor, por lo que `350000` significa CLP 350000.

El objeto `product_data`

El objeto price_data contiene un objeto product_data con información del producto:

Atributo	Tipo	Descripción
`name`	`string`	Requerido. Nombre del producto o servicio que se compra.
`image_url`	`string`	URL de imagen para el producto. Debe ser una URL HTTPS. Relación de aspecto recomendada: 9:4.

El ejemplo a continuación crea un Checkout Session con un solo line item: Servidor

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/cancel",
    "line_items": [
      {
        "quantity": 1,
        "price_data": {
          "currency": "CLP",
          "unit_amount": 350000,
          "product_data": {
            "name": "Annual subscription",
            "image_url": "https://merchant.com/images/annual-subscription.png"
          }
        }
      }
    ]
  }'

Node

const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_TEST_SECRET_API_KEY');

const checkoutSession = await fintoc.checkoutSessions.create({
  amount: 350000,
  currency: 'CLP',
  success_url: 'https://merchant.com/success',
  cancel_url: 'https://merchant.com/cancel',
  line_items: [
    {
      quantity: 1,
      price_data: {
        currency: 'CLP',
        unit_amount: 350000,
        product_data: {
          name: 'Annual subscription',
          image_url: 'https://merchant.com/images/annual-subscription.png'
        }
      }
    }
  ]
});

from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_API_KEY')

checkout_session = client.checkout_sessions.create(
    amount=350000,
    currency='CLP',
    success_url='https://merchant.com/success',
    cancel_url='https://merchant.com/cancel',
    line_items=[
        {
            'quantity': 1,
            'price_data': {
                'currency': 'CLP',
                'unit_amount': 350000,
                'product_data': {
                    'name': 'Annual subscription',
                    'image_url': 'https://merchant.com/images/annual-subscription.png'
                }
            }
        }
    ]
)

Fintoc responde con el objeto Checkout Session creado, haciendo eco de los line_items que enviaste:

{
  "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/cancel",
  "redirect_url": "https://pay.fintoc.com/checkout/cs_li5531onlFDi235",
  "metadata": {},
  "line_items": [
    {
      "quantity": 1,
      "price_data": {
        "currency": "CLP",
        "unit_amount": 350000,
        "product_data": {
          "name": "Annual subscription",
          "image_url": "https://merchant.com/images/annual-subscription.png"
        }
      }
    }
  ]
}

Preseleccionar un método de pago (opcional)

Puedes crear un Checkout Session sin especificar métodos de pago. En este caso, los clientes 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 hayas habilitado en Fintoc. Alternativamente, puedes definir explícitamente el tipo o tipos de método de pago para la sesión. Por ejemplo, la solicitud a continuación establece el método bank_transfer y usa payment_method_options para preseleccionar la institución cl_banco_estado para el cliente. En este escenario, el flujo de pago presentado al cliente se limita a este método y banco específicos. Servidor

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/cancel",
      "payment_method_types": ["bank_transfer"],
      "payment_method_options": {
        "bank_transfer": {
          "sender_account": {
            "institution_id": {
              "value": "cl_banco_estado"
            }
          }
        }
      },
      "customer_data": {
        "tax_id": {
          "type": "cl_rut",
          "value": "11.111.111-1"
        },
        "name": "Felipe Castro",
        "email": "jon@snow.com",
        "metadata": {}
      }
    }'

Node

const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_TEST_SECRET_API_KEY');

const checkoutSession = await fintoc.checkoutSessions.create({
  amount: 350000,
  currency: 'CLP',
  success_url: 'https://merchant.com/success',
  cancel_url: 'https://merchant.com/cancel',
  payment_method_types: ['bank_transfer'],
  payment_method_options: {
    bank_transfer: {
      sender_account: {
        institution_id: {
          value: 'cl_banco_estado'
        }
      }
    }
  },
  customer_data: {
    tax_id: {
      type: 'cl_rut',
      value: '11.111.111-1'
    },
    name: 'Felipe Castro',
    email: 'jon@snow.com',
    metadata: {}
  }
});

from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_API_KEY')

checkout_session = client.checkout_sessions.create(
    amount=350000,
    currency='CLP',
    success_url='https://merchant.com/success',
    cancel_url='https://merchant.com/cancel',
    payment_method_types=['bank_transfer'],
    payment_method_options={
        'bank_transfer': {
            'sender_account': {
                'institution_id': {
                    'value': 'cl_banco_estado'
                }
            }
        }
    },
    customer_data={
        'tax_id': {
            'type': 'cl_rut',
            'value': '11.111.111-1'
        },
        'name': 'Felipe Castro',
        'email': 'jon@snow.com',
        'metadata': {}
    }
)

Atributo	Tipo	Descripción
`payment_method_types`	`array of strings`	Lista de tipos de método de pago disponibles para la sesión. Uno o más de `bank_transfer`, `card`.
`payment_method_options`	`object`	Conjunto de configuraciones para cada método de pago disponible.

Fintoc responde con el objeto Checkout Session creado, haciendo eco del método e institución preseleccionados:

{
  "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/cancel",
  "redirect_url": "https://pay.fintoc.com/checkout/cs_li5531onlFDi235",
  "metadata": {},
  "payment_method_types": [
    "bank_transfer"
  ],
  "payment_method_options": {
    "bank_transfer": {
      "sender_account": {
        "institution_id": {
          "value": "cl_banco_estado"
        }
      }
    }
  },
  "customer": {
    "id": "cus_3B2bODrQFje7ZVkT69xyaTSDwXQ",
    "object": "customer",
    "name": "Felipe Castro",
    "email": "jon@snow.com",
    "metadata": {},
    "tax_id": {
      "type": "cl_rut",
      "value": "11.111.111-1"
    }
  }
}

Izquierda: Vista predeterminada que muestra todos los métodos disponibles en Chile (transferencia bancaria y tarjetas) cuando no se establece el parámetro `payment_method_types`. Centro: Flujo `bank_transfer` preseleccionado para Banco Estado, mostrando directamente el formulario de pago específico de la institución. Derecha: Flujo `card` preseleccionado.

Uso de tu propia página de CheckoutCuando tienes tu propia página de checkout, debes establecer payment_method_types para redirigir a los clientes al checkout alojado por Fintoc después de que ya hayan seleccionado su método de pago preferido.Esto omite la pantalla de selección de método de pago de Fintoc y dirige a los clientes directamente al flujo de pago específico, en lugar de dejar que Fintoc gestione la experiencia de checkout completa.

Respuesta al crear una Checkout Session

Después de hacer la solicitud para crear la Checkout Session, Fintoc responde con el objeto de la sesión:

{
  "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/cancel",
  "redirect_url": "https://pay.fintoc.com/checkout/cs_li5531onlFDi235",
  "metadata": {},
  "customer": {
    "id": "cus_3B2bODrQFje7ZVkT69xyaTSDwXQ",
    "object": "customer",
    "name": "Felipe Castro",
    "email": "jon@snow.com",
    "metadata": {},
    "tax_id": {
      "type": "cl_rut",
      "value": "11.111.111-1"
    }
  }
}

La respuesta incluye el atributo redirect_url. En el siguiente paso, usarás este atributo para redirigir al cliente a completar el pago.

Redirige al cliente para completar el pago

A continuación, redirige a los clientes a la página de checkout alojada por Fintoc. Después de que completen el pago, Fintoc los redirige automáticamente de vuelta a tu sitio: al success_url después de un pago exitoso, o al cancel_url si cancelan. Cliente

window.location.assign(REDIRECT_URL_FROM_YOUR_BACKEND);

Maneja los eventos posteriores al pago

Una vez que un Checkout Session finaliza, manejas el resultado del pago en tu frontend y completas el pago en tu backend. En tu backend, usa los eventos que Fintoc envía a través de 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. Sigue la guía de webhooks 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:

{
  "id": "evt_a4xK32BanKWYn",
  "object": "event",
  "type": "checkout_session.finished",
  "data": {
    "id": "cs_li5531onlFDi235",
    "mode": "test",
    "amount": 350000,
    "object": "checkout_session",
    "status": "finished",
    "flow": "payment",
    "currency": "CLP",
    "metadata": {},
    "cancel_url": "https://merchant.com/cancel",
    "created_at": "2026-01-13T18:48:25Z",
    "expires_at": "2026-01-14T18:48:25Z",
    "success_url": "https://merchant.com/success",
    "redirect_url": "https://pay.fintoc.com/checkout/cs_li5531onlFDi235",
    "session_token": null,
    "customer_email": null,
    "customer": {
      "id": "cus_3B2bODrQFje7ZVkT69xyaTSDwXQ",
      "object": "customer",
      "name": "Felipe Castro",
      "email": "jon@snow.com",
      "metadata": {},
      "tax_id": {
        "type": "cl_rut",
        "value": "11.111.111-1"
      }
    },
    "payment_method_types": [
      "bank_transfer"
    ],
    "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": "11.111.111-1",
          "institution_id": "cl_banco_falabella"
        },
        "business_profile": {},
        "transaction_date": null,
        "recipient_account": null,
        "payment_type_options": {}
      }
    },
    "payment_method_options": {}
  }
}

Fintoc emite estos eventos a lo largo del ciclo de vida del pago, incluyendo las rutas de falla y pendiente. Maneja cada uno:

Evento	Descripción	Acción
`checkout_session.finished`	Enviado cuando un `Checkout Session` alcanza un estado final. El pago asociado puede aún estar pendiente, por ejemplo `requires_action`.	Completa la orden según el estado del pago.
`checkout_session.expired`	Enviado cuando un `Checkout Session` expira.	Ofrece al cliente otro intento de pago.
`payment_intent.succeeded`	Enviado cuando el pago relacionado a un `Checkout Session` es exitoso.	Confirma la orden del cliente.
`payment_intent.failed`	Enviado cuando el pago relacionado a un `Checkout Session` falla.	Ofrece al cliente otro intento de pago.
`payment_intent.requires_action`	Enviado cuando el pago relacionado a un `Checkout Session` necesita una acción del cliente. Recibes este evento cuando un pago `bank_transfer` desde una cuenta empresarial requiere aprobación de más de un representante.	Informa a tu cliente de la acción necesaria para aprobar el pago, según el campo `next_action` en el evento del webhook.

Manejo de pagos asíncronos después de que termina el Checkout SessionEn algunos casos, el 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 aprobación de más de un representante.En estos casos, cuando recibas el evento payment_intent.requires_action, informa al cliente que el pago está pendiente de aprobación. Una vez que recibas el evento payment_intent.succeeded o payment_intent.failed, debes notificar al cliente del estado final del pago tan pronto como se confirme.

Prueba tu integración

Usando tu Secret Key de modo de prueba, puedes crear pagos que simulan resultados exitosos y fallidos sin mover dinero. Esto te permite validar tu flujo de pago completo 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 pago
Los webhooks para eventos posteriores al pago

Una sesión de prueba exitosa alcanza el status finished y dispara los webhooks checkout_session.finished y payment_intent.succeeded; una fallida dispara payment_intent.failed. Para disparar escenarios específicos, usa las credenciales de prueba y valores especiales de prueba descritos en nuestra guía de pruebas.

Inicio

Recursos

Pagos

Transferencias

Movimientos

Aceptar un pago

Opcional: instala el SDK del backend

Crea una sesión

Business profile (opcional)

Incluir datos del cliente (opcional)

Incluir una lista de ítems (opcional)

El objeto `price_data`

El objeto `product_data`

Preseleccionar un método de pago (opcional)

Respuesta al crear una Checkout Session

Redirige al cliente para completar el pago

Maneja los eventos posteriores al pago

Completa el pago en tu backend

Prueba tu integración

​Opcional: instala el SDK del backend

​Crea una sesión

​Business profile (opcional)

​Incluir datos del cliente (opcional)

​Incluir una lista de ítems (opcional)

​El objeto price_data

​El objeto product_data

​Preseleccionar un método de pago (opcional)

​Respuesta al crear una Checkout Session

​Redirige al cliente para completar el pago

​Maneja los eventos posteriores al pago

​Completa el pago en tu backend

​Prueba tu integración

Opcional: instala el SDK del backend

Crea una sesión

Business profile (opcional)

Incluir datos del cliente (opcional)

Incluir una lista de ítems (opcional)

El objeto `price_data`

El objeto `product_data`

Preseleccionar un método de pago (opcional)

Respuesta al crear una Checkout Session

Redirige al cliente para completar el pago

Maneja los eventos posteriores al pago

Completa el pago en tu backend

Prueba tu integración