Exchange-rate drift on payouts
SET API (Platforms) and SET Merchant API · Live since 2026-11-10
The problem
A bank payout in another currency is converted at the rate when it is sent, not when you created it. A payout that waits for an approver, is scheduled for later, or sits in a queue can go out at a rate that has moved. No rate is locked: SET's provider offers no rate lock.
The answer: maxRateDriftBps
Tell SET how far the rate may move:
POST /v1/payouts
{ "wallet": "…", "recipient": "rcp_…", "amount": "5000.00", "maxRateDriftBps": 50 }- When the payout is created, SET reads the buy rate from USD to the payout's currency and keeps it.
- Just before the payout is sent, SET reads the rate again.
- If it has moved by more than
maxRateDriftBpsbasis points in either direction, the payout is held for review. You getpayout.pending_reviewwithreviewReasons: ["rate_drift"], and nothing is sent. - SET's operator then releases the payout (
payout.released, sent at the rate then) or refuses it (payout.refused, nothing sent).
A rate SET cannot read at send time also holds the payout. It is never sent blind.
Rules
| Rule | Detail |
|---|---|
| Currencies | Bank payouts in EUR, GBP, MXN, BRL or COP. Anything else is 400 max_rate_drift_not_applicable |
| Range | 1 to 5000 basis points (0.01% to 50%). Anything else is 400 max_rate_drift_invalid |
| Measured | The change from the rate at creation, in basis points of that rate, rounded up |
| No rate at creation | 502 rate_unavailable. Try again, or leave the field out |
| Scheduled and approved payouts | Covered: the check runs when the payout is actually sent |
| Payout batches | Not covered. Batch items carry no guard |
Choosing a value
- A payout sent at once moves little between creation and sending. A guard matters most for payouts that wait: for approval, for a schedule, or for funds.
- Too tight a value holds payouts that would have been fine. Hold the payout only when the cost of a worse rate outweighs a delay.
What it is not
It is not a locked rate, and it does not guarantee the amount that arrives. The recipient's bank amount still depends on the rate when the payout is sent, and on fees. GET /v1/exchange_rates gives an estimate only.