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

# Configura split en pagos recurrentes

> Declara una regla de split en una suscripción o factura y distribuye cada cobro recurrente entre destinatarios Entity.

Divide un cobro recurrente entre destinatarios. Declara la regla una vez y Fintoc la aplica en cada ciclo al monto cobrado.

Una suscripción emite una factura por ciclo de facturación y cada factura genera un `PaymentIntent` cuando Fintoc la cobra. La regla de split y el split aplicado son distintos: la regla declara cómo distribuir los cobros y el split aplicado calcula esa distribución para un cobro. La regla queda en el objeto que la declara. El resultado queda en el `PaymentIntent`. En un pago único, el resultado también queda en el Checkout Session.

Si aún no integras pagos con split, comienza con [Aceptar pagos con split](https://docs.fintoc.com/es/guides/payments/accept-a-payment/accept-split-payments.md). El objeto `split` es el mismo que envías en un Checkout Session de pago único.

> [!NOTE]
>
> Los endpoints v2 de `Subscription` e `Invoice` requieren la versión de API `2026-02-01` o posterior. Consulta [Versión de la API](https://docs.fintoc.com/es/api/fintoc-api/authentication.md#versión-de-la-api).

## Dónde puedes declarar la regla

Declara una regla de split en cualquiera de estos puntos de entrada:

| Punto de entrada | Qué divide |
| - | - |
| `POST /v2/checkout_sessions` con `flow: payment` | El pago único de esa sesión. |
| `POST /v2/checkout_sessions` con `flow: subscription` | Cada cobro de la suscripción que crea la sesión. Fintoc traspasa la regla a la suscripción cuando la sesión termina. |
| `POST /v2/subscriptions` | Cada cobro de esa suscripción, desde la primera factura. |
| `POST /v2/invoices` | Solo el cobro de esa factura independiente. |
| `PATCH /v2/invoices/{id}` | El cobro de una factura existente en `draft`, incluida una factura de suscripción. También puedes enviar `split` junto con `add_lines` o `remove_lines`. |

## El objeto split

Cada entrada de `split` identifica a un destinatario y su parte:

| Parámetro | Tipo | Requerido | Ejemplo | Descripción |
| - | - | - | - | - |
| `split` | `array` | No | `[{...}]` | Reglas que dividen cada cobro entre destinatarios. Entre 1 y 10 entradas. Si lo omites, recibes el cobro completo. |
| `split[].entity_id` | `string` | Sí | `ent_6Qd3kZvNxL8r` | La Entity que recibe esta parte. Fintoc valida la Entity cuando declaras la regla, igual que en un Checkout Session de pago único. Fintoc vuelve a comprobar la elegibilidad al momento del cobro, y un cambio posterior no invalida la regla. |
| `split[].type` | `string` | Sí | `percentage` | `percentage` o `flat`. Todas las entradas deben usar el mismo tipo. Una suscripción con precio en Unidad de Fomento (UF), con moneda `CLF`, solo acepta `percentage`. |
| `split[].amount` | `integer` | Sí | `8500` | Para `percentage`, puntos base. Para `flat`, el monto en la unidad más pequeña de la moneda. Debe ser mayor que `0`. |
| `split[].charge_processing_fee` | `boolean` | Con descuento automático de comisiones, `true` en al menos una entrada; sin él, nunca `true` | `true` | Indica si este destinatario paga parte de la comisión de procesamiento del pago. El valor predeterminado es `false`. |
| `split[].metadata` | `object` | No | `{"unit": "A-401"}` | Pares clave-valor que adjuntas a esta entrada. |

> [!NOTE]
>
> Los porcentajes usan puntos base: `10000` es 100%, `8500` es 85% y `50` es 0.5%. Una regla de porcentajes debe sumar exactamente `10000`.

> [!NOTE]
>
> Una regla siempre debe sumar el monto cobrado. Las reglas de porcentajes se adaptan a los cambios en el monto del cobro. Con `flat`, mantén la regla sincronizada: actualiza la regla de la suscripción cuando cambies su precio. Actualiza la regla de una factura con `PATCH` o envía `split` junto con `add_lines` o `remove_lines` cuando edites la factura. Los montos de las suscripciones en UF cambian en cada ciclo sin actualizar el precio, por lo que estas suscripciones no aceptan reglas `flat`.

### Quién paga la comisión de procesamiento

Quién paga depende de si tu organización tiene activo el [descuento automático de comisiones](https://docs.fintoc.com/es/guides/payments/fintoc-fees.md#cómo-se-te-factura):

* **Con descuento automático de comisiones:** Cada entrada con `charge_processing_fee` en `true` paga la comisión de procesamiento en proporción a su parte del cobro entre esas entradas. Las entradas que envían `false` u omiten el campo no pagan la comisión. Al menos una entrada debe tener `charge_processing_fee` en `true`. Si no, Fintoc rechaza la regla de split con el error `MISSING_CHARGE_PROCESSING_FEE`.
* **Sin descuento automático de comisiones:** Ninguna entrada puede tener `charge_processing_fee` en `true`. Si no, Fintoc rechaza la regla de split con el error `CHARGE_PROCESSING_FEE_NOT_ALLOWED`. Tu organización paga la comisión de procesamiento, que Fintoc cobra en tu factura de fin de período.

Fintoc revisa esto cuando declaras la regla, no cuando cobra una factura. Los ejemplos de esta página tienen `charge_processing_fee` en `true` en una entrada, como lo hace una organización con descuento automático de comisiones.

Fintoc redondea hacia abajo, a la unidad más pequeña de la moneda, la parte del monto y de la comisión de cada destinatario. El residuo de ambos va a la primera entrada que paga la comisión. Cuando ninguna entrada paga la comisión, el residuo del monto va a la primera entrada.

> [!NOTE]
>
> Si ya integras split en pagos únicos, antes `charge_processing_fee` debía estar en `true` en exactamente una entrada. Ahora más de una entrada puede tenerlo en `true`. El error `MULTIPLE_CHARGE_PROCESSING_FEE` ya no existe.

## Crea una suscripción con una regla de split

Los ejemplos cobran el arriendo mensual de una unidad y lo dividen en tres partes: 85% para el propietario, 10% para la corredora y 5% para tu plataforma. Cada destinatario es una Entity de tu organización. El propietario paga la comisión de procesamiento, así que solo su entrada tiene `charge_processing_fee` en `true`.

**Servidor**

```bash curl theme={null}
curl --request POST "https://api.fintoc.com/v2/subscriptions" \
  --header "Authorization: YOUR_TEST_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "customer": "cus_3Tn7vQxJ2mBd",
    "collection_method": "charge_automatically",
    "payment_method": "pm_5Kw9rYhN8cFz",
    "items": [
      {
        "quantity": 1,
        "price_data": {
          "currency": "CLP",
          "unit_amount": 450000,
          "recurring": { "interval": "month", "interval_count": 1 },
          "product_data": { "name": "Arriendo unidad A-401" }
        }
      }
    ],
    "split": [
      { "entity_id": "ent_6Qd3kZvNxL8r", "type": "percentage", "amount": 8500, "charge_processing_fee": true },
      { "entity_id": "ent_1Ys8cRpMvD2w", "type": "percentage", "amount": 1000 },
      { "entity_id": "ent_4Pq7sLwXy2Nc", "type": "percentage", "amount": 500 }
    ]
  }'
```

```javascript Node theme={null}
const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_TEST_SECRET_API_KEY');

const subscription = await fintoc.v2.subscriptions.create({
  customer: 'cus_3Tn7vQxJ2mBd',
  collection_method: 'charge_automatically',
  payment_method: 'pm_5Kw9rYhN8cFz',
  items: [
    {
      quantity: 1,
      price_data: {
        currency: 'CLP',
        unit_amount: 450000,
        recurring: { interval: 'month', interval_count: 1 },
        product_data: { name: 'Arriendo unidad A-401' }
      }
    }
  ],
  split: [
    { entity_id: 'ent_6Qd3kZvNxL8r', type: 'percentage', amount: 8500, charge_processing_fee: true },
    { entity_id: 'ent_1Ys8cRpMvD2w', type: 'percentage', amount: 1000 },
    { entity_id: 'ent_4Pq7sLwXy2Nc', type: 'percentage', amount: 500 }
  ]
});
```

```python Python theme={null}
from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_API_KEY')

subscription = client.v2.subscriptions.create(
    customer='cus_3Tn7vQxJ2mBd',
    collection_method='charge_automatically',
    payment_method='pm_5Kw9rYhN8cFz',
    items=[
        {
            'quantity': 1,
            'price_data': {
                'currency': 'CLP',
                'unit_amount': 450000,
                'recurring': { 'interval': 'month', 'interval_count': 1 },
                'product_data': { 'name': 'Arriendo unidad A-401' }
            }
        }
    ],
    split=[
        { 'entity_id': 'ent_6Qd3kZvNxL8r', 'type': 'percentage', 'amount': 8500, 'charge_processing_fee': True },
        { 'entity_id': 'ent_1Ys8cRpMvD2w', 'type': 'percentage', 'amount': 1000 },
        { 'entity_id': 'ent_4Pq7sLwXy2Nc', 'type': 'percentage', 'amount': 500 }
    ]
)
```

```json theme={null}
{
  "id": "sub_4Nf2jHtQ7bXe",
  "object": "subscription",
  "billing_cycle_anchor": "2026-10-01T00:00:00Z",
  "cancel_at": null,
  "collection_method": "charge_automatically",
  "created_at": "2026-10-01T00:00:00Z",
  "customer": "cus_3Tn7vQxJ2mBd",
  "items": [
    {
      "id": "si_9Bk2mVqL6rTs",
      "object": "subscription_item",
      "price": {
        "currency": "CLP",
        "product": {
          "id": "prod_2Hx8nWcK5pJv",
          "object": "product",
          "created_at": "2026-10-01T00:00:00Z",
          "description": null,
          "image_url": null,
          "metadata": {},
          "mode": "test",
          "name": "Arriendo unidad A-401"
        },
        "recurring": { "interval": "month", "interval_count": 1 },
        "unit_amount": 450000
      },
      "quantity": 1
    }
  ],
  "metadata": {},
  "mode": "test",
  "payment_method": "pm_5Kw9rYhN8cFz",
  "split": [
    { "entity_id": "ent_6Qd3kZvNxL8r", "type": "percentage", "amount": 8500, "charge_processing_fee": true, "metadata": {} },
    { "entity_id": "ent_1Ys8cRpMvD2w", "type": "percentage", "amount": 1000, "charge_processing_fee": false, "metadata": {} },
    { "entity_id": "ent_4Pq7sLwXy2Nc", "type": "percentage", "amount": 500, "charge_processing_fee": false, "metadata": {} }
  ],
  "status": "incomplete",
  "trial_end": null
}
```

La suscripción comienza en `incomplete` y pasa a `active` cuando el primer pago tiene éxito. Su `split` contiene la regla con los valores predeterminados completos, sin importar el estado del cobro. Consulta el `PaymentIntent` para obtener los montos calculados.

## Crea un Checkout Session de suscripción con una regla de split

Usa este flujo cuando tu cliente aún necesita autorizar el medio de pago. Envía `split` junto con `flow: subscription`. Fintoc traspasa la regla a la suscripción que crea la sesión.

**Servidor**

```bash 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",
    "currency": "CLP",
    "payment_method_types": ["pac", "card"],
    "success_url": "https://yourapp.com/success",
    "cancel_url": "https://yourapp.com/cancel",
    "customer_data": {
      "email": "test.customer@example.com",
      "name": "Test Customer 1"
    },
    "line_items": [
      {
        "quantity": 1,
        "price_data": {
          "currency": "CLP",
          "unit_amount": 450000,
          "recurring": { "interval": "month", "interval_count": 1 },
          "product_data": { "name": "Arriendo unidad A-401" }
        }
      }
    ],
    "split": [
      { "entity_id": "ent_6Qd3kZvNxL8r", "type": "percentage", "amount": 8500, "charge_processing_fee": true },
      { "entity_id": "ent_1Ys8cRpMvD2w", "type": "percentage", "amount": 1000 },
      { "entity_id": "ent_4Pq7sLwXy2Nc", "type": "percentage", "amount": 500 }
    ]
  }'
```

```javascript Node theme={null}
const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_TEST_SECRET_API_KEY');

const checkoutSession = await fintoc.v2.checkoutSessions.create({
  flow: 'subscription',
  currency: 'CLP',
  payment_method_types: ['pac', 'card'],
  success_url: 'https://yourapp.com/success',
  cancel_url: 'https://yourapp.com/cancel',
  customer_data: {
    email: 'test.customer@example.com',
    name: 'Test Customer 1'
  },
  line_items: [
    {
      quantity: 1,
      price_data: {
        currency: 'CLP',
        unit_amount: 450000,
        recurring: { interval: 'month', interval_count: 1 },
        product_data: { name: 'Arriendo unidad A-401' }
      }
    }
  ],
  split: [
    { entity_id: 'ent_6Qd3kZvNxL8r', type: 'percentage', amount: 8500, charge_processing_fee: true },
    { entity_id: 'ent_1Ys8cRpMvD2w', type: 'percentage', amount: 1000 },
    { entity_id: 'ent_4Pq7sLwXy2Nc', type: 'percentage', amount: 500 }
  ]
});
```

```python Python theme={null}
from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_API_KEY')

checkout_session = client.v2.checkout_sessions.create(
    flow='subscription',
    currency='CLP',
    payment_method_types=['pac', 'card'],
    success_url='https://yourapp.com/success',
    cancel_url='https://yourapp.com/cancel',
    customer_data={
        'email': 'test.customer@example.com',
        'name': 'Test Customer 1'
    },
    line_items=[
        {
            'quantity': 1,
            'price_data': {
                'currency': 'CLP',
                'unit_amount': 450000,
                'recurring': { 'interval': 'month', 'interval_count': 1 },
                'product_data': { 'name': 'Arriendo unidad A-401' }
            }
        }
    ],
    split=[
        { 'entity_id': 'ent_6Qd3kZvNxL8r', 'type': 'percentage', 'amount': 8500, 'charge_processing_fee': True },
        { 'entity_id': 'ent_1Ys8cRpMvD2w', 'type': 'percentage', 'amount': 1000 },
        { 'entity_id': 'ent_4Pq7sLwXy2Nc', 'type': 'percentage', 'amount': 500 }
    ]
)
```

```json theme={null}
{
  "id": "cs_7Rk4mBdW9pLv",
  "object": "checkout_session",
  "amount": null,
  "billing_cycle_anchor": null,
  "business_profile": null,
  "cancel_url": "https://yourapp.com/cancel",
  "created_at": "2026-10-01T00:00:00Z",
  "currency": "CLP",
  "customer": {
    "id": "cus_3Tn7vQxJ2mBd",
    "object": "customer",
    "address": null,
    "created_at": "2026-10-01T00:00:00Z",
    "email": "test.customer@example.com",
    "metadata": {},
    "mode": "test",
    "name": "Test Customer 1",
    "phone": null,
    "tax_id": null
  },
  "customer_email": "test.customer@example.com",
  "customer_phone": null,
  "expires_at": "2026-10-02T00:00:00Z",
  "flow": "subscription",
  "line_items": [
    {
      "price": {
        "currency": "CLP",
        "product": { "description": null, "image_url": null, "metadata": {}, "name": "Arriendo unidad A-401" },
        "recurring": { "interval": "month", "interval_count": 1 },
        "unit_amount": 450000
      },
      "quantity": 1
    }
  ],
  "metadata": {},
  "mode": "test",
  "payment_method": null,
  "payment_method_options": {},
  "payment_method_types": ["pac", "card"],
  "payment_resource": null,
  "redirect_url": "https://pay.fintoc.com/checkout/cs_7Rk4mBdW9pLv",
  "save_payment_method": null,
  "session_token": null,
  "setup_intent": null,
  "split": [
    { "entity_id": "ent_6Qd3kZvNxL8r", "type": "percentage", "amount": 8500, "charge_processing_fee": true, "metadata": {} },
    { "entity_id": "ent_1Ys8cRpMvD2w", "type": "percentage", "amount": 1000, "charge_processing_fee": false, "metadata": {} },
    { "entity_id": "ent_4Pq7sLwXy2Nc", "type": "percentage", "amount": 500, "charge_processing_fee": false, "metadata": {} }
  ],
  "status": "created",
  "split_applied": null,
  "subscription": null,
  "success_url": "https://yourapp.com/success",
  "trial_end": null
}
```

Fintoc valida la regla cuando creas la sesión, no cuando tu cliente la completa. Si una Entity no existe o no te pertenece, la solicitud falla en vez de crear una suscripción inválida. Fintoc vuelve a comprobar si el destinatario está operativo al momento del cobro.

## Actualiza la regla de una suscripción

Envía `split` en `PATCH /v2/subscriptions/{id}` para reemplazar la regla. La nueva regla aplica a las facturas que la suscripción emite desde ese momento. Las facturas existentes conservan la regla heredada, incluso mientras están en `draft`. Fintoc reemplaza la regla completa en vez de combinar las entradas, así que envía todas las entradas que quieras conservar.

**Servidor**

```bash curl theme={null}
curl --request PATCH "https://api.fintoc.com/v2/subscriptions/sub_4Nf2jHtQ7bXe" \
  --header "Authorization: YOUR_TEST_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "split": [
      { "entity_id": "ent_6Qd3kZvNxL8r", "type": "percentage", "amount": 8000, "charge_processing_fee": true },
      { "entity_id": "ent_1Ys8cRpMvD2w", "type": "percentage", "amount": 1500 },
      { "entity_id": "ent_4Pq7sLwXy2Nc", "type": "percentage", "amount": 500 }
    ]
  }'
```

```javascript Node theme={null}
const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_TEST_SECRET_API_KEY');

const subscription = await fintoc.v2.subscriptions.update('sub_4Nf2jHtQ7bXe', {
  split: [
    { entity_id: 'ent_6Qd3kZvNxL8r', type: 'percentage', amount: 8000, charge_processing_fee: true },
    { entity_id: 'ent_1Ys8cRpMvD2w', type: 'percentage', amount: 1500 },
    { entity_id: 'ent_4Pq7sLwXy2Nc', type: 'percentage', amount: 500 }
  ]
});
```

```python Python theme={null}
from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_API_KEY')

subscription = client.v2.subscriptions.update(
    'sub_4Nf2jHtQ7bXe',
    split=[
        { 'entity_id': 'ent_6Qd3kZvNxL8r', 'type': 'percentage', 'amount': 8000, 'charge_processing_fee': True },
        { 'entity_id': 'ent_1Ys8cRpMvD2w', 'type': 'percentage', 'amount': 1500 },
        { 'entity_id': 'ent_4Pq7sLwXy2Nc', 'type': 'percentage', 'amount': 500 }
    ]
)
```

```json theme={null}
{
  "id": "sub_4Nf2jHtQ7bXe",
  "object": "subscription",
  "billing_cycle_anchor": "2026-10-01T00:00:00Z",
  "cancel_at": null,
  "collection_method": "charge_automatically",
  "created_at": "2026-10-01T00:00:00Z",
  "customer": "cus_3Tn7vQxJ2mBd",
  "items": [
    {
      "id": "si_9Bk2mVqL6rTs",
      "object": "subscription_item",
      "price": {
        "currency": "CLP",
        "product": {
          "id": "prod_2Hx8nWcK5pJv",
          "object": "product",
          "created_at": "2026-10-01T00:00:00Z",
          "description": null,
          "image_url": null,
          "metadata": {},
          "mode": "test",
          "name": "Arriendo unidad A-401"
        },
        "recurring": { "interval": "month", "interval_count": 1 },
        "unit_amount": 450000
      },
      "quantity": 1
    }
  ],
  "metadata": {},
  "mode": "test",
  "payment_method": "pm_5Kw9rYhN8cFz",
  "split": [
    { "entity_id": "ent_6Qd3kZvNxL8r", "type": "percentage", "amount": 8000, "charge_processing_fee": true, "metadata": {} },
    { "entity_id": "ent_1Ys8cRpMvD2w", "type": "percentage", "amount": 1500, "charge_processing_fee": false, "metadata": {} },
    { "entity_id": "ent_4Pq7sLwXy2Nc", "type": "percentage", "amount": 500, "charge_processing_fee": false, "metadata": {} }
  ],
  "status": "incomplete",
  "trial_end": null
}
```

Esta respuesta supone que el primer pago aún no tiene éxito. Actualizar la regla no cambia el estado de la suscripción.

> [!NOTE]
>
> Si tu regla usa `flat`, actualízala cada vez que cambies el precio de un ítem de la suscripción. Si la regla ya no suma el total de los ítems, la suscripción reporta `status: "inconsistent"` con `reason: "split_amount_mismatch"`. Fintoc no puede finalizar la siguiente factura hasta que la regla vuelva a sumar. Consulta [Descuadres del split al finalizar](#descuadres-del-split-al-finalizar).

### Reemplaza la regla para un ciclo

Cada factura copia la regla de su suscripción al momento de su creación, en vez de mantener una referencia dinámica. Este comportamiento tiene tres consecuencias:

* Cambiar la regla de la suscripción afecta a las facturas futuras, no a las existentes.
* Una regla que declaras en una factura reemplaza la regla heredada solo para ese ciclo.
* Una factura sin regla declarada ni heredada cobra sin split y te asigna el 100%.

Cada entrada del `split` de una factura indica el origen de su regla en el campo `inherited`. El campo es `true` cuando la factura copió la regla de su suscripción. El campo es `false` cuando declaraste la regla en la factura, ya sea en una factura independiente o como reemplazo para un ciclo.

Para reemplazar el split de un ciclo de suscripción, edita su factura mientras está en `draft`. Desde el segundo ciclo, Fintoc crea cada factura en `draft` y la finaliza 1 hora después. La primera factura no pasa por `draft`, así que no puedes reemplazar su regla de esta forma. Consulta [Invoices en el flujo de suscripción](https://docs.fintoc.com/es/guides/payments/accept-recurring-payments/manage-invoices.md#invoices-en-el-flujo-de-suscripción). El reemplazo no cambia la regla de la suscripción ni ningún otro ciclo.

`PATCH /v2/invoices/{id}` reemplaza la regla completa, que debe sumar el total actual de la factura. Si también cambias el monto, envía `split` junto con `add_lines` o `remove_lines`. El monto y la regla cambian en la misma solicitud y mantienen la factura balanceada.

Este ejemplo agrega una línea de gastos comunes de `30000` a la factura de noviembre. Solo para este ciclo, el propietario recibe `430000`, la corredora no recibe nada y tu plataforma conserva `50000`. Los montos `flat` suman el nuevo total de `480000`.

**Servidor**

```bash curl theme={null}
curl --request POST "https://api.fintoc.com/v2/invoices/in_6Hr3kWpN8sVt/add_lines" \
  --header "Authorization: YOUR_TEST_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "lines": [
      { "amount": 30000, "currency": "CLP", "name": "Gastos comunes", "quantity": 1 }
    ],
    "split": [
      { "entity_id": "ent_6Qd3kZvNxL8r", "type": "flat", "amount": 430000, "charge_processing_fee": true },
      { "entity_id": "ent_4Pq7sLwXy2Nc", "type": "flat", "amount": 50000 }
    ]
  }'
```

```javascript Node theme={null}
const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_TEST_SECRET_API_KEY');

const invoice = await fintoc.v2.invoices.addLines('in_6Hr3kWpN8sVt', {
  lines: [
    { amount: 30000, currency: 'CLP', name: 'Gastos comunes', quantity: 1 }
  ],
  split: [
    { entity_id: 'ent_6Qd3kZvNxL8r', type: 'flat', amount: 430000, charge_processing_fee: true },
    { entity_id: 'ent_4Pq7sLwXy2Nc', type: 'flat', amount: 50000 }
  ]
});
```

```python Python theme={null}
from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_API_KEY')

invoice = client.v2.invoices.add_lines(
    'in_6Hr3kWpN8sVt',
    lines=[
        { 'amount': 30000, 'currency': 'CLP', 'name': 'Gastos comunes', 'quantity': 1 }
    ],
    split=[
        { 'entity_id': 'ent_6Qd3kZvNxL8r', 'type': 'flat', 'amount': 430000, 'charge_processing_fee': True },
        { 'entity_id': 'ent_4Pq7sLwXy2Nc', 'type': 'flat', 'amount': 50000 }
    ]
)
```

```json theme={null}
{
  "id": "in_6Hr3kWpN8sVt",
  "object": "invoice",
  "attempt_count": 0,
  "collection_method": "charge_automatically",
  "created_at": "2026-11-01T00:00:00Z",
  "currency": "CLP",
  "customer": "cus_3Tn7vQxJ2mBd",
  "default_payment_method": null,
  "external_payment": false,
  "hosted_invoice_url": null,
  "lines": [
    {
      "id": "il_7Dx4kMsP9qWv",
      "object": "line_item",
      "amount": 450000,
      "currency": "CLP",
      "description": null,
      "name": "Arriendo unidad A-401",
      "period_end": "2026-12-01T00:00:00Z",
      "period_start": "2026-11-01T00:00:00Z",
      "quantity": 1
    },
    {
      "id": "il_3Fa6nYtH8rKx",
      "object": "line_item",
      "amount": 30000,
      "currency": "CLP",
      "description": null,
      "name": "Gastos comunes",
      "period_end": null,
      "period_start": null,
      "quantity": 1
    }
  ],
  "metadata": {},
  "mode": "test",
  "next_payment_attempt_at": null,
  "payments": [],
  "split": [
    { "entity_id": "ent_6Qd3kZvNxL8r", "type": "flat", "amount": 430000, "charge_processing_fee": true, "inherited": false, "metadata": {} },
    { "entity_id": "ent_4Pq7sLwXy2Nc", "type": "flat", "amount": 50000, "charge_processing_fee": false, "inherited": false, "metadata": {} }
  ],
  "status": "draft",
  "subscription": "sub_4Nf2jHtQ7bXe",
  "total": 480000
}
```

## Crea una factura con una regla de split

Para cobrar una factura independiente con su propia regla, envía `split` en `POST /v2/invoices`. Una factura independiente no depende de tus suscripciones ni cambia sus reglas.

Las librerías de Fintoc para Node y Python no crean facturas. Llama al endpoint [Crear una factura](https://docs.fintoc.com/es/api/payments-api/invoices/invoices-create.md) por HTTP, como en este ejemplo con `curl`.

**Servidor**

```bash curl theme={null}
curl --request POST "https://api.fintoc.com/v2/invoices" \
  --header "Authorization: YOUR_TEST_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "customer": "cus_3Tn7vQxJ2mBd",
    "collection_method": "charge_automatically",
    "default_payment_method": "pm_5Kw9rYhN8cFz",
    "lines": [
      { "amount": 450000, "currency": "CLP", "name": "Arriendo unidad A-401", "quantity": 1 }
    ],
    "split": [
      { "entity_id": "ent_6Qd3kZvNxL8r", "type": "flat", "amount": 400000, "charge_processing_fee": true },
      { "entity_id": "ent_4Pq7sLwXy2Nc", "type": "flat", "amount": 50000 }
    ]
  }'
```

```json theme={null}
{
  "id": "in_8Cm3yTrB6wNh",
  "object": "invoice",
  "attempt_count": 0,
  "collection_method": "charge_automatically",
  "created_at": "2026-10-01T00:00:00Z",
  "currency": "CLP",
  "customer": "cus_3Tn7vQxJ2mBd",
  "default_payment_method": "pm_5Kw9rYhN8cFz",
  "external_payment": false,
  "hosted_invoice_url": null,
  "lines": [
    {
      "id": "il_9Wn5sDcV4hLp",
      "object": "line_item",
      "amount": 450000,
      "currency": "CLP",
      "description": null,
      "name": "Arriendo unidad A-401",
      "period_end": null,
      "period_start": null,
      "quantity": 1
    }
  ],
  "metadata": {},
  "mode": "test",
  "next_payment_attempt_at": null,
  "payments": [],
  "split": [
    { "entity_id": "ent_6Qd3kZvNxL8r", "type": "flat", "amount": 400000, "charge_processing_fee": true, "inherited": false, "metadata": {} },
    { "entity_id": "ent_4Pq7sLwXy2Nc", "type": "flat", "amount": 50000, "charge_processing_fee": false, "inherited": false, "metadata": {} }
  ],
  "status": "draft",
  "subscription": null,
  "total": 450000
}
```

Esta factura independiente permanece en `draft` hasta que la [finalices](https://docs.fintoc.com/es/api/payments-api/invoices/invoices-finalize.md). La finalización la mueve a `open` e inicia el cobro con `default_payment_method`.

## Consulta el split aplicado

Cuando Fintoc cobra la factura, crea un `PaymentIntent` y aplica la regla a su monto. El resultado es `split_applied`, el mismo objeto que recibes en los pagos únicos. Los pagos únicos siguen informando el resultado como antes.

**Payload del webhook**

Este ejemplo muestra la primera factura de la suscripción, que heredó la regla de porcentajes original, no la factura independiente anterior.

```json theme={null}
{
  "id": "evt_2Lp8xVnK5tQj",
  "object": "event",
  "type": "invoice.payment_succeeded",
  "data": {
    "id": "in_2Jv6nXsM9cQr",
    "object": "invoice",
    "attempt_count": 1,
    "collection_method": "charge_automatically",
    "created_at": "2026-10-01T00:00:00Z",
    "currency": "CLP",
    "customer": "cus_3Tn7vQxJ2mBd",
    "default_payment_method": null,
    "external_payment": false,
    "hosted_invoice_url": null,
    "lines": [
      {
        "id": "il_5Rt8wKmQ2xHs",
        "object": "line_item",
        "amount": 450000,
        "currency": "CLP",
        "description": null,
        "name": "Arriendo unidad A-401",
        "period_end": "2026-11-01T00:00:00Z",
        "period_start": "2026-10-01T00:00:00Z",
        "quantity": 1
      }
    ],
    "metadata": {},
    "mode": "test",
    "next_payment_attempt_at": null,
    "payments": [
      { "amount": 450000, "currency": "CLP", "payment_intent": "pi_5Vz7qGsL3nRk", "status": "succeeded" }
    ],
    "split": [
      { "entity_id": "ent_6Qd3kZvNxL8r", "type": "percentage", "amount": 8500, "charge_processing_fee": true, "inherited": true, "metadata": {} },
      { "entity_id": "ent_1Ys8cRpMvD2w", "type": "percentage", "amount": 1000, "charge_processing_fee": false, "inherited": true, "metadata": {} },
      { "entity_id": "ent_4Pq7sLwXy2Nc", "type": "percentage", "amount": 500, "charge_processing_fee": false, "inherited": true, "metadata": {} }
    ],
    "split_applied": [
      { "entity_id": "ent_6Qd3kZvNxL8r", "calculated_amount": 382500, "charge_processing_fee": true, "redirected": false, "redirected_to_entity_id": null, "redirection_reason": null },
      { "entity_id": "ent_1Ys8cRpMvD2w", "calculated_amount": 45000, "charge_processing_fee": false, "redirected": false, "redirected_to_entity_id": null, "redirection_reason": null },
      { "entity_id": "ent_4Pq7sLwXy2Nc", "calculated_amount": 22500, "charge_processing_fee": false, "redirected": false, "redirected_to_entity_id": null, "redirection_reason": null }
    ],
    "status": "paid",
    "subscription": "sub_4Nf2jHtQ7bXe",
    "total": 450000
  }
}
```

Maneja estos eventos para seguir los cobros y sus splits:

| Evento | Descripción | Acción |
| - | - | - |
| `invoice.payment_succeeded` | Fintoc cobra la factura y calcula el split. | Abona la parte de cada destinatario en tu contabilidad usando `split_applied`. Omite las [partes redirigidas](#cuando-un-destinatario-ya-no-está-operativo), en las que `redirected` es `true`. |
| `invoice.split_redirected` | Fintoc crea un intento de cobro de la factura y abona al menos una parte a la Entity raíz de tu organización. | Busca las entradas en las que `redirected` es `true` y haz seguimiento con esos destinatarios, como se describe en [Cuando un destinatario ya no está operativo](#cuando-un-destinatario-ya-no-está-operativo). |
| `invoice.paid` | La factura queda completamente liquidada. Incluye el mismo `split_applied`. | Cierra el ciclo. |
| `invoice.finalization_failed` | Fintoc no pudo finalizar la factura porque su `split` no suma su `total`. La factura queda en `draft` y Fintoc no la cobra. | Corrige la regla de la factura y finalízala, como se describe en [Descuadres del split al finalizar](#descuadres-del-split-al-finalizar). |
| `invoice.payment_failed` | Un intento de cobro falla. | Maneja el evento igual que en las facturas sin split. |
| `payment_intent.succeeded` | El pago subyacente queda liquidado. | Usa este evento si ya lo consumes para pagos únicos. Incluye el mismo `split_applied`. |
| `checkout_session.finished` | Un Checkout Session llega a un estado final, en cualquier `flow`. El split recurrente no cambia este evento. | Sigue manejando el evento como antes. En pagos únicos, aún incluye `split_applied`. |

Los eventos incluyen el mismo `split_applied` porque el resultado queda en el `PaymentIntent`. El `PaymentIntent` es común a todos los orígenes: una sesión de pago único, un ciclo de suscripción o una factura independiente.

Una factura expone el split de su último intento de cobro. Si un cobro falla y reintentas, el nuevo intento calcula su propio split sobre el mismo monto. Solo el intento que se liquida mueve dinero.

## Cuando un destinatario ya no está operativo

Una Entity puede dejar de ser elegible para recibir liquidaciones después de que declares la regla. Por ejemplo, Fintoc puede pausar la cuenta de la Entity durante una revisión de cumplimiento. Considera que la elegibilidad puede cambiar mientras una suscripción cobra cada mes.

**El cobro continúa.** Fintoc cobra la factura como siempre y abona la parte de ese destinatario a la Entity raíz de tu organización. El resto del split no cambia y el pagador no ve ninguna diferencia.

Hasta que la Entity vuelva a estar operativa, mantienes fondos que corresponden a tu destinatario. No abones a ese destinatario en tu contabilidad una parte redirigida.

Fintoc redirige una parte cuando, al momento del cobro, el `capabilities.settlement_recipient.status` del destinatario no es `operational` o la Entity ya no existe. Esto también aplica cuando tu cliente paga la factura con una Checkout Session.

Cada entrada de `split_applied` en la factura y en su `PaymentIntent` indica si Fintoc redirigió esa parte:

| Campo | Tipo | Descripción |
| - | - | - |
| `redirected` | `boolean` | Si es `true`, Fintoc abonó la parte a la Entity raíz de tu organización en lugar de a `entity_id`. El `calculated_amount` no cambia. |
| `redirected_to_entity_id` | `string` o `null` | ID de la Entity que recibió la parte en lugar de `entity_id`. Es `null` salvo que `redirected` sea `true`. |
| `redirection_reason` | `string` o `null` | Motivo por el que Fintoc redirigió la parte: `not_operational` cuando la Entity no ha completado su onboarding o está pausada, y `not_found` cuando la Entity ya no existe. Es `null` salvo que `redirected` sea `true`. |

Lee estos campos en el payload de `invoice.payment_succeeded`. El Dashboard también marca cada parte redirigida en la factura y el pago.

Para reaccionar apenas Fintoc redirija una parte, suscríbete a `invoice.split_redirected`. Fintoc envía este evento cuando crea un intento de cobro de una factura y al menos una entrada de `split_applied` tiene `redirected` en `true`. El `data` del evento es la factura, con los mismos campos que los demás eventos de facturas. Fintoc no envía el evento en los intentos de cobro sin partes redirigidas.

## Descuadres del split al finalizar

Fintoc vuelve a revisar la regla cuando finaliza una factura. Una regla no pasa esa revisión cuando sus montos `flat` no suman el `total` de la factura, o cuando una entrada `percentage` resulta en un monto de `0`. Esto puede pasar cuando cambias las líneas de la factura o el precio de un ítem de la suscripción sin actualizar una regla `flat`.

Mientras la regla no sume, la API reporta el descuadre en ambos objetos:

* Una factura en `draft` reporta `status: "inconsistent"` con `reason: "split_amount_mismatch"`.
* Una suscripción cuya regla ya no suma el total de sus ítems reporta `status: "inconsistent"` con el mismo `reason`. La siguiente factura copia esa regla, así que Fintoc tampoco puede finalizarla.

`reason` es `null` en todos los demás estados.

Cuando Fintoc intenta finalizar una factura inconsistente, Fintoc deja la factura en `draft`, no la cobra y envía `invoice.finalization_failed`. Fintoc no reintenta la finalización. Si llamas tú a [Finalizar una factura](https://docs.fintoc.com/es/api/payments-api/invoices/invoices-finalize.md), la solicitud falla con el error `SPLIT_AMOUNT_MISMATCH`.

Para recuperarte:

1. Envía una regla que sume el `total` de la factura con `PATCH /v2/invoices/{id}`. Si la suscripción causó el descuadre, actualiza también la regla de la suscripción para que las siguientes facturas sumen.
2. Finaliza la factura con [Finalizar una factura](https://docs.fintoc.com/es/api/payments-api/invoices/invoices-finalize.md). La finalización mueve la factura a `open` e inicia el cobro.

## Errores

Declarar una regla devuelve los mismos errores de validación que un Checkout Session de pago único, listados en [Errores](https://docs.fintoc.com/es/guides/payments/accept-a-payment/accept-split-payments.md#errors) en Aceptar pagos con split. También puedes recibir estos códigos:

| Código | Cuándo aparece |
| - | - |
| `SPLIT_AMOUNT_MISMATCH` | La regla no suma el monto de la factura al finalizarla. Fintoc no finaliza ni cobra la factura, que queda en `draft`, y envía `invoice.finalization_failed`. Consulta [Descuadres del split al finalizar](#descuadres-del-split-al-finalizar). |
| `SPLIT_FLAT_NOT_ALLOWED_IN_INDEXED_SUBSCRIPTION` | Declaraste una regla `flat` en una suscripción con precio en UF. El monto cambia en cada ciclo, así que usa `percentage`. |
| `SPLIT_NOT_AVAILABLE` | Tu organización no tiene pagos con split habilitados. |

Estos casos no generan un split y no son errores:

* Una factura liquidada fuera de Fintoc con `external_payment: true`. No existe un `PaymentIntent` que dividir.
* Una factura con monto cero. Fintoc marca la factura como pagada sin crear un `PaymentIntent`.
* Una factura anulada. Anular la factura también anula su regla.
* Una suscripción cancelada. Las facturas existentes siguen siendo válidas y conservan la regla heredada.

## Prueba tu integración

Verifica cobros exitosos, cambios de monto y reglas `flat` desbalanceadas en modo `test`:

1. Con tu secret key de prueba, crea una suscripción con una regla `split` de porcentajes y al menos dos Entities de prueba. Para crearlas y hacer su onboarding, sigue [Crear una Entity](https://docs.fintoc.com/es/guides/payments/accept-a-payment/accept-split-payments.md#step-1-create-an-entity).
2. Espera el cobro simulado de la primera factura, como se describe en [Prueba tu integración](https://docs.fintoc.com/es/guides/payments/accept-recurring-payments.md#prueba-tu-integración). Comprueba que `invoice.payment_succeeded` incluya `split_applied` y que todos los valores `calculated_amount` sumen el monto de la factura.
3. Crea un Checkout Session de suscripción con la misma regla y el nombre de producto `sandbox_draft`. Fintoc crea su factura en `draft`, como se describe en [Probar la creación de invoice con estado `draft`](https://docs.fintoc.com/es/guides/payments/accept-recurring-payments/manage-invoices#probar-la-creación-de-invoice-con-estado-draft). Usa [Agregar líneas](https://docs.fintoc.com/es/api/payments-api/invoices/invoices-add-lines.md) para agregar una línea de `1`, de modo que el total no se divida en partes exactas. Cuando Fintoc cobre la factura, comprueba que los porcentajes se calculen sobre el nuevo total y que el residuo del redondeo vaya a la primera entrada que paga la comisión.
4. Repite el paso 3 con otra suscripción `sandbox_draft`. Mientras su factura está en `draft`, usa `PATCH /v2/invoices/{id}` para reemplazar la regla de la factura por una regla `flat` que sume el total. Luego agrega una línea sin enviar `split`. Revisa que la factura reporte `status: "inconsistent"` con `reason: "split_amount_mismatch"`. Cuando Fintoc intenta finalizar la factura, la factura queda en `draft` y recibes `invoice.finalization_failed`.
