SETSimple Easy Transactions
SET DocsAPI reference and complianceUpdated 2026-11-09
Browse: SET Merchant API

SET Merchant API · Payout controls

Schedule a recurring payout

POST/v1/payout_schedules

Key scope: write · Success: 201

The same payout every day, week, month, quarter or year from a customer's custodial wallet to one of its recipients. Each run makes an ordinary payout under the creating key, with the same limits, approval and checks; the wallet's balance is checked when it runs.

Headers

Idempotency-Key string
Optional. The same key and body run once; a replay answers with Idempotent-Replayed: true. Kept 24 hours.

Body

wallet stringrequired
The paying customer's custodial wallet.
recipient stringrequired
One of that customer's recipients.
amount decimal stringrequired
USDC per payout, whole cents.
every "day" | "week" | "month" | "quarter" | "year"required
How often.
startAt ISO time
The first run, with its offset, within a year. Default: now.
count integer
How many payouts, 1–1000. Default: until canceled.
approval "required"
Hold each payout for an approver key.
externalId string
Your id; a repeat returns the same schedule. Each payout's externalId is <schedule>:<n>.

Notes

  • A scheduled payout takes no reference: references go to the bank in the sending request only and are never stored.
  • Runs missed while SET's scheduler was down are skipped, never sent twice. A revoked key or a disabled recipient stops the schedule.
  • Events payout_schedule.created, .skipped (with problem), .completed, .canceled, and each payout's own events.

Errors

  • 400 body_invalid
  • 400 external_id_invalid
  • 400 every_invalid
  • 400 start_at_invalid
  • 400 count_invalid
  • 400 approval_invalid
  • 400 reference_not_supported
  • 403 operator_cannot_pay_out
  • 409 limit_exceeded
  • 400 amount_invalid
  • 400 amount_too_small
  • 400 reference_invalid
  • 400 external_id_invalid
  • 400 recipient_other_customer
  • 404 recipient_unknown
  • 404 wallet_unknown
  • 409 recipient_disabled
  • 409 recipient_incomplete
  • 409 payee_not_ready
  • 409 balance_too_low
  • 409 initiation_required
  • 403 operator_cannot_pay_out
  • 403 platform_fee_not_allowed
  • 503 bridge_wallets_disabled
  • 401 api_key_required
  • 401 api_key_invalid
  • 401 api_key_wrong_mode
  • 403 scope_missing
  • 429 rate_limited

All codes: Errors.