> For the complete documentation index, see [llms.txt](https://docs.fonbnk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fonbnk.com/widget-integration/url-params.md). # URL params Every query parameter that configures the Pay Widget. The Pay Widget is configured through URL query parameters. {% hint style="warning" %} **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`, `/kyc/login` — sends the user back to the start if it is missing, discarding the rest of your parameters. {% endhint %} ### Identity | Parameter | Flows | Description | | --------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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](/widget-integration/signing-the-url.md). ### What to buy or sell | Parameter | Flows | Description | | --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/supported-countries-and-cryptocurrencies.md). | | quoteId | on-ramp / off-ramp | A quote ID from [Create quote](/server-to-server/api-endpoints/create-quote.md), to show your own pricing and hold it through the widget. | ### Locking the user in | Parameter | Flows | Description | | ------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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](/widget-integration/skipping-screens.md). | Parameter | Flows | Description | | -------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | email | on-ramp / off-ramp | Pre-fills the user's email on the auth screen. With `kycType` it is locked, and the user cannot type another address. | | at | on-ramp / off-ramp | Access token from [Generate user auth tokens](/server-to-server/api-endpoints/generate-user-auth-tokens.md). **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.

| ### Hosted KYC These open a KYC check with no order behind it. You do not build the URL yourself: [Get user KYC state](/server-to-server/api-endpoints/get-user-kyc-state.md) returns a ready link per tier in `kycUrls`, and the values below are inside its signature. The flow is on [KYC flow](/server-to-server/kyc-flow.md). | Parameter | Flows | Description | | --------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | kycType | KYC | `basic` or `advanced`, lower case. It makes that tier required even though no order asks for one, and it is what puts the login screen in hosted mode. A country rule that asks for more still wins, so `basic` in a country we verify only at the advanced tier comes back as advanced. | ### After the order | Parameter | Flows | Description | | --------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | callbackUrl | on-ramp / KYC |

Shows a "Back to website" link pointing here. On the on-ramp success page it supports placeholders replaced with order data: {orderId}, {transactionHash}, {usdcAmount}, {airtimeAmount}, {network}, {address}. So becomes .
On the hosted KYC page there is no order, so no placeholder is replaced and the link appears once the user has submitted a check.
\[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 / KYC | 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 | Parameter | Flows | Description | | ------------- | ------------------ | ---------------------- | | 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. | {% hint style="info" %} `orderParams` is the field to reconcile against — it comes back on the [webhook](/server-to-server/webhooks.md) and is queryable on [Get order](/server-to-server/api-endpoints/get-order.md). The UTM params are for your own analytics. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.fonbnk.com/widget-integration/url-params.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.