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. |
Examples
Simple Referral link
Simple referral link:
https://widget.finchpay.io?partner_key=YOUR_PARTNER_KEYWith 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_KEYWith 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.