Skip to main content
A payout schedule pays out money you have collected from customers without you calling Create Payout. You choose an interval for a currency and a default destination for it. Every time the interval comes around, whatever has settled since the last run goes to that destination as one payout. Schedules are per currency. NGN can pay out daily while USD stays manual, and each currency has its own interval, its own minimum, and its own default destination.

​
What Gets Paid Out

A schedule moves settled customer collections only. Money you put into the balance yourself is invisible to it: This is deliberate. If you top a balance up for a specific purpose, the next run does not send it away. Three further rules decide the amount:
  • Whole collections only, oldest first. A run takes settled collections in the order they landed and stops at the first one your spendable balance no longer covers. What it stops at stays eligible for the next run.
  • Your spendable balance is the ceiling. A refund or a lost dispute since settlement makes your balance smaller than what you earned, and a run does not pay out money that is no longer there.
  • The minimum is a floor, not a target. If you set one and the eligible total is below it, the run pays nothing and the money rolls into the next run.

​
Intervals

manual is the off switch. A currency with no schedule behaves the same way, so setting manual is how you turn automatic payouts off without losing the rest of the configuration. anchor_hour_utc is an hour from 0 to 23 in UTC, and defaults to 10. The payout days are lists, so weekly and monthly are floors rather than exact frequencies. weekly_payout_days takes weekday names, monday through sunday, defaulting to ["monday"]. monthly_payout_days takes days of the month, each 1 to 31, defaulting to [1]. A weekly schedule on ["monday", "thursday"] pays twice a week, and the next run is always the soonest day still ahead.
29, 30 and 31 mean the last day of a month that is shorter. Set [31] and you are paid on the 31st of January, the 30th of April, and the 28th of February, which is how you ask to be paid at month end. Two days that collapse onto the same date in a short month, such as [30, 31] in February, are one payout rather than two.
A list is only read by the interval it belongs to. Sending weekly_payout_days with a monthly interval is rejected rather than ignored, so a schedule never quietly loses the days you asked for.

​
How instant Behaves

instant is not a schedule in the clock sense. It reacts to funds settling, so you are paid several times on a busy day and not at all on a quiet one, and next_run_at is always null. Collections that settle close together are paid out together, in one payout carrying one fee. A batch of collections maturing at the same time produces a single payout for the total, not one payout per collection.
Choose instant when you want money out as soon as it is yours. Choose a clock-driven interval for fewer, larger payouts and therefore fewer fees. Neither is more reliable than the other.

​
Where The Money Goes

Each currency pays out to the destination flagged is_default for that currency. Promote one with Update Destination. It has to be approved and still active, and the destination decides the rail and the payment method exactly as it does for a manual payout. If a currency has no default destination, its schedule skips that currency and pays nothing.
Deleting a destination clears the default flag with it. The schedule stays on its interval and quietly pays nothing until you promote another destination, so promote the replacement in the same sitting.

​
Paying Out In A Different Currency

A currency can pay out in another one, for example paying a USD balance to an NGN bank account. The rate is quoted when the run happens, not when you save the schedule, so the payout uses the rate of the day it is sent. Conversion follows the same corridor rules as a manual cross-currency payout: it is available out of USD and stablecoin balances, and not out of a local settlement currency. USD to NGN works. NGN to USD is rejected when you save the schedule, not silently at run time.

​
Fees

A scheduled payout is charged exactly like a manual one. amount is what the destination receives, and the fee is added on top, so the balance has to cover total_debited rather than amount. See Create Payout.

​
Setting A Schedule

The schedule has its own resource, separate from the account object. GET /v1/balance_settings · scope balance:read · full field reference → POST /v1/balance_settings · scope balance:write · full field reference → Neither takes an id in the path. Without X-Account-Id, both act on the account your key belongs to. The path and its scopes are named balance_settings for historical reasons; the schedule is the only thing they carry.
GET /v1/balance_settings returns the same block, so you never have to keep your own copy of the schedule. A currency that has never been scheduled is absent from the map rather than present and empty, because “pays out weekly” and “was never configured” are different answers.
Reading needs balance:read, writing needs balance:write. GET /v1/balances needs balance:read too, so one scope covers the whole balance resource.

​
What A Write Replaces

The two halves of schedule_by_currency behave differently, and the difference matters when you save a form:
  • A currency you leave out keeps its schedule. A call naming NGN does not stop USD paying out, so you never have to send currencies you were not thinking about.
  • A currency you name is replaced in full. A field you omit is cleared rather than kept, so send the whole schedule for that currency, not the one field that changed.
Turn automatic payouts off with "interval": "manual" rather than by removing the currency, which changes nothing.
The old cadence, enabled and anchor_day fields are rejected rather than ignored. A request still sending them fails with 400 VALIDATION_ERROR instead of quietly saving a schedule built from defaults, which would pay out on a day you did not choose.

​
Connected Accounts

If you run a platform, paying your accounts out by hand does not scale. Every account you onboard is another balance to watch and another payout to remember. Setting a schedule turns that into configuration: you choose each account’s interval once, at onboarding, and stop tracking the timing yourself. It is the same call, acting on the connected account with the X-Account-Id header instead of your own:
Reading with the same X-Account-Id returns the same block, so you can show an account its own schedule without keeping a copy of it. A full onboarding sequence for a new account is three calls: register the destination with Create Destination, promote it with Update Destination once it clears review, then set the schedule with X-Account-Id. From then on the account is paid without you calling Create Payout for it again.
X-Account-Id has to name an account your platform manages, or your own, the same resolution every other API-key route uses, so it needs no special-casing on your side. A platform sets the timing; the account holder can change it from their own dashboard, so treat what you set as a starting point rather than a lock.
Pair instant with a minimum_amount when an account collects small amounts through the day. Collections settling close together are already paid out together, but ones settling hours apart are not, so each carries its own fee. A floor holds them back until they are worth sending.

​
Tracking Scheduled Payouts

A scheduled payout is an ordinary payout once it exists. It appears in List Payouts, it is readable with Get Payout, and it emits payout.paid and payout.failed like any other. Its reference is generated for you and begins with auto_, which is how you tell it apart from payouts you created yourself. If a scheduled payout fails, the money returns to your balance and the collections behind it become eligible again, so the next run picks them back up rather than stranding them.
Three consecutive failed runs set the currency back to manual, and the reason is recorded in disabled_reason. This stops a rejected destination or a revoked permission from failing every cycle indefinitely. Setting an automatic interval again clears the count and resumes it, so check what failed before you turn it back on.