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:
addressquery parameteraddressSignaturequery parametertransferInMediaandtransferOutMediaquery 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) |
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 ony 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. |
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. |
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 below. |
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
transferInMediaare 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
addressThe 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:
<iframe src="...?address=BTC:2N7gzbQsDnfAFdwabcFqyw1Q8y1ZUpeqUgD,ETH:0x44eae1E05F5f294f0f2a054D16605993FCd627a9&..." />
<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
addressSignatureImportant:
For improved security, it is recommended to use the
addressSignatureparameter if you've set your system to provide the default receivingaddress.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>
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
addressconst crypto = require('crypto');
const address = 'crypto-address';
const secret = 'shared-secret';
const accountSignature = crypto.createHmac('SHA256', secret).update(address).digest('hex');