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

SET API (Platforms) · Payment setups

Set up one way to get paid

POST/v1/payment_setups

Key scope: write · Success: 201

One call per way. Checks everything first, creates what the way needs (bank account, Cash-Out Address, virtual account) and answers with payTo: exactly what the merchant gives its payers. A refused setup writes nothing.

Platform key beneficiary: {"type": "platform"} (the platform's own wallet) is refused with 403 platform_funds_not_allowed unless SET has allowed platform funds for that platform. Use the merchant's own wallet, {"type": "customer", …}. Without platform funds allowed, returnAddress is required and must be an address the merchant controls (400 return_address_required); the platform's own registered address is refused.

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
An approved customer.
way "wallet" | "cash_out" | "bank" (or 1, 2, 3)required
1 collect bank transfers as stablecoin to a wallet; 2 take stablecoin and pay out to the merchant's bank; 3 collect bank transfers to the merchant's bank.
currency "usd" | "eur" | "gbp"
Ways 1 and 3: what payers send. Default usd (way 3: the bank's own currency).
asset, address, beneficiary object
Way 1: the destination stablecoin (for example usdc-base), wallet address and whose wallet it is (Travel Rule).
bankAccount object | string
Ways 2 and 3: the fields of POST /v1/bank_accounts, or the id of one already linked.
chain "base" | "ethereum" | "solana"
Ways 2 and 3. Default base.
stablecoin "usdc" | "eurc"
Ways 2 and 3. Default usdc.
rail "ach" | "wire" | "sepa" | "faster_payments"
Ways 2 and 3. Default from the bank's currency.
reference string
Shown on each bank payout, within the rail's limits.
returnAddress string
Where a payment that cannot be paid out is returned.

Notes

  • If a later step is refused, the answer names it (step: bank_account, cash_out_address or virtual_account) and lists created. Fix the request and send it again: each step is content-idempotent.
  • Conversion Addresses (crypto to crypto) stay a separate call: POST /v1/conversion_addresses.

Errors

  • 400 way_invalid
  • 400 field_not_used
  • 400 bank_account_required
  • 400 return_address_required
  • 400 route_not_supported
  • 409 verification_incomplete
  • 409 endorsement_required
  • 403 platform_funds_not_allowed
  • 401 api_key_required
  • 401 api_key_invalid
  • 401 api_key_wrong_mode
  • 403 scope_missing
  • 429 rate_limited

All codes: Errors.