Skip to main content
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. The split object is the same one you send on a one-off Checkout Session.
The v2 Subscription and Invoice endpoints require API version 2026-02-01 or later. See API version.

Where you can declare the rule

Declare a split rule at any of these entry points:

The split object

Each split entry identifies a recipient and its share:
Percentages use basis points: 10000 is 100%, 8500 is 85%, and 50 is 0.5%. A percentage rule must add up to exactly 10000.
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 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.
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
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
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
This response assumes the first payment has not yet succeeded. Updating the rule does not change the subscription’s status.
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.

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

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 endpoint over HTTP, as in this curl example. Server
curl
This standalone invoice stays draft until you finalize it. 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.
Handle these events to track charges and their splits: 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: 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 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. 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 in Accept split payments. You can also receive these codes: 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.
  2. Wait for the simulated charge of the first invoice, as described in 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. Use Add lines 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.