SETSimple Easy Transactions
SET DocsAPI reference and complianceUpdated 2026-11-09
Browse: SET API (Platforms)

Payout controls

SET API and SET Merchant API · Live since 2026-11-09

Payouts from a customer's custodial wallet (POST /v1/payouts) can wait for a second approver, go out later or on a schedule, and stay within limits. SET also runs its own checks before any payout is sent.

Approval by a second key (maker-checker)

Send approval: "required" with a payout. The answer is 202 with state: "pending_approval", and nothing is sent yet.

  • A key with the approve scope, other than the key that asked, calls POST /v1/payouts/{id}/approve or /reject.
  • On approval the payout is checked against the wallet's balance and sent. A rejected payout is rejected and nothing is sent.
  • approve is a third key scope beside read and write. SET issues approver keys. POST /v1/api_keys passes the scope on only from a key that has it.
  • An approver key with read approve can approve but cannot make payouts. SET's operator cannot approve.

Later and recurring payouts

  • Later: scheduleAt (ISO 8601 with its offset, within a year) answers 202 with state: "scheduled". SET sends it once due, checking the balance then; a short wallet ends it as create_failed with problem balance_too_low.
  • Cancel: POST /v1/payouts/{id}/cancel stops a payout still waiting for approval or for its time.
  • Recurring: POST /v1/payout_schedules {wallet, recipient, amount, every, startAt?, count?, approval?, externalId?}, where every is day, week, month, quarter or year. Each run makes one payout under the key that created the schedule, with the same limits, approval and checks. Its externalId is <schedule>:<n>.
    • Runs missed while SET's scheduler was down are skipped, never sent twice.
    • A revoked key or a disabled recipient stops the schedule.
    • DELETE /v1/payout_schedules/{id} stops it.
  • A payout sent later takes no reference: references go to the bank in the sending request only and are never stored.

Limits

SET sets limits per API key and per recipient: the most one payout may send, and the most in any rolling 24 hours. Read them at GET /v1/payout_limits. Today every default is null (no limit). A payout over a limit is refused with 409 limit_exceeded, naming the limit and its maximum.

SET's checks before sending

SET runs its own checks inside the send path of every payout: single payouts, batch items, scheduled runs and released approvals. The checks are:

  • the number or value of payouts per customer and per recipient over 24 hours;
  • a first payout to a new recipient above an amount;
  • the recipient's country against the countries SET's provider serves;
  • the same bank account or wallet paid by another platform. SET compares a keyed hash of the account, never the numbers.

A hit holds the payout as pending_review (202, event payout.pending_review, with reviewReasons). SET's operator then releases it as asked (payout.released) or refuses it (payout.refused; nothing is sent). The operator never starts or redirects a payout.

The thresholds are SET's to set, and each check is switched off until SET sets it.

FedNow

A USD bank recipient can take destination.rail: "fednow" once SET switches FedNow payouts on (403 fednow_disabled until then). SET reads the account back from its provider and refuses it (fednow_not_supported) unless the account can receive FedNow. Cash-Out Addresses do not offer FedNow.

Events

payout.pending_approval, payout.approved, payout.rejected, payout.scheduled, payout.canceled, payout.pending_review, payout.released, payout.refused, payout_schedule.created, payout_schedule.skipped, payout_schedule.completed, payout_schedule.canceled.