Split payment API documentation

This split payment API documentation explains how FractionalPay turns each payment on your own operator account into allocations, ledger entries and payouts. Read the concepts once, then follow the quickstart with a test key in about fifteen minutes.

API reference Quickstart

How a split flows

FractionalPay is a rules, ledger and orchestration layer. Your customer pays at your licensed payment operator, the money lands in your own platform account, and FractionalPay decides who gets what, books it and tells the operator when to pay. We never hold funds. The split payment API page shows the product side, the security page the money flow in detail.

1

Payment

Operator reports a succeeded payment of $1,000.00
2

Rule

Highest priority match, version stored with the split
3

Ledger

Balanced transaction, one credit per beneficiary
4

Payout

Scheduled instruction sent to your operator account

Workspace

Your company in FractionalPay. It owns the connected operator account, beneficiaries, rules, the ledger, team members, API keys and the subscription. Scale workspaces can hold up to 10 connected accounts with a ledger per entity.

Beneficiaries

Everyone who receives a share: sellers, providers, partners, affiliates, subcontractors, locations or creators. Each beneficiary links to its own connected account ID at your operator, where the operator verifies it.

Split rules

A rule matches payments (all payments, a product, or a metadata key and value) and lists lines in percent or fixed amounts. Rules have a priority, and a remainder line decides who receives the cents left after rounding. Lines above 100 percent are rejected.

Splits

When a payment succeeds at your operator, the highest priority matching rule produces a split: one allocation per beneficiary. Rounding uses the largest remainder method, so allocations always add up to the payment amount to the cent.

Ledger

Every split, hold, refund and payout is a double-entry transaction whose debits equal its credits. The ledger is append-only: corrections are new reversing transactions. Balances per beneficiary are pending, held, available and paid.

Payouts

Available balances are paid on the schedule you choose (instant, weekly or monthly) once they pass the minimum payout threshold. FractionalPay sends the payout instruction, your operator moves the money and reports the result back.

Holds and reserves

A rule line can hold a percentage of a beneficiary's share for a number of days, for example until delivery or until a return window ends. Held amounts are released automatically and booked in the ledger (Growth and Scale).

Refunds

A full or partial refund is reversed proportionally across every beneficiary of the original split. If part of a share was already paid out, the difference is recorded as a negative balance and netted against the next payout.

Reconciliation

Every day the ledger is matched against the balance transactions of your operator account. Matches are marked, mismatches raise an alert and a reconciliation.mismatch webhook (Growth and Scale).

Test and live keys

Keys starting with fp_test_ work on test data in any workspace, including the sandbox with 100 requests per day. Keys starting with fp_live_ act on live data and need a paid plan. Keys are shown once and stored as a hash.

Quickstart in five steps

Everything below works with a test key in the sandbox workspace you get at signup. Amounts are integers in cents. The full field list is in the API reference.

1
Create a test key

Sign up, open Developers in the dashboard and create a test key. Copy it, it is shown only once.
```
export FP_KEY="fp_test_9c2f..."
```

Simulate a split

Check your percentages before saving anything. The simulate endpoint uses the same engine as the dashboard.

curl https://fractionalpay.com/api/v1/splits/simulate \
  -H "Authorization: Bearer $FP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100000, "currency": "USD", "parties": [{"role": "Provider", "kind": "percent", "value": 70}, {"role": "Platform", "kind": "percent", "value": 15}, {"role": "Partner", "kind": "percent", "value": 10}, {"role": "Subcontractor", "kind": "percent", "value": 5}]}'

Add beneficiaries

Create one beneficiary per party and store the returned integer IDs (the example below returns id 20). In live mode, add the connected account ID each one has at your operator.

curl https://fractionalpay.com/api/v1/beneficiaries \
  -H "Authorization: Bearer $FP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Northwind Studio", "email": "[email protected]", "type": "seller", "country": "US", "currency": "USD"}'

Save a split rule

Turn the simulation into a rule with lines that point to your beneficiaries by ID, a platform line for your share, and the beneficiary that receives the cents left after rounding.

curl https://fractionalpay.com/api/v1/rules \
  -H "Authorization: Bearer $FP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketplace default", "match_type": "all", "priority": 10, "lines": [{"beneficiary_id": 20, "kind": "percent", "value": 70}, {"role_key": "platform", "kind": "percent", "value": 30}], "remainder_to_beneficiary_id": 20}'

5
Record a test payment and listen for webhooks

Record a payment with your test key, see split.allocations in the response and receive split.created on your webhook endpoint. A payment no rule can split yet is kept with split.status queued and a queued_reason. In live mode, payments arrive from your connected operator account automatically.
```
curl https://fractionalpay.com/api/v1/payments \
  -H "Authorization: Bearer $FP_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "order-10482", "amount": 100000, "currency": "USD", "customer_ref": "cus_771"}'
```

Going live

Choose a plan, connect your platform account at your operator from Settings, create a live key and point your webhook endpoint at production. Live payments then split automatically, with no change to your checkout. Plans and limits are on the pricing page.