Supported query parameters

The widget supports a number of configuration options defined using query parameters.

This page describes the following topics related to the Trade Widget supported query parameters:

• List and description of supported query parameters
• Improving Trade Widget UX by passing specific query parameters
• How to use:
  • address query parameter
  • addressSignature query parameter
  • transferInMedia and transferOutMedia query parameters

🚧

URL Encoding the query parameters:

Every provided query parameter has to be URL encoded. E.g. using encodeURIComponent(yourParameter) in JS.

Parameter	Description
partnerId	id you got from Coinify
partnerName	name to be displayed in the widget as partner name, currently used when displaying partner fee if enabled, defaults to 'Partner'. Can be string or object (just has be be provided as url encoded string, see example)
partnerContext	Free context for partners to receive in webhooks , can be stringified JSON as well. Partner context may also be provided using settings.partner-context-changed
primaryColor	color of the primary button; Accepted: named value e.g. blue, hash value e.g. #00ff00, or rgba(0,255,0,1)
themeMode	enables you to set the Trade Widget theme to light or dark. If not specified, defaults to light.
cryptoCurrencies	comma separated list of crypto currencies to support in the widget. Will include only the listed crypto currencies from those supported by default
fiatCurrencies	comma separated list of fiat currencies to support in the widget. Will include only the listed fiat currencies from those supported by default
defaultCryptoCurrency	defines the crypto currency initially selected on Buy/Sell quotes if multiple crypto currencies are available
defaultFiatCurrency	defines the fiat currency initially selected on Buy/Sell quotes if multiple fiat currencies are available
buyAmount	defines initial amount on Buy quotes. Note, often used with targetPage, defaultCryptoCurrency, and defaultFiatCurrency defined
sellAmount	defines initial amount on Sell quotes. Note, often used with targetPage, defaultCryptoCurrency, and defaultFiatCurrency defined
isBuyAmountFixed	If set to true, the specified buyAmount is locked and cannot be changed from the Trade Widget UI. Accepts true or false values.
isSellAmountFixed	If set to true, the specified sellAmount is locked and cannot be changed from the Trade Widget UI. Accepts true or false values.
isBuyAmountWithFees	If set to true, the provided buyAmount will include all the fees and the buyAmount will be the amount the end-user will spend. Accepts true or false values.
isSellAmountWithFees	If set to true, the provided sellAmount will include all the fees and the sellAmount will be the amount the end-user will spend. Accepts true or false values.
address	defines default wallet address to receive funds at when buying crypto currencies, and default wallet address to refund funds to when selling crypto currencies in case the sell cannot be completed. See details on how to use address below.
addressSignature	provides HMAC-SHA-256 signature for address. Only used if a shared secret has been established with Coinify. See details on how to use address below.
walletType	If this value is not provided via the query parameter, the customer has to provide it on the Trade Widget. Available values: self_hosted - provide this value when you know the user is sending the purchased crypto to their own wallet. vasp - provide this value when you know the user is sending the purchased crypto to a wallet managed/hosted by a 3rd party like a Centralised Exchange. See how to use walletType below.
confirmMessages	defines if external confirmation of trade messages is required. When provided the widget will await confirmation messages from hosting window before continuing flow. See details on how to use messages below.
memo	defines an optional memo/destination tag accepted by some crypto currencies. See details on how to use address below.
noSignup	defines whether to support signup through the widget. Note the negation! Available values are 'false' (allow signup for corporate & individuals), 'true' (allow no signup), 'corporate' (allow signup only for individual traders) and 'individual' (allow signup only for corporate traders).
targetPage	defines a target landing page other than the default. Available values are 'login', 'signup', 'signup-corporate', 'buy', 'sell' and 'trade-history'
refreshToken	used for custom onboarding flows. The refeshTokencan be obtained by calling one of the auth endpoints . The refreshToken should be URL encoded so that the browsers interprets it correctly.
transferInMedia	list of transfer media for inbound payment method . Available: card, bank, blockchain. See details on how to use .
transferOutMedia	list of transfer media for outbound payment method . Available: bank, blockchain. See details on how to use below.
returnURL	the URL that you want to redirect the customer to upon successfuly completed trade. The provided URL must be url-encoded. ***Note that this query parameter is only available for the Customised Landing Page URL *** .

Providing these parameters can only remove options from the user's view. There may be reasons (e.g legal or contractual) that some options are not available to your users in the underlying API. Adding parameters here will not change that.

📘

Info:

In general the widget will adjust to only present what makes sense with the given parameters (e.g. remove the Sell option if only Buy related transferInMedia are found). It is currently possible to specify parameters that result in an invalid configuration. If you experience a blank widget, try to remove some parameters.

Improve Trade Widget UX by passing query parameters

By passing some of the parameter values in the Trade Widget URL, specific Trade Widget UI screens will be skipped, effectively simplifying the customer's flow. Please find detailed explanation of which UI screens are skipped based on the provided parameters:

Query Parameter	Description
transferInMedia	Providing this parameter will set the payment method accordingly and the customer will not have to select the payment method again on Coinify's Trade Widget.
buyAmount; defaultFiatCurrency; defaultCryptoCurrency	If these parameters are provided together, the Quote page will be skipped.
address	Providing this parameter will skip the screen where the customer is asked to provide the receiving crypto address.

If you're already collecting any of these datapoints on your end, it is recommended to pass them as Trade Widget query parameters for a more seamless customer experience. We encourage you to test the flow yourself to get a better understanding of the flow with and without providing these parameters.

How to use address

The address parameter should be provided in the format currency1:address1,currency2:address2,... to specify the default wallet address per cryptocurrency. Alternatively, if the widget is configured to have only a single currency, you may provide only the address and omit the currency. See examples:

Provide the default receiving crypto wallet address for multiple cryptocurrencies, example:

<iframe src="...?address=BTC:2N7gzbQsDnfAFdwabcFqyw1Q8y1ZUpeqUgD,ETH:0x44eae1E05F5f294f0f2a054D16605993FCd627a9&..." />

Provide the default receiving crypto wallet address for a single cryptocurrency, example:

<iframe src="...?cryptoCurrencies=BTC&address=2N7gzbQsDnfAFdwabcFqyw1Q8y1ZUpeqUgD&..." />

📘

Good to know:

When Buying a cryptocurrency the address provided for the currency is used to pre-fill the receiving wallet address input field. Equally, when Selling, the address is used to pre-fill the refund wallet address input field. (Note, some cryptocurrencies do not require a refund address to be provided). Buying or Selling currencies with no default address specified will require the end-user to manually enter the wallet address.

How to use addressSignature

❗️

Important:

For improved security, it is recommended to use the addressSignature parameter if you've set your system to provide the default receiving address.

Share a UUID format secret with Coinify via a secure channel to enable this feature. Once enabled, our system will refuse to create trades whose addresses do not have a valid signature.

In order to ensure that the address passed into the widget has not been tampered with, you have the to sign the address(es) using a shared secret, and passing the signature to the widget as well.

addressSignature follows the same format as the address parameter described above:

• Single currency format:
  • addressSignature=<sig>
    • ...?cryptoCurrencies=BTC&address=2N7gzbQsDnfAFdwabcFqyw1Q8y1ZUpeqUgD&addressSignature=<sig>
• Multiple currencies format:
  • addressSignature=BTC:<btcSig>,ETH:<ethSig>
  • ...?address=BTC:<btcAddr>,ETH:<ethAddr>&addressSignature=BTC:<btcSig>,ETH:<ethSig>

Address signature is an opt-in feature, and requires you to establish a shared secret with Coinify for the HMAC-SHA-256 signature.

Memo

Some crypto currencies accept a memo/destination tag in addition to the wallet address. The value for this can be specified in the memo query parameter.

Memo follows the same format as the address and addressSignature parameters, see examples above.

JavaScript example code for generating a signature from the shared secret and address

JavaScript

const crypto = require('crypto');

const address = 'crypto-address';
const secret = 'shared-secret';

const accountSignature = crypto.createHmac('SHA256', secret).update(address).digest('hex');

How to use walletType

Similar to providing the address, providing walletType differs depending on if you're passing values for one or multiple cryptocurrency wallets.

If multiple cryptocurrencies are being specified, the walletType parameter should be provided in the format currency1:walletType1,currency2:walletType2,... to specify the wallet type per each cryptocurrency you pass to the trade widget. Alternatively, if the widget is configured to have only a single currency, you may provide only one value for the walletType parameter and omit the currency. See examples:

Provide the default receiving crypto wallet type for a single cryptocurrency, example:

<iframe src="...?cryptoCurrencies=BTC&address=2N7gzbQsDnfAFdwabcFqyw1Q8y1ZUpeqUgD&walletType=self_hosted..." />

Provide the default receiving crypto wallet address for multiple cryptocurrencies, example:

<iframe src="...?walletType=BTC:vasp,ETH:vasp&..." />

📘

If the walletType is not specified, the customer will have to provide it on the Trade Widget.

If you are a VASP/CASP hosting wallets/addresses which receive the assets purchased by your end-users via Coinify Trade Widget, then you can pass vasp.

If you are unsure whether the end-user is sending funds to their own wallet or to a VASP/CASP, then leave it to the customer to specify.

❗️

The walletType must be correct for a trade to succeed.