Creating and tracking payouts

Updated 18 September 20263 min read

On this page

A payout sends money from one of your ledger accounts to a counterparty's bank account. Creating one reserves the funds immediately, submits the payment on the rail you chose and then reports every step through its status and events.

Before you create a payout

You need three things:

A funded source account in the same currency as the payout.
A counterparty with a verified bank account. See Counterparties and screening.
A key with the payouts:write scope, or a secret key.

Create a payout

curl https://api.ledgerline.dev/v1/payouts \
  -H "Authorization: Bearer $LEDGERLINE_API_KEY" \
  -H "Idempotency-Key: 7d2f8c1e-5b3a-4a96-8a1e-9c04d2b6f3e8" \
  -d source_account_id=acc_01J9QK5M2A \
  -d counterparty_bank_account_id=cba_01JA6C8W4N \
  -d amount=1250000 \
  -d currency=USD \
  -d rail=ach \
  -d description="September invoice 2041"

{
  "id": "pay_01JA6D4H2K",
  "status": "scheduled",
  "rail": "ach",
  "amount": 1250000,
  "currency": "USD",
  "source_account_id": "acc_01J9QK5M2A",
  "expected_arrival": "2026-09-18T21:00:00Z",
  "submission_deadline": "2026-09-17T15:00:00Z",
  "created_at": "2026-09-16T09:42:11Z"
}

The amount is an integer in minor units, so 1250000 is $12,500.00. Always send an Idempotency-Key. A payout retried without one can be created twice. See Idempotency.

Creating payouts is limited to 120 requests per minute per key. See Rate limits.

Status lifecycle

Status	Meaning
`pending_review`	Held for manual review, for example a first large payout to a new counterparty.
`scheduled`	Accepted and waiting for the next submission window.
`submitted`	Sent to the bank or network. It can no longer be canceled.
`paid`	The rail confirmed delivery.
`failed`	Rejected before delivery. The funds are released back to the source account.
`returned`	Delivered, then sent back by the receiving bank. See Returns and failed payouts.
`canceled`	You canceled it before submission.

A payout moves forward only. paid can still become returned for a short time on batch rails.

What happens to the money

At creation Ledgerline posts a pending transaction that debits the source account, so the amount leaves the available balance at once. When the payout is submitted or paid the hold becomes permanent. On failed, returned or canceled the hold is released or reversed, and the funds reappear in available. See Account balances.

Canceling a payout

You can cancel a payout as long as it is pending_review or scheduled:

curl -X POST https://api.ledgerline.dev/v1/payouts/pay_01JA6D4H2K/cancel \
  -H "Authorization: Bearer $LEDGERLINE_API_KEY" \
  -H "Idempotency-Key: 3e1b7a90-60c4-4df2-b5f1-2a6d8e9c0b14"

Once the status is submitted, cancellation is not possible. If the payment is already on its way, wait for the outcome. If it is paid in error, you need the recipient to return the money.

Tracking progress

Do not poll. Subscribe to payout events and update your records when they arrive:

Event	Fired when
`payout.created`	The payout is accepted.
`payout.submitted`	It leaves for the bank or network.
`payout.paid`	Delivery is confirmed.
`payout.failed`	It was rejected.
`payout.returned`	The recipient bank sent it back.
`payout.canceled`	You canceled it.

Each event carries the full payout object. See the webhooks overview for delivery details and verify every delivery.

Limits

Per-payout and daily limits depend on your plan. For ACH, a single payout can be up to $25,000 on Starter, $250,000 on Growth and $1,000,000 on Scale. The complete table is in Limits and quotas. A payout over the limit fails with limit_exceeded, and the error's param names the limit that was hit.

Choosing when it arrives

The rail controls timing. A payout created before the 15:00 UTC cut-off on a business day is submitted that day. Read Payment rails for the cut-offs of each rail.

Listing payouts

GET /v1/payouts supports filters for status, counterparty_id, rail, created_after and created_before. The date range may span at most 366 days.