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

# Configure split on recurring payments

> Declare a split rule on a subscription or invoice and distribute each recurring charge between Entity recipients.

Split a recurring charge between recipients. You declare the rule once, and Fintoc resolves it on every cycle against the amount charged.

A subscription issues one invoice per billing cycle, and each invoice creates a `PaymentIntent` when Fintoc charges it. The split rule and the applied split are different: the rule declares how to distribute charges, and the applied split resolves that rule against one charge. The rule lives on the object that declared it. The result lives on the `PaymentIntent`. On a one-off payment, the result also stays on the Checkout Session.

If you haven't integrated split payments yet, start with [Accept split payments](https://docs.fintoc.com/guides/payments/accept-a-payment/accept-split-payments.md). The `split` object is the same one you send on a one-off Checkout Session.

> [!NOTE]
>
> The v2 `Subscription` and `Invoice` endpoints require API version `2026-02-01` or later. See [API version](https://docs.fintoc.com/api/fintoc-api/authentication.md#api-version).

## Where you can declare the rule

Declare a split rule at any of these entry points:

| Entry point | What it splits |
| - | - |
| `POST /v2/checkout_sessions` with `flow: payment` | The one-off payment of that session. |
| `POST /v2/checkout_sessions` with `flow: subscription` | Every charge of the subscription the session creates. Fintoc hands the rule over to the subscription when the session completes. |
| `POST /v2/subscriptions` | Every charge of that subscription, starting with the first invoice. |
| `POST /v2/invoices` | The charge of that standalone invoice only. |
| `PATCH /v2/invoices/{id}` | The charge of an existing invoice in `draft`, including a subscription invoice. You can also send `split` alongside `add_lines` or `remove_lines`. |

## The split object

Each `split` entry identifies a recipient and its share:

| Parameter | Type | Required | Example | Description |
| - | - | - | - | - |
| `split` | `array` | No | `[{...}]` | Rules that divide each charge between recipients. Between 1 and 10 entries. Omit it and the full charge goes to you. |
| `split[].entity_id` | `string` | Yes | `ent_6Qd3kZvNxL8r` | The Entity that receives this portion. Fintoc validates the Entity when you declare the rule, as on a one-off Checkout Session. Fintoc checks eligibility again at charge time, and a later change doesn't invalidate the rule. |
| `split[].type` | `string` | Yes | `percentage` | Either `percentage` or `flat`. Every entry must use the same type. A subscription priced in Unidad de Fomento (UF), with currency `CLF`, only accepts `percentage`. |
| `split[].amount` | `integer` | Yes | `8500` | For `percentage`, basis points. For `flat`, the amount in the currency's smallest unit. Must be greater than `0`. |
| `split[].charge_processing_fee` | `boolean` | With automatic fee deduction, `true` on at least one entry; without it, never `true` | `true` | Whether this recipient pays part of the payment processing fee. Defaults to `false`. |
| `split[].metadata` | `object` | No | `{"unit": "A-401"}` | Key-value pairs you attach to this entry. |

> [!NOTE]
>
> Percentages use basis points: `10000` is 100%, `8500` is 85%, and `50` is 0.5%. A percentage rule must add up to exactly `10000`.

> [!NOTE]
>
> A rule must always add up to the amount charged. Percentage rules adapt to changes in the charge amount. With `flat`, you keep the rule in sync: update the subscription rule when you change its price. Update an invoice's rule with `PATCH`, or send `split` alongside `add_lines` or `remove_lines` when you edit the invoice. UF subscription amounts change every cycle without a price update, so UF subscriptions don't accept `flat` rules.

### Who pays the processing fee

Who pays depends on whether [automatic fee deduction](https://docs.fintoc.com/guides/payments/fintoc-fees.md#how-you’re-billed) is active for your organization:

* **With automatic fee deduction:** Every entry that sets `charge_processing_fee` to `true` pays the processing fee in proportion to its share of the charge among those entries. Entries that send `false` or leave the field out don't pay the fee. At least one entry must set `charge_processing_fee` to `true`. Otherwise, Fintoc rejects the split rule with the `MISSING_CHARGE_PROCESSING_FEE` error.
* **Without automatic fee deduction:** No entry can set `charge_processing_fee` to `true`. Otherwise, Fintoc rejects the split rule with the `CHARGE_PROCESSING_FEE_NOT_ALLOWED` error. Your organization pays the processing fee, billed on your end-of-period invoice.

Fintoc checks this when you declare the rule, not when it charges an invoice. The examples on this page set `charge_processing_fee` to `true` on one entry, as an organization with automatic fee deduction does.

Fintoc rounds each recipient's share of the amount and of the fee down to the currency's smallest unit. The rounding remainder of both goes to the first entry that pays the fee. When no entry pays the fee, the remainder of the amount goes to the first entry.

> [!NOTE]
>
> If you already integrated split on one-off payments, `charge_processing_fee` used to be `true` on exactly one entry. Now more than one entry can set it to `true`. The `MULTIPLE_CHARGE_PROCESSING_FEE` error no longer exists.

## Create a subscription with a split rule

The examples bill the monthly rent of a unit and split it three ways: 85% to the owner, 10% to the brokerage, and 5% to your platform. Each recipient is an Entity of your organization. The owner pays the processing fee, so only its entry sets `charge_processing_fee` to `true`.

**Server**

```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
}
```

The subscription starts `incomplete` and becomes `active` once the first payment succeeds. Its `split` contains the rule with defaults filled in, regardless of charge status. Read the `PaymentIntent` for resolved amounts.

## Create a subscription Checkout Session with a split rule

Use this flow when your customer still needs to authorize the payment method. Send `split` alongside `flow: subscription`. Fintoc hands the rule over to the subscription the session creates.

**Server**

```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 validates the rule when you create the session, not when your customer completes it. If an Entity doesn't exist or doesn't belong to you, the request fails instead of creating a broken subscription. Fintoc checks again at charge time whether a recipient is operational.

## Update the rule on a subscription

Send `split` on `PATCH /v2/subscriptions/{id}` to replace the rule. The new rule applies to invoices issued from then on. Existing invoices keep their inherited rule, even while in `draft`. Fintoc replaces the whole rule rather than merging entries, so send every entry you want to keep.

**Server**

```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
}
```

This response assumes the first payment has not yet succeeded. Updating the rule does not change the subscription's status.

> [!NOTE]
>
> If your rule uses `flat`, update the rule whenever you change a subscription item's price. If the rule no longer adds up to the items' total, the subscription reports `status: "inconsistent"` with `reason: "split_amount_mismatch"`. Fintoc can't finalize the next invoice until the rule adds up again. See [Split mismatches at finalization](#split-mismatches-at-finalization).

### Override the rule for one cycle

Each invoice copies its subscription's rule at creation, rather than holding a live reference. This behavior has three consequences:

* Changing the subscription rule affects future invoices, not existing ones.
* A rule declared on an invoice replaces the inherited rule for that cycle only.
* An invoice without a declared or inherited rule charges without a split, with 100% going to you.

Each entry of an invoice's `split` reports where its rule came from in the `inherited` field. The field is `true` when the invoice copied the rule from its subscription. The field is `false` when you declared the rule on the invoice, either on a standalone invoice or as an override for one cycle.

To override one subscription cycle, edit its invoice while it is in `draft`. From the second cycle on, Fintoc creates each invoice in `draft` and finalizes it 1 hour later. The first invoice skips the `draft` window, so you can't override it this way. See [Invoices in the subscription flow](https://docs.fintoc.com/guides/payments/accept-recurring-payments/manage-invoices.md#invoices-in-the-subscription-flow). The override doesn't change the subscription's rule or any other cycle.

`PATCH /v2/invoices/{id}` replaces the whole rule, which must add up to the invoice's current total. If you also change the amount, send `split` alongside `add_lines` or `remove_lines`. The amount and rule change in the same request, keeping the invoice balanced.

This example adds a `30000` common-expenses line to November's invoice. For this cycle only, the owner receives `430000`, the brokerage receives nothing, and your platform keeps `50000`. The `flat` amounts add up to the new total of `480000`.

**Server**

```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
}
```

## Create an invoice with a split rule

To charge a standalone invoice with its own rule, send `split` on `POST /v2/invoices`. A standalone invoice is independent of your subscriptions and doesn't change their rules.

Fintoc's Node and Python libraries don't create invoices. Call the [Create an invoice](https://docs.fintoc.com/api/payments-api/invoices/invoices-create.md) endpoint over HTTP, as in this `curl` example.

**Server**

```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
}
```

This standalone invoice stays `draft` until you [finalize it](https://docs.fintoc.com/api/payments-api/invoices/invoices-finalize.md). Finalization moves it to `open` and starts the charge against `default_payment_method`.

## Read the applied split

When Fintoc charges the invoice, Fintoc creates a `PaymentIntent` and resolves the rule against its amount. The result is `split_applied`, the same object you receive on one-off payments. One-off payments continue reporting the result as before.

**Webhook payload**

This example shows the first subscription invoice, which inherited the original percentage rule, not the standalone invoice above.

```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
  }
}
```

Handle these events to track charges and their splits:

| Event | Description | Action |
| - | - | - |
| `invoice.payment_succeeded` | Fintoc charged the invoice and resolved the split. | Credit each recipient in your books using `split_applied`. Skip [redirected portions](#when-a-recipient-is-no-longer-operational), where `redirected` is `true`. |
| `invoice.split_redirected` | Fintoc created a charge attempt for the invoice and credited at least one portion to your organization's root Entity. | Find the entries where `redirected` is `true` and follow up with those recipients, as described in [When a recipient is no longer operational](#when-a-recipient-is-no-longer-operational). |
| `invoice.paid` | The invoice is fully settled. Carries the same `split_applied`. | Close the cycle. |
| `invoice.finalization_failed` | Fintoc couldn't finalize the invoice because its `split` doesn't add up to its `total`. The invoice stays in `draft` and Fintoc doesn't charge it. | Fix the invoice's rule and finalize the invoice, as described in [Split mismatches at finalization](#split-mismatches-at-finalization). |
| `invoice.payment_failed` | A charge attempt failed. | Handle the event as you do for invoices without a split. |
| `payment_intent.succeeded` | The underlying payment settled. | Use this event if you already consume it for one-off payments. It carries the same `split_applied`. |
| `checkout_session.finished` | A Checkout Session reached a final state, in either `flow`. Recurring split doesn't change this event. | Keep handling the event as before. For one-off payments, it still carries `split_applied`. |

The events carry the same `split_applied` because the result lives on the `PaymentIntent`. The `PaymentIntent` is common to every origin: a one-off session, a subscription cycle, or a standalone invoice.

An invoice exposes the split of its latest charge attempt. If a charge fails and you retry, the new attempt resolves its own split against the same amount. Only the attempt that settles moves money.

## When a recipient is no longer operational

An Entity can become ineligible for settlement after you declare the rule. For example, Fintoc can pause the Entity's account during a compliance review. Expect eligibility to change while a subscription charges every month.

**The charge continues.** Fintoc charges the invoice as usual and credits that recipient's portion to your organization's root Entity. The rest of the split stays unchanged, and the payer sees no difference.

Until the Entity becomes operational again, you hold funds that belong to your recipient. Don't credit that recipient in your books for a redirected portion.

Fintoc redirects a portion when, at charge time, the recipient's `capabilities.settlement_recipient.status` isn't `operational` or the Entity no longer exists. This also applies when your customer pays the invoice through a Checkout Session.

Each `split_applied` entry on the invoice and its `PaymentIntent` reports whether Fintoc redirected that portion:

| Field | Type | Description |
| - | - | - |
| `redirected` | `boolean` | If `true`, Fintoc credited the portion to your organization's root Entity instead of `entity_id`. The `calculated_amount` doesn't change. |
| `redirected_to_entity_id` | `string` or `null` | ID of the Entity that received the portion instead of `entity_id`. `null` unless `redirected` is `true`. |
| `redirection_reason` | `string` or `null` | Reason Fintoc redirected the portion: `not_operational` when the Entity hasn't completed its onboarding or is paused, and `not_found` when the Entity no longer exists. `null` unless `redirected` is `true`. |

Read these fields in the `invoice.payment_succeeded` payload. The Dashboard also flags each redirected portion on the invoice and the payment.

To react as soon as Fintoc redirects a portion, subscribe to `invoice.split_redirected`. Fintoc sends this event when it creates a charge attempt for an invoice and at least one `split_applied` entry has `redirected` set to `true`. The event's `data` is the invoice, with the same fields as the other invoice events. Fintoc doesn't send the event for charge attempts without a redirected portion.

## Split mismatches at finalization

Fintoc checks the rule again when it finalizes an invoice. A rule fails that check when its `flat` amounts don't add up to the invoice's `total`, or when a `percentage` entry resolves to an amount of `0`. This can happen when you change the invoice's lines or a subscription item's price without updating a `flat` rule.

While the rule doesn't add up, the API reports the mismatch on both objects:

* A `draft` invoice reports `status: "inconsistent"` with `reason: "split_amount_mismatch"`.
* A subscription whose rule no longer adds up to its items' total reports `status: "inconsistent"` with the same `reason`. The next invoice copies that rule, so Fintoc can't finalize it either.

`reason` is `null` for every other status.

When Fintoc tries to finalize an inconsistent invoice, Fintoc leaves the invoice in `draft`, doesn't charge it, and sends `invoice.finalization_failed`. Fintoc doesn't retry the finalization. If you call [Finalize an invoice](https://docs.fintoc.com/api/payments-api/invoices/invoices-finalize.md) yourself, the request fails with the `SPLIT_AMOUNT_MISMATCH` error.

To recover:

1. Send a rule that adds up to the invoice's `total` with `PATCH /v2/invoices/{id}`. If the subscription caused the mismatch, also update the subscription's rule so the next invoices add up.
2. Finalize the invoice with [Finalize an invoice](https://docs.fintoc.com/api/payments-api/invoices/invoices-finalize.md). Finalization moves the invoice to `open` and starts the charge.

## Errors

Declaring a rule returns the same validation errors as a one-off Checkout Session, listed in [Errors](https://docs.fintoc.com/guides/payments/accept-a-payment/accept-split-payments.md#errors) in Accept split payments. You can also receive these codes:

| Code | When it occurs |
| - | - |
| `SPLIT_AMOUNT_MISMATCH` | The rule doesn't add up to the invoice amount at finalization. Fintoc doesn't finalize or charge the invoice, which stays in `draft`, and sends `invoice.finalization_failed`. See [Split mismatches at finalization](#split-mismatches-at-finalization). |
| `SPLIT_FLAT_NOT_ALLOWED_IN_INDEXED_SUBSCRIPTION` | You declared a `flat` rule on a subscription priced in UF. The amount changes every cycle, so use `percentage`. |
| `SPLIT_NOT_AVAILABLE` | Your organization isn't enabled for split payments. |

These cases produce no split and are not errors:

* An invoice settled outside Fintoc with `external_payment: true`. No `PaymentIntent` exists to split.
* An invoice with a zero amount. Fintoc marks the invoice as paid without creating a `PaymentIntent`.
* A voided invoice. Voiding the invoice also voids its rule.
* A canceled subscription. Existing invoices stay valid and keep their inherited rule.

## Test your integration

Verify successful charges, amount changes, and unbalanced `flat` rules in `test` mode:

1. Using your test Secret Key, create a subscription with a percentage `split` rule and at least two test Entities. To create and onboard them, follow [Create an Entity](https://docs.fintoc.com/guides/payments/accept-a-payment/accept-split-payments.md#step-1-create-an-entity).
2. Wait for the simulated charge of the first invoice, as described in [Test your integration](https://docs.fintoc.com/guides/payments/accept-recurring-payments.md#test-your-integration). Check that `invoice.payment_succeeded` carries `split_applied` and that all `calculated_amount` values add up to the invoice amount.
3. Create a subscription Checkout Session with the same rule and the product name `sandbox_draft`. Fintoc creates its invoice in `draft`, as described in [Test invoice creation with status `draft`](https://docs.fintoc.com/guides/payments/accept-recurring-payments/manage-invoices#test-invoice-creation-with-status-draft). Use [Add lines](https://docs.fintoc.com/api/payments-api/invoices/invoices-add-lines.md) to add a line of `1`, so the total doesn't divide evenly. When Fintoc charges the invoice, check that the percentages resolve against the new total and that the rounding remainder goes to the first entry that pays the fee.
4. Repeat step 3 with another `sandbox_draft` subscription. While its invoice is in `draft`, use `PATCH /v2/invoices/{id}` to replace the invoice's rule with a `flat` rule that adds up to the total. Then add a line without sending `split`. Check that the invoice reports `status: "inconsistent"` with `reason: "split_amount_mismatch"`. When Fintoc tries to finalize the invoice, the invoice stays in `draft` and you receive `invoice.finalization_failed`.
