Supported widget parameters
Onramper provides a range of customization options for the widget, facilitated through parameters added as query strings to the widget integration URL.
Parameter | Type | Description |
---|---|---|
apiKey | string | The unique identifier provided by the Onramper team. |
mode | string | A comma-separated list of widget modes to support (e.g., buy,sell ). |
partnerContext | string | A unique string used to identify each session. |
successRedirectUrl | string | Specifies a redirect URL for successful transaction completion. |
failureRedirectUrl | string | Specifies a redirect URL for a failed transaction. |
defaultFiat | string | The default fiat currency is to be displayed. |
onlyFiats | string | The only fiat currencies to be displayed. |
excludeFiats | string | Fiat currencies that are to be excluded. |
defaultAmount | number | The default amount to be displayed (must be used with defaultFiat ). |
defaultCrypto | string | The default cryptocurrency is to be displayed. |
excludeCryptos | string | Cryptocurrencies to be excluded. |
onlyCryptos | string | The only cryptocurrencies to be displayed. |
excludeCryptoNetworks | string | Blockchain networks to be excluded. |
onlyCryptoNetworks | string | The only blockchain networks to be displayed |
defaultPaymentMethod | string | The default payment method is to be displayed. |
excludePaymentMethods | string | Payment Methods to be excluded. |
wallets | string | The wallet address(-es) to be passed to the widget. |
networkWallets | string | Multiple wallet addresses can be specified for use with all tokens that are supported by a single blockchain network. |
walletAddressTags | string | String of wallet address tags (destination tags/memos) that can be supplied to the widget |
supportRecurringPayments | boolean | Enable repeat payments (DCA). |
enableCountrySelector | boolean | Display the country selector. |
uuid | string | uuid to track the user’s session or device |
API Key
Your API key uniquely identifies you as a client — and it’s essential for configuring features like coverage, recommendations, webhook support, and other important settings.
With your API key added, your URL will look something like this:
https://buy.onramper.com/?apiKey=pk_prod_01HETEQF46GSK6BS5JWKDF31BT
Mode
The mode
parameter allows you to initialize the Onramper widget with multiple modes enabled. You can specify the modes as a comma-separated string when passing them to the widget.
https://buy.onramper.com?mode=buy
https://buy.onramper.com?mode=buy,sell
https://buy.onramper.com?mode=sell
https://buy.onramper.com?mode=buy,sell,swap
Partner Context
partnerContext
is a unique string used to identify each session. It must be a valid string format. This identifier will be included in every webhook payload and the response for each order retrieval request.
With the partnerContext
, the URL will look like this
https://buy.onramper.com?apiKey=pk_prod_01HETEQF46GSK6BS5JWKDF31BT&partnerContext=<partner_context>
Success Redirect URL
successRedirectUrl
specifies a URL for redirecting the user after a successful transaction completion. It's important to note that not all providers support this feature. Availability can be checked on the Feature support (per onramp). The URL should be URL-encoded.
https://buy.onramper.com?apiKey=pk_prod_01HETEQF46GSK6BS5JWKDF31BT&successRedirectUrl=https%3A%2F%2Fonramper.com%2F
Failure Redirect URL
failureRedirectUrl
specifies a URL for redirecting the user after a failed transaction. It's important to note that not all providers support this feature. Availability can be checked on the Feature support (per onramp). The URL should be URL-encoded.
https://buy.onramper.com?apiKey=pk_prod_01HETEQF46GSK6BS5JWKDF31BT&failureRedirectUrl=https%3A%2F%2Fonramper.com%2F
Default Fiat
Set a default fiat currency to be displayed using thedefaultFiat
https://buy.onramper.com?defaultFiat=USD
Only Fiats
Force one or multiple fiat currencies in your widget using onlyFiats
:
https://buy.onramper.com?onlyFiats=USD,EUR
Exclude Fiats
Omit certain fiat currencies with excludeFiats
:
https://buy.onramper.com?excludeFiats=USD,EUR
Default Amount
When used in conjunction with defaultFiat
, defaultAmount
will pre-populate the fiat currency input with your desired amount.
The URL below will default to a EUR amount of €125 whenever a user accesses your widget:
https://buy.onramper.com?defaultFiat=EUR&defaultAmount=125
Default Crypto
By default, the widget will use its recommendation algorithm to set the output currency, based on the most-used crypto in the user’s country.
However, you can override this with defaultCrypto
. Check out Crypto currencies to find your desired ID (please use the value from the Onramper ID
column).
https://buy.onramper.com/?defaultCrypto=ETH
Exclude Cryptos
Right out of the box, the Onramper widget makes all cryptocurrencies available.
Use excludeCryptos
if you want to remove some from your widget. Check out Crypto currencies to find your desired IDs (please use the values from the Onramper ID
column).
For instance, the example below makes ether and bitcoin unavailable to buy:
https://buy.onramper.com?excludeCryptos=BTC,ETH
Only Cryptos
If you only want a specific set of cryptos to be displayed, use onlyCryptos
.
Check out Crypto currencies to find your desired IDs (please use the values from the Onramper ID
column).
The string below ensures that only BTC and ETH can be bought through your widget:
https://buy.onramper.com?onlyCryptos=ETH,BTC
Exclude Crypto Networks
Similar to excludeCryptos
, excludeCryptoNetworks
allows you to remove entire crypto networks from the widget: Network IDs can be found from Crypto networks - please use the values from Onramper ID
column.
https://buy.onramper.com?excludeCryptoNetworks=bitcoin,ethereum
Only Crypto Networks
onlyCryptoNetworks
enables you to force the use of certain networks. Network IDs can be found from Crypto networks - please use the values from Onramper ID
column.
https://buy.onramper.com/?onlyCryptoNetworks=ethereum,polygon
Default Payment Method
Load your preferred payment method with defaultPaymentMethod
. You can find their Onramper IDs under Payment methods.
Below is an example of a URL that loads Bank Transfer:
https://buy.onramper.com/?defaultFiat=EUR&defaultAmount=200&defaultPaymentMethod=banktransfer
Exclude Payment Methods
Don’t want to show your users certain payment methods? Add excludePaymentMethods
to your string:
https://buy.onramper.com/?defaultFiat=EUR&excludePaymentMethods=creditcard
Wallets
The wallets
parameter allows you to pass a string containing wallet addresses to the widget.
Format-wise, each address should be a combination of the Token ID (also called Onramper ID
) and the wallet address, separated by a colon. For instance, the example below shows the string for a wallet on the Bitcoin network:
BTC:3FZbgi29cpjq2GjdwV8eyHuJJnkLtktZc5
Want to add multiple addresses? Just use the same format, separating each instance with a comma:
wallets=BTC:3FZbgi29cpjq2GjdwV8eyHuJJnkLtktZc5,ETH:0xb794f5ea0ba39494ce839613fffba74279579268
When passing the wallets
parameter, make sure to pass all wallets for the cryptocurrencies you have enabled using the onlyCryptos
parameter. Failure to do this will result in selectable tokens, requiring users to manually enter their wallet address
Remember, the URL itself should also incorporate a valid production API Key:
https://buy.onramper.com?wallets=BTC:3FZbgi29cpjq2GjdwV8eyHuJJnkLtktZc5,ETH:0xb794f5ea0ba39494ce839613fffba74279579268
Network Wallets
Want to pass a wallet that functions for multiple currencies or tokens on a network? For that, you’ll need networkWallets
. Provide a valid Onramper Network ID, followed by the wallet address:
The wallet address can be prefixed with any valid).
https://buy.onramper.com/?networkWallets=ETHEREUM:0xb794f5ea0ba39494ce839613fffba74279579268
Wallet Address Tags
The walletAddressTags
parameter allows you to pass a string of wallet address tags (destination tags/memos) that can be supplied to the widget.
Format-wise, each address should be a combination of the Token ID and the tag, separated by a colon.
https://buy.onramper.com/?wallets=xrp_ripple:rCoinaUERUrXb1aA7dJu8qRcmvPNiKS3d,xlm_stellar:0xb794f5ea0ba39494ce839613fffba74279579268&walletAddressTags=xrp_ripple:1234567890,xlm_stellar:1234567890
Repeat Payments
Onramper's feature for recurring cryptocurrency purchases allows users to set up plans for automatic crypto buying. To activate this feature, users should append supportRecurringPayments=true
as a query parameter in the URL. This addition enables the repeat payments functionality, offering a streamlined way for regular crypto investments.
https://buy.onramper.com/?supportRecurringPayments=true
Country Selector
Onramper's widget includes a feature enabling users to select their country to obtain a tailored quote. To activate this country selector, add enableCountrySelector=true
as a query parameter in the URL. This functionality provides a more personalized experience. However, it's important to note that there may be country-specific and geo-restrictions imposed by onramp services, potentially limiting the ability to proceed with transactions in certain regions.
https://buy.onramper.com/?enableCountrySelector=true
UUID
The uuid
parameter represents a unique identifier (UUID) that can be passed as a URL parameter. This UUID is expected to follow the standard UUID v4 format (xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx). If a valid uuid is provided, it will be stored in a browser cookie and used to track the user’s session or device.
https://buy.onramper.com/?uuid=e16ba042-9102-4b2c-a1b8-6095df3828da
Updated 6 days ago