Preview fees
See what a payout will cost before you send it. POST /v1/payouts/quote returns your account’s actual applicable payout fee — plus tax, the statutory levy, and the total that would leave your wallet — and, for a cross-currency quote, the derived beneficiary amount, source debit, and rate. It’s a read-only, advisory preview: no money moves and no payout is created.
Send the same amount fields you’d send to create a payout — minus the recipient and the send-time guards. Fees are resolved per-merchant, so a published fee table can’t tell you your rate; an authenticated quote can.
New to payouts? Start with the Payouts overview. For the cross-currency flow, see Cross-currency payouts.
Before you use a quote
- A valid API key is the only requirement — read tier, no extra capability or account enablement. You can preview cross-currency cost before requesting enablement.
- The fee is exact for your account.
fee_minor+tax_minorare the fee your account would actually pay for that amount, in that environment. - The rate and levy are indicative. For a cross-currency quote the
fx.rateis the current system rate (fx.indicative: true, withfx.as_of) — the binding rate is the one active when the payout is processed. Thelevy_minoris computed on your default route; the exact statutory levy can differ if your account has a bank-specific route. Usemin_receive_minor/max_debit_minoron the real payout to protect against rate movement between quote and send. - The quote takes no recipient. It’s PII-free — you don’t send
recipient, and the response never includes a spread or a provider name. - Environment-scoped to your key. A sandbox (
sk_test_…) key quotes your test fees + rates; a live (sk_live_…) key quotes live. Quote with the key for the environment you’re integrating against.
POSTPreview payout fees
Returns an advisory fee/cost breakdown. Provide the amount by exactly one method — amount_minor (destination — the beneficiary amount) or, for a cross-currency quote, funding_amount_minor (source — what leaves your funding wallet). No recipient, no min_receive_minor / max_debit_minor.
Destination (payout) currency — what the beneficiary receives (e.g. NGN).
Optional. The wallet currency you’d fund from. Present and different from currency → cross-currency quote (the response gains an fx block).
BigInt as string, minor units of currency. Destination method — the exact amount the beneficiary receives. XOR with funding_amount_minor.
BigInt as string, minor units of funding_currency. Source method — what leaves your funding wallet; the beneficiary amount is derived at the rate. Requires funding_currency. XOR with amount_minor.
Source method only. false (default) = on-top (the fee is added on top of what you send); true = inclusive (the fee is carved out of funding_amount_minor).
Optional self-documenting label, "source" or "destination". The amount fields are the source of truth — a mismatch returns 400. Only valid on a cross-currency quote.
Response fields
| Field | Type | Notes |
|---|---|---|
object | string | Always payout_quote. |
currency | string | Destination currency. |
amount_minor | string | Beneficiary receives (minor units of currency) — echoes your input for the destination method, derived at the rate for the source method. |
fee_minor | string | Your account’s actual applicable payout fee (minor units of currency). |
tax_minor | string | Tax on the fee (e.g. VAT), minor units of currency. |
levy_minor | string | Indicative statutory levy on the default route (minor units of currency). |
total_debit_minor | string | What leaves your funding wallet: the source debit (funding currency) for a cross-currency quote, otherwise amount + fee + tax + levy (in currency). |
fx | object | null | Present only on a cross-currency quote. Null for same-currency. |
fx.funding_currency | string | The wallet currency you’d fund from. |
fx.source_debit_minor | string | What would be debited from the funding wallet (minor units of funding_currency). Equals total_debit_minor. |
fx.converted_minor | string | What would be credited to the destination wallet to fund the payout — the full destination total (amount + fee + tax + levy), minor units of currency. |
fx.fee_source_minor | string | The fee (fee + tax + levy) expressed in the funding currency — the fee in the currency you send. |
fx.rate | string | Prevailing system rate (decimal). Indicative. |
fx.as_of | string | null | When the rate was published (UTC). Indicative. |
fx.indicative | boolean | Always true — a quote’s rate is advisory. |
The quote reuses the exact fee, levy, and conversion logic the real payout runs, so its numbers match what you’ll be charged — with two caveats: the rate is the current indicative rate (binding at execution), and the levy is your default route (the exact levy can differ on a bank-specific route). That’s why the quote is advisory. Set min_receive_minor (source method) or max_debit_minor (destination method) on the actual payout to guard against rate movement.
Errors
| Code | HTTP | Cause |
|---|---|---|
missing_field | 400 | currency is missing. |
unsupported_currency | 400 | currency or funding_currency is not a valid currency code. |
invalid_funding_currency | 400 | funding_currency is malformed or equals currency. |
invalid_amount | 400 | amount_minor / funding_amount_minor is not a positive integer. |
ambiguous_amount | 400 | Both amount_minor and funding_amount_minor were sent. |
amount_required | 400 | Neither amount field was sent. |
guard_field_wrong_method | 400 | funding_amount_minor without funding_currency, or fee_inclusive without funding_amount_minor. |
amount_basis_mismatch | 400 | amount_basis doesn’t match the amount fields, or was sent on a same-currency quote. |
fx_rate_unavailable | 422 | No active rate for the requested currency pair. |
funding_below_fee | 422 | Inclusive source method: funding_amount_minor is too small to cover the fee. |
unauthorized | 401 | Missing or invalid API key. |
# Same-currency (NGN): what will a ₦15,000 payout cost?
curl -X POST 'https://api.swappr.me/api/v1/payouts/quote' \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "currency": "NGN", "amount_minor": "1500000" }'
# Cross-currency (source method): I'll send C$15.00 from my CAD wallet to an NGN payout.
curl -X POST 'https://api.swappr.me/api/v1/payouts/quote' \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "currency": "NGN", "funding_currency": "CAD", "funding_amount_minor": "1500" }'{
"object": "payout_quote",
"currency": "NGN",
"amount_minor": "1500000",
"fee_minor": "5000",
"tax_minor": "0",
"levy_minor": "5000",
"total_debit_minor": "1510000",
"fx": null
}{
"object": "payout_quote",
"currency": "NGN",
"amount_minor": "1500000",
"fee_minor": "5000",
"tax_minor": "0",
"levy_minor": "5000",
"total_debit_minor": "1510",
"fx": {
"funding_currency": "CAD",
"source_debit_minor": "1510",
"converted_minor": "1510000",
"fee_source_minor": "10",
"rate": "1000.0",
"as_of": "2026-07-03T09:30:00.000Z",
"indicative": true
}
}