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.

Query 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
External IDexternal_idUUID, 36 characters longNoExternal ID used to uniquely identify the transaction through API or Webhooks. Generated by you for reference purposes.
Page UI Hiddenpage_uihiddenNoHide the header and footer on the widget page.
Hide Feeshide_feestrue / falseNoHide fees in the widget.
Hide Logohide_logotrue / falseNoHide the logo in the widget.
Hide Support Chat Buttonchat_button_hiddentrue / falseNoHide the support chat button in the widget.
Page Background Colorpage_bgHex color code (3 or 6 characters), e.g., 000, FFF, 000000, FFFFFFNoBackground 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