Skip to content
FractionalPay

Payouts API

The payouts API for platforms

The FractionalPay payouts API tells you what every beneficiary is owed and what happens to each payout: balances split into pending, held, available and paid, payouts with clear statuses, and a signed webhook for every change.

Payouts become transfers on your own connected Stripe account. You get the scheduling, thresholds, approvals and retries without writing them yourself.

Try the split simulator See pricing
  • Balances per beneficiary and currency in one call
  • Six payout statuses and payout.* webhooks
  • Idempotent writes, test and live keys

GET /v1/balances

200 OK

curl https://fractionalpay.com/api/v1/balances \
  -H "Authorization: Bearer fp_test_4eC39H..."
{
  "object": "list",
  "data": [
    {
      "object": "balance",
      "beneficiary_id": 8812,
      "name": "Northwind Studio",
      "currency": "USD",
      "pending": 42000,
      "held": 5000,
      "available": 128450,
      "paid": 1250000,
      "by_currency": {
        "USD": {
          "pending": 42000,
          "held": 5000,
          "available": 128450,
          "paid": 1250000,
          "owed": 170450
        }
      }
    },
    {
      "object": "balance",
      "beneficiary_id": 8811,
      "name": "Harbor Partners",
      "currency": "USD",
      "pending": 6500,
      "held": 0,
      "available": 19800,
      "paid": 214000,
      "by_currency": {
        "USD": {
          "pending": 6500,
          "held": 0,
          "available": 19800,
          "paid": 214000,
          "owed": 26300
        }
      }
    }
  ],
  "has_more": true
}

Money path

How a payout becomes a transfer on your account

FractionalPay does not sit in the money path. Customer payments land in your own platform account at your payment operator, and each beneficiary is linked to a connected account under that platform. We calculate, record and instruct. We never hold, pool or transmit funds and we are not a payment institution.

  1. 01

    Shares accrue

    Each split credits beneficiaries in the ledger. New shares start as pending, reserved shares as held.

  2. 02

    Balance becomes available

    After the availability delay or when a hold is released, the amount moves to available and fires hold.released where relevant.

  3. 03

    Payout is scheduled

    On the beneficiary's schedule, available balance above the minimum becomes a payout and fires payout.scheduled.

  4. 04

    Transfer on your account

    We instruct a transfer from your platform account to the beneficiary's connected account and track it to payout.paid or payout.failed.

Payout calendar

November 2026

Mon
Tue
Wed
Thu
Fri
Sat
Sun

1

2

3

4

5

6

$18.4k

$1.3k

7

8

9

10

11

12

13

$3.3k

14

15

16

17

18

19

20

$17.9k

21

22

23

24

25

26

27

28

29

30

  • Nov 6 · Sellers $18,420.00Scheduled
  • Nov 6 · Northwind Studio $1,284.50Scheduled
  • Nov 13 · Partners $3,260.00Approval
  • Nov 20 · Sellers $17,905.40Held
Weekly Friday payouts with a held batch and one awaiting approval

Payout statuses

Six statuses, one meaning each

GET /payouts returns every payout with one of six statuses. Your code never has to guess whether money moved, because each status maps to a single state of the transfer on your account.

  • scheduled

    What it means
    Due on a date, amount fixed
    Event
    payout.scheduled

  • held

    What it means
    Waiting on a hold or a negative balance
    Event
    none

  • awaiting_approval

    What it means
    Above your approval threshold
    Event
    none

  • sent

    What it means
    Transfer instruction accepted
    Event
    none

  • paid

    What it means
    Transfer confirmed on your account
    Event
    payout.paid

  • failed

    What it means
    Rejected, with a failure reason
    Event
    payout.failed

A failed payout keeps its failure_reason and the amount is not lost: it stays owed in the ledger and can go out again once the beneficiary fixes their account. Approvals above a threshold are a Scale feature: a second team member approves with POST /payouts/{id}/approve before the transfer is instructed.

Webhook delivery · payout.failed

200 delivered

POST https://api.yourplatform.com/hooks/fractionalpay

FractionalPay-Signature: t=1760534400,v1=5257a869e7ec...

{
  "id": "evt_e09867748b1b47a01510c52e",
  "type": "payout.failed",
  "created": 1760534400,
  "livemode": false,
  "data": {
    "payout": {
      "id": 7302,
      "object": "payout",
      "beneficiary_id": 8811,
      "amount": 19800,
      "currency": "USD",
      "status": "failed",
      "scheduled_for": 1792141200,
      "sent_at": 1792141260,
      "external_transfer_id": "tr_1Q9Hpt7302",
      "failure_reason": "account_closed",
      "requires_approval": false,
      "approved_by": null,
      "approved_at": null,
      "created": 1792062790
    }
  }
}

For developers

Endpoints, keys and retries you can rely on

Base URL https://fractionalpay.com/api/v1, JSON in and out, amounts as integers in minor units with a three-letter currency. Every POST accepts an Idempotency-Key; the same key with the same body returns the first result for 24 hours, so a retried approval never approves twice.

Webhooks carry a FractionalPay-Signature header with an HMAC SHA-256 of the timestamp and raw body. Failed deliveries retry with backoff for 24 hours (1 min, 5 min, 30 min, 2 h, 6 h, 12 h) and can be replayed from the delivery log. Test keys start with fp_test_, live keys with fp_live_.

  • Read balances with GET /balances
  • List payouts and filter by status with GET /payouts
  • Approve a payout with POST /payouts/{id}/approve on Scale
  • Look up a beneficiary and its balances with GET /beneficiaries/{id}
Read the API reference

POST /v1/payouts/9204/approve

200 OK

curl -X POST https://fractionalpay.com/api/v1/payouts/9204/approve \
  -H "Authorization: Bearer fp_test_4eC39H..." \
  -H "Idempotency-Key: 33042946-order" \
  -H "Content-Type: application/json"
{
  "id": 9204,
  "object": "payout",
  "beneficiary_id": 8811,
  "amount": 1326000,
  "currency": "USD",
  "status": "scheduled",
  "scheduled_for": 1792141200,
  "sent_at": null,
  "external_transfer_id": null,
  "failure_reason": null,
  "requires_approval": true,
  "approved_by": 7,
  "approved_at": 1792062800,
  "created": 1792062790
}

Webhook delivery · payout.paid

200 delivered

POST https://api.yourplatform.com/hooks/fractionalpay

FractionalPay-Signature: t=1760534400,v1=5257a869e7ec...

{
  "id": "evt_7f5495b5aad91970bdb4eead",
  "type": "payout.paid",
  "created": 1760534400,
  "livemode": false,
  "data": {
    "payout": {
      "id": 9204,
      "object": "payout",
      "beneficiary_id": 8811,
      "amount": 1326000,
      "currency": "USD",
      "status": "paid",
      "scheduled_for": 1792141200,
      "sent_at": 1792141260,
      "external_transfer_id": "tr_1Q9Hpt9204",
      "failure_reason": null,
      "requires_approval": true,
      "approved_by": 7,
      "approved_at": 1792062800,
      "created": 1792062790
    }
  }
}

Stripe payout API, without the bookkeeping

What you would otherwise build around raw transfers

Your operator's own API can move money from your platform balance to a connected account. What it does not keep is your business view: who earned which share of which payment, what is reserved, what was clawed back by a refund and what is safe to pay today. That bookkeeping is the part teams underestimate.

FractionalPay keeps it in a double-entry ledger where every transaction balances to zero. Payouts are drawn from the available balance only, negative balances from refunds are netted before anything is sent, and a minimum threshold stops tiny transfers. If you also need the split itself, start with the split payment API; if your use case is paying sellers, see marketplace payouts.

  • Daily, weekly or monthly schedules per beneficiary
  • Minimum payout amount and availability delay
  • Holds and reserves on Growth, four-eyes approvals on Scale

Beneficiary balances

Seller

Northwind Studio

Scheduled

$1,284.50

Available now

Weekly, Friday

Seller

Northwind Studio

Held

$50.00

Reserve 10% for 14 days

Releases Nov 9

Partner

Harbor Partners

Available

$198.00

Commission

Monthly, 1st

Partner

Harbor Partners

Paid

$2,140.00

Paid to date

Last payout Oct 1

Reconciliation run

Nov 6, 2026 · 3 matched, 1 open

  • txn_...4KQCharge
    Operator $1,000.00Ledger $1,000.00
    Matched
  • txn_...7PDPayout
    Operator $1,284.50Ledger $1,284.50
    Matched
  • txn_...2WNFee
    Operator $2.50Ledger none
    Missing
  • txn_...9LAPayout
    Operator $198.00Ledger $198.00
    Matched

Built for the engineer on call

Payout logic you can test before it touches money

Start in the sandbox with an fp_test_ key and demo data. Record test payments with POST /payments and watch balances move from pending to available. Live keys, webhook endpoints and real payouts open on a paid plan, once your own account is connected.

Daily reconciliation compares the ledger with your account's balance transactions and raises reconciliation.mismatch when a payout or fee does not line up. Full reference in the API documentation, plan limits on pricing.

Questions

Frequently asked questions

Something else on your mind? Write to [email protected] or read the API documentation.

What is the FractionalPay payouts API?
A REST API that exposes balances and payouts for every beneficiary on your platform. It decides what is payable, schedules payouts and instructs transfers on your own connected account, with a webhook for each change.
Is this a replacement for the Stripe payout API?
No, it works on top of it. Transfers still happen on your own Stripe account. FractionalPay adds the ledger, balances, schedules, holds, approvals and reconciliation around them.
Does FractionalPay hold the funds being paid out?
No. Funds stay in your platform account at your payment operator until they are transferred to the beneficiary's connected account. We never hold, pool or transmit funds and we are not a payment institution.
What do pending, held and available mean?
Pending is earned but not yet past the availability delay. Held is reserved by a hold rule or offset by a negative balance. Available is ready for the next payout. Paid is what has already been transferred.
Which plan includes payout approvals?
Four-eyes approvals above a threshold, with POST /payouts/{id}/approve, are part of Scale at 1,499 USD a month or 749 USD a month billed yearly.
What are the API limits?
Up to 100 requests per second per key. Monthly quotas are 50,000 requests on Starter, 500,000 on Growth and 5,000,000 on Scale; the sandbox allows 100 requests a day.
Is there a fee per payout?
Not from us. Plans are flat monthly prices with a split flow limit. Your operator's own payout fees stay as they are.

Watch a split turn into payouts

Run a payment through the simulator to see each balance, the ledger lines and the payout date, then create a sandbox key and call the same endpoints.

Try the split simulator See pricing

No transaction fees from us. Runs on your own payment account at a licensed operator. FractionalPay never holds your funds.