Split payment API
The split payment API for platforms
FractionalPay is a split payment API: send one payment, get back every party's share, the balanced ledger entries and the payout date. Rules live in the dashboard or in code, and money stays in your own payment account.
- Percentage and fixed lines, priorities and a remainder party
- Idempotent requests, signed webhooks, test and live keys
- Flat monthly plan, no per-transaction fee from us
POST /v1/splits/simulate
200 OK
curl -X POST https://fractionalpay.com/api/v1/splits/simulate \
-H "Authorization: Bearer fp_test_4eC39H..." \
-H "Idempotency-Key: 42d766c9-order" \
-H "Content-Type: application/json" \
-d '{
"amount": 100000,
"currency": "USD",
"parties": [
{"role": "Provider", "kind": "percent", "value": 70},
{
"role": "Platform",
"kind": "percent",
"value": 15,
"platform": true
},
{"role": "Partner", "kind": "percent", "value": 10},
{"role": "Subcontractor", "kind": "fixed", "value": 5000}
],
"schedule": "weekly"
}'{
"object": "split_simulation",
"amount": 100000,
"currency": "USD",
"refund": 0,
"schedule": "weekly",
"hold": false,
"balanced": true,
"allocations": [
{
"role": "Provider",
"kind": "percent",
"value": 70,
"platform": false,
"remainder": false,
"amount": 70000,
"share_percent": 70,
"held": 0,
"refund_reversal": 0,
"net": 70000,
"available_now": 70000
},
{
"role": "Platform",
"kind": "percent",
"value": 15,
"platform": true,
"remainder": true,
"amount": 15000,
"share_percent": 15,
"held": 0,
"refund_reversal": 0,
"net": 15000,
"available_now": 15000
},
{
"role": "Partner",
"kind": "percent",
"value": 10,
"platform": false,
"remainder": false,
"amount": 10000,
"share_percent": 10,
"held": 0,
"refund_reversal": 0,
"net": 10000,
"available_now": 10000
},
{
"role": "Subcontractor",
"kind": "fixed",
"value": 5000,
"platform": false,
"remainder": false,
"amount": 5000,
"share_percent": 5,
"held": 0,
"refund_reversal": 0,
"net": 5000,
"available_now": 5000
}
],
"payouts": [
{
"date": "2026-10-23",
"party": "Provider",
"amount": 70000,
"note": "Scheduled payout"
},
{
"date": "2026-10-23",
"party": "Partner",
"amount": 10000,
"note": "Scheduled payout"
},
{
"date": "2026-10-23",
"party": "Subcontractor",
"amount": 5000,
"note": "Scheduled payout"
}
]
}How the API works
One payment in, every share out
Your checkout stays where it is. Payments arrive from the platform account you connect at your payment operator, or you record them with POST /payments. FractionalPay matches a rule, writes the split and tells you what happened. You never move funds through us, because we never hold them.
-
01
Create beneficiaries
Sellers, partners, affiliates or subcontractors, each linked to its connected account id at your operator.
-
02
Define a rule
Percent and fixed lines, a priority, a match on product or metadata, and the party that receives the remainder.
-
03
Payment succeeds
The split runs once per payment. The allocations and a ledger transaction that balances to zero are written in the same step.
-
04
Payouts and webhooks
Shares become available, move into payouts on your schedule and every change fires a signed event.
Worked example
A 1,000 USD payment split four ways
A customer pays 1,000.00 USD for a service. The provider earns 70 percent, the platform keeps 15 percent, the referring partner gets 10 percent and a subcontractor is owed a fixed 50.00 USD. Fixed lines are applied first, then percentages of the gross amount, and the sum of all shares always equals the payment.
-
Provider
- Rule
- 70%
- Share
- $700.00
-
Platform
- Rule
- 15%
- Share
- $150.00
-
Partner
- Rule
- 10%
- Share
- $100.00
-
Subcontractor
- Rule
- Fixed $50.00
- Share
- $50.00
-
Total
- Rule
- Share
- $1,000.00
When percentages do not divide evenly, for example 33.33 percent of 100.00 USD, FractionalPay rounds with the largest remainder method and sends the leftover cent to the remainder party you chose. Nobody gets a fraction of a cent and the ledger never drifts. You can run the same numbers in the split simulator without an account.
Ledger journal
Balanced
txn_4Q8M2R ·Split of order-1000 by rule v3
- Operator balance (your account) Dr$1,000.00
- Payable to Provider Cr$700.00
- Platform revenue Cr$150.00
- Payable to Partner Cr$100.00
- Payable to Subcontractor Cr$50.00
TotalDr $1,000.00 · Cr $1,000.00
| Account | Debit | Credit |
|---|---|---|
| Operator balance (your account) | $1,000.00 | |
| Payable to Provider | $700.00 | |
| Platform revenue | $150.00 | |
| Payable to Partner | $100.00 | |
| Payable to Subcontractor | $50.00 | |
| Total | $1,000.00 | $1,000.00 |
Build or buy
What a split payment API saves your engineers
Dividing a number by four is the easy part. The work is everything around it: the parts finance asks about months later, when a refund lands on an order that was already paid out.
FractionalPay ships all six behind one API and a dashboard your finance team can use without opening a ticket. If you only need the raw ledger and payout calls, start with the payouts API; if reconciliation is the pain, read about payment reconciliation software.
-
1
Double-entry ledger
Append-only entries, accounts per beneficiary, every transaction balancing to zero, balances you can rebuild at any date.
-
2
Idempotency
Operator events arrive twice and retries happen. Every write needs a key so one payment never becomes two splits.
-
3
Rounding and remainders
Percentages of odd amounts, mixed fixed and percent lines, currencies with different minor units, and a rule for the leftover cent.
-
4
Refunds and disputes
Reversing a split proportionally, carrying negative balances into the next payout and keeping the history readable.
-
5
Payout scheduling
Availability dates, holds, minimum thresholds, approvals and a retry path for failed transfers.
-
6
Reconciliation
Matching your ledger to the operator's balance transactions every day and flagging what does not match.
For developers
Predictable endpoints and signed events
Amounts are integers in minor units with a three-letter currency. Every POST accepts an Idempotency-Key, and the same key with the same body returns the first result for 24 hours. Test keys start with fp_test_ and work in the sandbox; live keys start with fp_live_.
Each split fires split.created. Refunds fire split.reversed, payouts fire payout.scheduled, payout.paid or payout.failed. Deliveries are signed with HMAC SHA-256 and retried with backoff for 24 hours.
-
Record a payment and split it with
POST /payments -
Reverse part of it with
POST /payments/{id}/refunds -
Read balances per beneficiary with
GET /balances
POST /v1/payments
201 Created
curl -X POST https://fractionalpay.com/api/v1/payments \
-H "Authorization: Bearer fp_test_4eC39H..." \
-H "Idempotency-Key: adcbad10-order" \
-H "Content-Type: application/json" \
-d '{
"external_id": "order_48213",
"amount": 100000,
"currency": "USD",
"product_ref": "service"
}'{
"id": 48213,
"object": "payment",
"external_id": "order_48213",
"amount": 100000,
"currency": "USD",
"fee": 0,
"net": 100000,
"customer_ref": null,
"product_ref": "service",
"metadata": {},
"livemode": false,
"status": "succeeded",
"occurred_at": 1792062776,
"created": 1792062776,
"split": {
"id": 48213,
"object": "split",
"status": "calculated",
"rule_id": 3,
"rule_version": 3,
"gross": 100000,
"currency": "USD",
"queued_reason": null,
"calculated_at": 1792062776,
"allocations": [
{
"id": 7101,
"beneficiary_id": 41,
"role_key": null,
"amount": 70000,
"currency": "USD",
"held_amount": 0,
"held_until": null,
"status": "available",
"payout_id": null
},
{
"id": 7102,
"beneficiary_id": 42,
"role_key": null,
"amount": 10000,
"currency": "USD",
"held_amount": 0,
"held_until": null,
"status": "available",
"payout_id": null
},
{
"id": 7103,
"beneficiary_id": 43,
"role_key": null,
"amount": 5000,
"currency": "USD",
"held_amount": 0,
"held_until": null,
"status": "available",
"payout_id": null
},
{
"id": 7104,
"beneficiary_id": null,
"role_key": "platform",
"amount": 15000,
"currency": "USD",
"held_amount": 0,
"held_until": null,
"status": "available",
"payout_id": null
}
]
},
"refunds": []
}Webhook delivery · split.created
200 delivered
POST https://api.yourplatform.com/hooks/fractionalpay
FractionalPay-Signature: t=1760534400,v1=5257a869e7ec...
{
"id": "evt_7c92f0e38760fc81336796a2",
"type": "split.created",
"created": 1760534400,
"livemode": false,
"data": {
"split": {
"id": 48213,
"object": "split",
"status": "calculated",
"rule_id": 3,
"rule_version": 3,
"gross": 100000,
"currency": "USD",
"queued_reason": null,
"calculated_at": 1792062776,
"allocations": [
{
"id": 7101,
"beneficiary_id": 41,
"role_key": null,
"amount": 70000,
"currency": "USD",
"held_amount": 0,
"held_until": null,
"status": "available",
"payout_id": null
},
{
"id": 7102,
"beneficiary_id": 42,
"role_key": null,
"amount": 10000,
"currency": "USD",
"held_amount": 0,
"held_until": null,
"status": "available",
"payout_id": null
},
{
"id": 7103,
"beneficiary_id": 43,
"role_key": null,
"amount": 5000,
"currency": "USD",
"held_amount": 0,
"held_until": null,
"status": "available",
"payout_id": null
},
{
"id": 7104,
"beneficiary_id": null,
"role_key": "platform",
"amount": 15000,
"currency": "USD",
"held_amount": 0,
"held_until": null,
"status": "available",
"payout_id": null
}
]
},
"payment_id": 48213,
"external_id": "order_48213"
}
}Split payment software
What every plan includes
The API and the dashboard are the same product. Engineers call endpoints, finance edits rules and approves payouts in the browser, and both see one ledger.
Each feature is included from the plan shown and in every plan above it. Compare plans.
-
Percentage and fixed rules
Starter+Priorities, product and metadata matching, caps and a remainder party.
-
Proportional refunds
Starter+Refunds and chargebacks reversed across every share automatically.
-
Payout schedules
Starter+Daily, weekly or monthly payouts with a minimum amount per beneficiary.
-
Recurring splits
Growth+Subscription renewals split again on every invoice, with time-limited partner lines.
-
Holds and reserves
Growth+Keep a percentage back until a return window or delivery date passes.
-
Multiple entities
ScaleSeveral connected accounts and currencies with a ledger per entity.
Split rule
Version 3 · Active
Rule name
Services, default
Applies to
Product is service
- 1 Provider 70%
- 2 Partner 10%
- 3 Subcontractor $50.00
Who builds with it
Made for the team that owns the money flow
A lead engineer usually starts with the sandbox and a test key on day one. Finance joins when the first rule goes live, because the ledger and the payout calendar answer the question they ask every Monday: how much do we owe whom right now.
Marketplaces use the same API to pay sellers, as described on our marketplace payments page, and subscription businesses use it for revenue sharing with resellers.
Questions
Frequently asked questions
Something else on your mind? Write to [email protected] or read the API documentation.
Does FractionalPay hold or move our money?
Which payment operator does the split payment API work with?
How are refunds handled after a split?
Can we test without live money?
fp_test_ keys and demo data. POST /splits/simulate returns allocations, ledger lines and payouts without saving anything.Is there a per-transaction fee?
What are the API rate limits?
Run your own split through the API
Start with the simulator on the homepage, then create a sandbox key and send the same request from your terminal.
No transaction fees from us. Runs on your own payment account at a licensed operator. FractionalPay never holds your funds.