Returning deposits
SET API and SET Merchant API · Live since 2026-11-09
A customer sometimes receives money it should not keep: a duplicate, a payment from someone it does not know, or the wrong amount. POST /v1/deposits/{id}/return sends a dollar deposit back to whoever sent it.
How a return works
- Who pays for it: the customer's own custodial wallet (
wallet, fromPOST /v1/wallets), in USDC. SET takes no fee on a return. If the wallet holds too little, the answer is409 wallet_balance_too_low. - Who receives it: always the original sender of the deposit. Name them in
sender:{type: "business" | "individual", name, address}, or{type: "customer"}when the customer sent it itself. They are the Travel Rule beneficiary of the return, and their details go to SET's provider only. - Why:
reasonis one ofduplicate,fraudulent,requested_by_customer,requested_by_sender,unrecognized_sender,wrong_amount,complianceorother. - One return per deposit. Follow it with
GET /v1/deposits/{id}/return, or list all withGET /v1/deposit_returns.
Rules checked before anything is sent
| Rule | Answer when broken |
|---|---|
| ACH and FedNow deposits are returned in full | 400 amount_must_match |
| Wire, SEPA and Faster Payments can be returned in part, never more than the deposit | 400 amount_too_high |
| Within 90 days of the deposit | 409 return_window_passed |
| The deposit has been received and not refunded | 409 deposit_not_returnable |
| USD deposits only, for now: a EUR or GBP return would be cross-currency, which the provider must enable for SET | 409 return_currency_not_supported |
| Colombian PSE payments cannot be returned | 409 deposit_not_returnable |
Events
deposit.return_requested, then deposit_return.<state> as the return moves. In staging, returning a simulated deposit (sim_dep_…) is simulated and nothing is sent.
Crypto that cannot be delivered
When stablecoin sent to an address cannot be delivered, SET's provider returns it according to a crypto return policy. A policy covers SET's whole account, so only SET's operator sets one, and only to static addresses. Read them with GET /v1/crypto_return_policies; evmReturnsCovered says, per stablecoin, whether every EVM chain is covered. Multichain addresses that take one stablecoin on every EVM chain depend on these policies and are not offered yet.