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

SET API (Platforms) · Recipients & payouts

Create a recipient

POST/v1/recipients

Key scope: write · Success: 201

A third party a customer pays from its custodial wallet: a supplier, a contractor, or the platform itself. The name and address are sealed at rest and appear in no event.

Platform key party: {type: "platform"} needs platform funds allowed for the platform (403 platform_funds_not_allowed).

Headers

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

Body

customer stringrequired
The paying customer.
party objectrequired
{type: "business" | "individual", name, address: {country (alpha-3), streetLine1?, city?, state?, postalCode?}, legalEntityIdentifier?, firstName?, lastName?}, or {type: "platform"}: the platform itself, with the legal details SET registered for it.
destination objectrequired
{kind: "bank", currency, …} with the fields of POST /v1/bank_accounts in any of the six currencies (rail defaults from the currency); {kind: "wallet", chain, address} for any wallet, a Cash-Out Address included; {kind: "bridge_wallet", wallet} for another of your customers' custodial wallets; {kind: "email", email, chain?} for SET Payable Email.
externalId string
Your id for the recipient.

Notes

  • Bank numbers go to the provider only, held there in the recipient's name under the paying customer; an email goes to the sign-in provider only.
  • Events recipient.created, recipient.disabled.

Errors

  • 400 party_invalid
  • 400 destination_invalid
  • 400 currency_invalid
  • 400 rail_invalid
  • 400 bank_details_refused
  • 400 chain_invalid
  • 400 address_invalid
  • 400 wallet_type_invalid
  • 400 recipient_is_customer
  • 400 external_id_invalid
  • 404 wallet_unknown
  • 409 platform_details_incomplete
  • 403 platform_funds_not_allowed
  • 403 payable_email_merchant
  • 403 payable_email_off
  • 503 payable_email_disabled
  • 503 recipients_unavailable
  • 401 api_key_required
  • 401 api_key_invalid
  • 401 api_key_wrong_mode
  • 403 scope_missing
  • 429 rate_limited

All codes: Errors.