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
Eachsplit 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_feetotruepays the processing fee in proportion to its share of the charge among those entries. Entries that sendfalseor leave the field out don’t pay the fee. At least one entry must setcharge_processing_feetotrue. Otherwise, Fintoc rejects the split rule with theMISSING_CHARGE_PROCESSING_FEEerror. - Without automatic fee deduction: No entry can set
charge_processing_feetotrue. Otherwise, Fintoc rejects the split rule with theCHARGE_PROCESSING_FEE_NOT_ALLOWEDerror. Your organization pays the processing fee, billed on your end-of-period invoice.
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 setscharge_processing_fee to true.
Server
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. Sendsplit alongside flow: subscription. Fintoc hands the rule over to the subscription the session creates.
Server
Update the rule on a subscription
Sendsplit 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
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.
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, sendsplit 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
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 aPaymentIntent 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.
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’scapabilities.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 itsflat 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
draftinvoice reportsstatus: "inconsistent"withreason: "split_amount_mismatch". - A subscription whose rule no longer adds up to its items’ total reports
status: "inconsistent"with the samereason. 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:
- Send a rule that adds up to the invoice’s
totalwithPATCH /v2/invoices/{id}. If the subscription caused the mismatch, also update the subscription’s rule so the next invoices add up. - Finalize the invoice with Finalize an invoice. Finalization moves the invoice to
openand 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. NoPaymentIntentexists 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 unbalancedflat rules in test mode:
- Using your test Secret Key, create a subscription with a percentage
splitrule and at least two test Entities. To create and onboard them, follow Create an Entity. - Wait for the simulated charge of the first invoice, as described in Test your integration. Check that
invoice.payment_succeededcarriessplit_appliedand that allcalculated_amountvalues add up to the invoice amount. - Create a subscription Checkout Session with the same rule and the product name
sandbox_draft. Fintoc creates its invoice indraft, as described in Test invoice creation with statusdraft. Use Add lines to add a line of1, 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. - Repeat step 3 with another
sandbox_draftsubscription. While its invoice is indraft, usePATCH /v2/invoices/{id}to replace the invoice’s rule with aflatrule that adds up to the total. Then add a line without sendingsplit. Check that the invoice reportsstatus: "inconsistent"withreason: "split_amount_mismatch". When Fintoc tries to finalize the invoice, the invoice stays indraftand you receiveinvoice.finalization_failed.