Widget URL Structure

Introduction

Our service uses a simple URL structure to pre-fill the values you need to pass. Below, you will find a list of parameters and their corresponding keys that you can utilize to construct custom exchange URLs.

Query Parameters

Parameter	Key	Allowed Values	Required	Description
Partner Key	`partner_key`	Your unique partner key	Yes	–
From Amount	`a`	Float (>= 50 EUR equivalent)	No	Amount to exchange from.
From Currency Ticker	`p`	Fiat ticker from the API	No	Ticker symbol of the source currency.
To Currency Ticker	`c`	Crypto ticker from the API	No	Ticker symbol of the target currency.
To Currency Network	`n`	Crypto network from the API (if applicable)	No	Network for the target currency.
Prefilled Wallet Address	`wallet_address`	Wallet address for provided crypto ticker & network	if `sign` is provided	The wallet address to prefill
Prefilled Wallet Extra	`wallet_extra`	Wallet extra (e.g., destination tag, memo, etc.) for the specified crypto ticker and network	Depends on crypto-asset	The wallet extra to prefill
Prefilled Wallet Sign	`sign`	Signed wallet address or wallet address and extra	if `wallet_address` is provided	HMAC-SHA256 from (wallet+extra) and secret
External ID	`external_id`	UUID, 36 characters long	No	External ID used to uniquely identify the transaction through API or Webhooks. Generated by you for reference purposes.
Page UI Hidden	`page_ui`	`hidden`	No	Hide the header and footer on the widget page.
Hide Fees	`hide_fees`	`true` / `false`	No	Hide fees in the widget.
Hide Logo	`hide_logo`	`true` / `false`	No	Hide the logo in the widget.
Hide Support Chat Button	`chat_button_hidden`	`true` / `false`	No	Hide the support chat button in the widget.
Page Background Color	`page_bg`	Hex color code (3 or 6 characters), e.g., `000`, `FFF`, `000000`, `FFFFFF`	No	Background color for the widget page.

Examples

Simple Referral link

Simple referral link:

https://widget.finchpay.io?partner_key=YOUR_PARTNER_KEY

With amount and currency

Pre-filled amount, from currency and to currency:

https://widget.finchpay.io/payment_method?a=564.33&p=EUR&c=MATIC&n=ETH&partner_key=YOUR_PARTNER_KEY

With prefilled Wallet Address (optional Wallet Extra)

To generate a signature, use HMAC-SHA256 with the wallet, an optional extra, and the secret key.

Here's the pseudocode for the approach:

Without extra: HMAC-SHA256(wallet_address, secret)
With extra: HMAC-SHA256((wallet_address + wallet_extra), secret)

Here is JavaScript/TypeScript code snippet to obtain sign:

const CryptoJS = require('crypto-js');
 
const getSign = (walletAddress, walletExtra, secret) => {
    const payload = [walletAddress, walletExtra].join('');
    return CryptoJS.HmacSHA256(payload, secret).toString(CryptoJS.enc.Hex);
};
 
getSign("wallet_addr", "extra", "your_secret_key");

If no extra is provided, add wallet_address and sign to the URL:

https://widget.finchpay.io/payment_method?a=564.33&p=EUR&c=MATIC&n=ETH&wallet_address=ETH_MATIC_WALLET_ADDRESS&sign=GENERATED_SIGN&partner_key=YOUR_PARTNER_KEY

If you have provided wallet_extra, include it in the URL:

https://widget.finchpay.io/payment_method?a=564.33&p=EUR&c=MATIC&n=ETH&wallet_address=ETH_MATIC_WALLET_ADDRESS&wallet_extra=THE_WALLET_EXTRA&sign=GENERATED_SIGN&partner_key=YOUR_PARTNER_KEY

⚠️

For wallet address pre-filling, to ticker, to network (if needed), wallet address, and sign parameters are required.

Interactive URL Builder

Try our URL builder to generate URLs that suit your requirements or use it as a reference guide.

💻 Partner URL Builder

Embeddable Calculator Telegram WebApp