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

SET Merchant API · 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.

Merchant key A merchant's destination wallet is always its own: beneficiary.type must be "customer"; "platform" is refused with 400 beneficiary_invalid. Without returnAddress, the merchant's own registered return address is used (POST /v1/return_addresses).

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.