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

SET Merchant API · Deposits

Return a deposit to its sender

POST/v1/deposits/{id}/return

Key scope: write · Success: 201

Sends a dollar deposit back to whoever sent it. The customer's own custodial wallet (POST /v1/wallets) pays for the return in USDC; SET takes no fee on a return. One return per deposit.

Path parameters

id stringrequired
The deposit's id.

Headers

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

Body

reason stringrequired
duplicate, fraudulent, requested_by_customer, requested_by_sender, unrecognized_sender, wrong_amount, compliance or other.
wallet stringrequired
The deposit customer's own custodial wallet, which funds the return.
sender objectrequired
Who sent the deposit, who receives it back (the Travel Rule beneficiary): {type: "business" | "individual", name, address: {country (alpha-3), …}}, or {type: "customer"}. Sent to the provider only.
amount decimal string
ACH and FedNow deposits: the whole deposit (400 amount_must_match). Wire, SEPA and Faster Payments: up to the deposit. Default: the whole deposit.

Notes

  • Only USD deposits for now: a EUR or GBP return would be cross-currency, which the provider must enable for SET first (409 return_currency_not_supported).
  • Within 90 days of the deposit (409 return_window_passed), once the provider has received it and not refunded it. Colombian PSE payments cannot be returned.
  • Events deposit.return_requested, then deposit_return.<state> as the return moves. In staging, a return of a simulated deposit is simulated.

Errors

  • 400 body_invalid
  • 400 reason_invalid
  • 400 amount_invalid
  • 400 amount_must_match
  • 400 amount_too_high
  • 400 return_refused
  • 404 deposit_unknown
  • 404 wallet_unknown
  • 409 return_exists
  • 409 return_currency_not_supported
  • 409 deposit_not_returnable
  • 409 return_window_passed
  • 409 return_rail_not_supported
  • 409 deposit_not_ready
  • 409 wallet_balance_too_low
  • 401 api_key_required
  • 401 api_key_invalid
  • 401 api_key_wrong_mode
  • 403 scope_missing
  • 429 rate_limited

All codes: Errors.