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

SET Merchant API · Recipients & payouts

Pay a recipient

POST/v1/payouts

Key scope: write · Success: 201

One payout from a customer's custodial wallet to one of its recipients: to a bank in its currency and rail, to a wallet, to another customer's wallet, or to an email. SET's fee is the key's developer fee, and at least 1.00 must reach the recipient. The Travel Rule data goes with it: the customer as originator, the recipient as beneficiary.

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 wallet (POST /v1/wallets). It must hold the amount, less payouts already queued.
recipient stringrequired
One of that customer's recipients.
amount decimal stringrequired
USDC, whole cents.
reference string
Bank payouts only, sent to the bank and never stored: ACH 10 letters, digits or spaces; wire 140; SEPA 6–140; SPEI, Pix and Faster Payments the rail's own.
externalId string
Your id; a retry with the same one returns the same payout.
platformFeeBps integer
Platform keys: the platform's own fee, in basis points, once SET allows it.

Notes

  • States follow the provider's transfer, forward only. Events payout.created, payout.<state>, payout.create_failed, and for live crypto payouts payout.delivered, payout.chain_mismatch or payout.chain_failed once the chain is read. paidToBank is true at payment_processed on a bank rail; delivered only when the chain agrees.
  • A refused payout answers 502 with the payout in create_failed and error: "payout_refused"; nothing left the wallet.
  • SET re-reads any payout no webhook has moved for 15 minutes. SET's operator cannot pay out (403 operator_cannot_pay_out).

Errors

  • 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
  • 502 payout_refused
  • 401 api_key_required
  • 401 api_key_invalid
  • 401 api_key_wrong_mode
  • 403 scope_missing
  • 429 rate_limited

All codes: Errors.