API referencePreview fees

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_minor are 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.rate is the current system rate (fx.indicative: true, with fx.as_of) — the binding rate is the one active when the payout is processed. The levy_minor is computed on your default route; the exact statutory levy can differ if your account has a bank-specific route. Use min_receive_minor / max_debit_minor on 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

POST/v1/payouts/quote

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.

Body parameters
currencystringRequired

Destination (payout) currency — what the beneficiary receives (e.g. NGN).

funding_currencystring

Optional. The wallet currency you’d fund from. Present and different from currency → cross-currency quote (the response gains an fx block).

amount_minorstring

BigInt as string, minor units of currency. Destination method — the exact amount the beneficiary receives. XOR with funding_amount_minor.

funding_amount_minorstring

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.

fee_inclusiveboolean

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).

amount_basisstring

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

FieldTypeNotes
objectstringAlways payout_quote.
currencystringDestination currency.
amount_minorstringBeneficiary receives (minor units of currency) — echoes your input for the destination method, derived at the rate for the source method.
fee_minorstringYour account’s actual applicable payout fee (minor units of currency).
tax_minorstringTax on the fee (e.g. VAT), minor units of currency.
levy_minorstringIndicative statutory levy on the default route (minor units of currency).
total_debit_minorstringWhat leaves your funding wallet: the source debit (funding currency) for a cross-currency quote, otherwise amount + fee + tax + levy (in currency).
fxobject | nullPresent only on a cross-currency quote. Null for same-currency.
fx.funding_currencystringThe wallet currency you’d fund from.
fx.source_debit_minorstringWhat would be debited from the funding wallet (minor units of funding_currency). Equals total_debit_minor.
fx.converted_minorstringWhat 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_minorstringThe fee (fee + tax + levy) expressed in the funding currency — the fee in the currency you send.
fx.ratestringPrevailing system rate (decimal). Indicative.
fx.as_ofstring | nullWhen the rate was published (UTC). Indicative.
fx.indicativebooleanAlways 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

CodeHTTPCause
missing_field400currency is missing.
unsupported_currency400currency or funding_currency is not a valid currency code.
invalid_funding_currency400funding_currency is malformed or equals currency.
invalid_amount400amount_minor / funding_amount_minor is not a positive integer.
ambiguous_amount400Both amount_minor and funding_amount_minor were sent.
amount_required400Neither amount field was sent.
guard_field_wrong_method400funding_amount_minor without funding_currency, or fee_inclusive without funding_amount_minor.
amount_basis_mismatch400amount_basis doesn’t match the amount fields, or was sent on a same-currency quote.
fx_rate_unavailable422No active rate for the requested currency pair.
funding_below_fee422Inclusive source method: funding_amount_minor is too small to cover the fee.
unauthorized401Missing or invalid API key.
Request
# 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" }'
Response — same-currency
{
  "object": "payout_quote",
  "currency": "NGN",
  "amount_minor": "1500000",
  "fee_minor": "5000",
  "tax_minor": "0",
  "levy_minor": "5000",
  "total_debit_minor": "1510000",
  "fx": null
}
200 OK
Response — cross-currency
{
  "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
  }
}
200 OK