URL params
Every query parameter that configures the Pay Widget.
The Pay Widget is configured through URL query parameters.
Values are matched exactly, in lower case, and a value we do not recognise is dropped silently — no error, no warning. The widget then falls back to a default, which is not always the one you would expect. The rows below say what each fallback is; read them before you hard-code a value.
Deep links need countryIsoCode. Any URL that opens a screen past the first one — /wallet, /auth, /swap, /auto-order — sends the user back to the start if it is missing, discarding the rest of your parameters.
Identity
source
on-ramp / off-ramp
The "Source" value from your merchant dashboard. Matches the order to your account. [Warning] In production you must be a verified merchant to use it. Contact us for KYB.
signature
on-ramp / off-ramp
A JWT (HS256) signed with a URL signature secret from your merchant dashboard. You can also carry configuration parameters in the token payload. [Warning] In production you must be a verified merchant to use it. Contact us for KYB.
See Signing the URL.
What to buy or sell
network
on-ramp / off-ramp
Wallet network. ARBITRUM, AVALANCHE, BASE, BNB, CELO, ETHEREUM, LISK, OPTIMISM, POLYGON, SOLANA, STELLAR, TEMPO, TON, TRON, XRP.
asset
on-ramp / off-ramp
Wallet asset. It must be one the network carries — the matrix is on Supported countries and cryptocurrencies.
Omit it and the widget picks the network's first available asset. With freezeWallet set, an unavailable pair shows a configuration error instead of falling back.
memo
on-ramp
Memo for the networks the widget routes by memo — Stellar and TON. A transfer to an exchange without the right memo is usually unrecoverable.
address
on-ramp
The wallet to deliver crypto to.
[Warning] In production you must be a verified merchant, and a valid signature must be present. Contact us for KYB.
amount
on-ramp / off-ramp
The amount, interpreted by currency. With no currency it is an amount of crypto to receive after fees.
currency
on-ramp / off-ramp
What amount means: local or crypto, lower case.
[Warning] Any other value — including LOCAL — is dropped, and an absent currency means crypto. So amount=50000¤cy=LOCAL quietly asks for 50,000 units of crypto.
countryIsoCode
on-ramp / off-ramp
Country to preselect, e.g. KE, NG. Required in practice on any deep link.
currencyIsoCode
on-ramp / off-ramp
An alternative to countryIsoCode, supported for nine currencies only: NGN, KES, GHS, UGX, ZAR, TZS, RWF, ZMW, MWK. Upper case, exact. Anything else — including XOF and XAF — is ignored. Prefer countryIsoCode.
paymentChannel
on-ramp / off-ramp
Channel to preselect, lower case: bank, mobile_money, airtime, digital_wallet, paybill, buy_goods. An unrecognised value is dropped and the country's first channel is selected instead.
carrierCode
on-ramp / off-ramp
Mobile carrier to preselect, e.g. ng_mtn, ke_safaricom. Codes are on Supported countries and cryptocurrencies.
quoteId
on-ramp / off-ramp
A quote ID from Create quote, to show your own pricing and hold it through the widget.
Locking the user in
freezeAmount
on-ramp / off-ramp
Stops the user changing the amount. Requires amount.
freezeWallet
on-ramp
Stops the user changing the wallet. Requires address.
[Warning] In production you must be a verified merchant, and a valid signature must be present. Contact us for KYB.
hideSwitch
on-ramp / off-ramp
Hides the Buy/Sell toggle at the top.
Skipping screens
The full recipe is on Skipping screens.
on-ramp / off-ramp
Pre-fills the user's email on the auth screen.
at
on-ramp / off-ramp
Access token from Generate user auth tokens. Only takes effect together with rt.
rt
on-ramp / off-ramp
The matching refresh token. Required alongside at — either one alone is ignored.
requiredFields
on-ramp / off-ramp
URL-encoded JSON of the fieldsToCreateOrder values, so the order screen can be skipped. Needs quoteId. A field value containing a literal % is not supported.
flow
on-ramp / off-ramp
onramp or offramp. Mandatory on /auto-order.
[Warning] Without it, or with any other value, the widget discards every skip and drops the user on the on-ramp Amount screen with no error.
After the order
callbackUrl
on-ramp
Shows a "Back to website" link on the success page pointing here. Supports placeholders replaced with order data: {orderId}, {transactionHash}, {usdcAmount}, {airtimeAmount}, {network}, {address}. So https://example.com/success/{orderId}/{usdcAmount} becomes https://example.com/success/648b3095a9f38d8b7b2da748/5.45.
[Warning] URL-encode the value. Each placeholder is replaced once, so do not repeat a token in one URL, and a value that is unavailable renders as an empty string.
callbackBtnText
on-ramp
Label for that link. Defaults to "Back to website".
closeBtn
on-ramp
Label for a button on the success page. Omit it and no button appears. The button is display-only — clicking it does not notify an embedding page.
orderParams
on-ramp / off-ramp
Your own reference. Echoed back on the order, and on the primary webhook as merchantOrderParams (the legacy on-ramp and off-ramp webhook payloads name it orderParams).
Attribution
utm_source
on-ramp / off-ramp
Recorded on the order.
utm_medium
on-ramp / off-ramp
Recorded on the order.
utm_campaign
on-ramp / off-ramp
Recorded on the order.
Last updated