Documentation
Widget URL Structure

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.

Search Parameters

ParameterKeyAllowed ValuesRequiredDescription
Partner Keypartner_keyYour unique partner keyYes
From AmountaFloat (>= 50 EUR equivalent)NoAmount to exchange from.
From Currency TickerpFiat ticker from the APINoTicker symbol of the source currency.
To Currency TickercCrypto ticker from the APINoTicker symbol of the target currency.
To Currency NetworknCrypto network from the API (if applicable)NoNetwork for the target currency.
Prefilled Wallet Addresswallet_addressWallet address for provided crypto ticker & networkif sign is providedThe wallet address to prefill
Prefilled Wallet Extrawallet_extraWallet extra (e.g., destination tag, memo, etc.) for the specified crypto ticker and networkDepends on crypto-assetThe wallet extra to prefill
Prefilled Wallet SignsignSigned wallet address or wallet address and extraif wallet_address is providedHMAC-SHA256 from (wallet+extra) and secret
Page UI Hiddenpage_uihiddenNoHide the header and footer on the widget page.
Hide Feeshide_feestrue / falseNoHide fees in the widget.

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.