> ## 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 pagos recurrentes
> >-
Hay tres pasos para aceptar pagos recurrentes usando Fintoc:
1. En tu backend, crea una `Checkout Session` con `flow: subscription`
2. Redirige a tu usuario a completar la inscripción en la página de checkout alojada por Fintoc
3. Maneja los eventos posteriores a la inscripción y los pagos recurrentes (webhooks)
El siguiente diagrama muestra cómo Fintoc interactúa tanto con tu backend como con tu frontend:
# Crea una sesión
El objeto Checkout Session representa tu intención de inscribir un método de pago para cobros recurrentes (PAC) y de crear una subscription con un monto y periodicidad fijos.
Usando tu [Secret Key](/es/v2023-11-15/docs/home/api-keys), crea una `Checkout Session` en tu backend con `flow` definido como `subscription`.
```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 '{
"flow": "subscription",
"amount": 350000,
"currency": "CLP",
"success_url": "https://merchant.com/success",
"cancel_url": "https://merchant.com/987654321",
"payment_method_types": [
"pac"
],
"customer_data": {
"tax_id": {
"type": "cl_rut",
"value": "12088191"
},
"name": "Felipe Castro",
"email": "name@example.com",
"metadata": {}
},
"line_items": [
{
"price_data": {
"currency": "CLP",
"unit_amount": 350000,
"product_data": {
"name": "SoyFocus plan"
},
"recurring": {
"interval": "month",
"interval_count": 1
}
},
"quantity": 1
}
],
"metadata": {
"subscription_external_id": "sub_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 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 que se está usando para los pagos recurrentes. Actualmente Fintoc solo soporta CLP. |
| `flow` | `subscription` | Tipo **requerido** del flujo para la sesión. Los tipos disponibles son `payment`, `setup` y `subscription` |
| `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. |
| `customer` | `cus_alm1321knjl1233` | Id de un cliente ya creado. Uno de `customer` o `customer_data` es **requerido**. |
| `customer_data` | `(object)` | Datos para la creación inline del cliente. Uno de `customer` o `customer_data` es **requerido**. |
| `payment_method_types` | `["pac"]` | Lista opcional de métodos de pago permitidos durante la inscripción. pac representa cobros en una cuenta bancaria. |
| `line_items` | `(array)` | Items **requeridos** de la subscription. |
| `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. |
## Incluir Datos del Cliente (Requerido para subscriptions)
Al crear una `Checkout Session` con `flow: subscription`, debes incluir información del cliente. Puedes hacerlo referenciando un ID de cliente existente (`customer`) o enviando `customer_data` para crear uno inline:
| Atributo | Tipo | Descripción |
| :--------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tax_id` | `object` | Objeto **requerido** 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. |
| `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) |
## Incluir una lista de Items (Requerido para subscriptions)
Al crear una `Checkout Session`, también puedes incluir información sobre los items de la sesión. Esto permite que Fintoc muestre esta información en la página de checkout y muestre solo los métodos de pago disponibles para productos específicos.
| Atributo | Tipo | Descripción |
| :----------- | :-------- | :---------------------------------------------------------------------------------------------------- |
| `quantity` | `integer` | Número **requerido** de unidades de este item que se están comprando. |
| `price_data` | `object` | Datos usados para generar un nuevo precio recurrente inline. Uno de price o price\_data es requerido. |
Cada line\_item necesita uno de price\_data o price.
### Objeto **price\_data**
| Atributo | Tipo | Descripción |
| :------------- | :--------- | :--------------------------------------------------------------------------------------------------------------------- |
| `product_data` | `object` | Datos usados para generar un nuevo objeto Product inline. Uno de product o product\_data es requerido. |
| `currency` | string | Moneda usada para la subscription. Actualmente solo soportamos CLP. |
| `unit_amount` | `integer` | Precio **requerido** por unidad del item, expresado en la unidad más pequeña de la moneda (p. ej., CLP sin decimales). |
| `recurring` | `(object)` | Configuración **requerida** de recurrencia (p. ej. interval: month, interval\_count: 1). |
### Objeto **product\_data**
| Atributo | Tipo | Descripción |
| :------- | :------- | :------------------------------------------------------------------ |
| `name` | `string` | Nombre **requerido** del producto o servicio que se está comprando. |
# 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",
"flow": "subscription",
"customer": {
"name": "Felipe Castro",
"email": "name@example.com",
"metadata": {},
"tax_id": {
"type": "cl_rut",
"value": "12088191"
}
},
"line_items": [
{
"price": {
"product": {
"name": "Plan A",
"description": "Pago recurrente monto fijo"
},
"currency": "CLP",
"unit_amount": 350000,
"recurring": {
"interval": "month",
"interval_count": 1
}
},
"quantity": 1
}
],
"success_url": "https://merchant.example/success",
"cancel_url": "https://merchant.example/cancel",
"redirect_url": "https://pay.fintoc.com/checkout/cs_123"
}
```
En la respuesta, deberías recibir el atributo `url`. En el siguiente paso, usarás este atributo para redirigir al usuario a completar la subscription.
## Redirige al usuario a completar el pago
A continuación, redirigirás a los usuarios a la página de Checkout de Fintoc. Después de completar el pago, serán redirigidos automáticamente a tu sitio.
Según el resultado, el usuario será redirigido a la URL de éxito o cancelación.
# Maneja los eventos posteriores a la sesión
Una vez que una Checkout Session finaliza, manejas el resultado en tu frontend y completas la subscription en tu backend. Para tu backend, usarás los eventos enviados por webhooks.
## Completa la subscription en tu backend
Fintoc envía un evento `checkout_session.finished` cuando la sesión se completa.
En un flujo de subscription, este evento incluye información sobre la sesión y referencias al `subscription` y al `payment_method` creados durante la inscripción.
```json theme={null}
{
"id": "evt_a4xK32BanKWYn",
"object": "event",
"type": "checkout_session.finished",
"data": {
"id": "cs_li5531onlFDi235",
"flow": "subscription",
"customer": {
"name": "Felipe Castro",
"email": "name@example.com",
"metadata": {},
"tax_id": {
"type": "cl_rut",
"value": "12088191"
}
},
"payment_method_types": ["pac"],
"status": "finished",
"payment_status": "succeeded",
"subscription": "sub_NffrFeUfNV2Hib",
"payment_method": "pm_NffrFeUfNV2Hib"
}
}
```
Debes manejar los siguientes eventos posteriores a la sesión:
| Evento | Descripción | Acción |
| :-------------------------- | :------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------- |
| `checkout_session.finished` | Enviado cuando una Checkout Session de subscription alcanza un estado final | Activa la subscription en tu lado según el estado final, y almacena los ids creados (`subscription`, `payment_method`, `customer`). |
| `checkout_session.expired` | Enviado cuando una sesión expira | Ofrece al cliente otro intento de suscribirse. |
| `payment_intent.succeeded` | Enviado cuando un payment intent se completa con éxito, como un cobro en una cuenta bancaria o tarjeta. | Confirma a tu cliente que el cobro de la subscription se realizó con éxito |
| `payment_intent.failed` | Enviado cuando un payment intent falla | Ofrece al cliente otro intento de pago de la subscription. |
# Prueba tu integración (Próximamente)
Para confirmar que tu integración funciona correctamente, puedes simular subscriptions y pagos recurrentes programados sin mover dinero real
## 1) Crea una Checkout Session de subscription usando credenciales de usuarios de prueba
Usando tu Secret Key de API en modo prueba, crea una Checkout Session de `flow: subscription` en tu backend y completa el flujo de inscripción de la subscription en la página alojada por Fintoc usando las siguientes credenciales:
**Credenciales de prueba**
* Usuario (RUT): `41614850-3`
* Contraseña: `jonsnow`
### 2) Maneja pagos programados simulados de la subscription
En modo prueba, una vez que se crea la subscription, Fintoc activará inmediatamente payment intents exitosos y fallidos, permitiéndote probar el manejo de todos los eventos posteriores a la sesión.