🔗iFrame initialization

Need help with your integration? Click here to chat with our custom GPT for instant answers.

Required Parameters

• apiKey: Your publishable API key for customer and transaction assignment. Also known as the public key.

• currencyCode: The cryptocurrency code (e.g., BTC, ETH, BCH) for purchase. See Supported Cryptocurrencies for more options. If multiple walletAddress are set, this will be the default cryptocurrency.

• walletAddress: The destination cryptocurrency wallet address for purchased funds.

  • If using one address it'll look like this: walletAddress=ltc1q2k0xaafhgt3s8qw03wmajjmlc8gcepdy0un0ah

  • If you want to accept multiple currencies, for example, Bitcoin, Litecoin, and Dogecoin, format the walletAddress parameter as follows: walletAddress=BTC:yourBitcoinAddress,LTC:yourLitecoinAddress,DOGE:yourDogecoinAddress

If you want to accept multiple currencies, for example, Bitcoin, Litecoin, and Dogecoin, format the walletAddress parameter as follows: walletAddress=BTC:yourBitcoinAddress,LTC:yourLitecoinAddress,DOGE:yourDogecoinAddress

Optional Parameters

• language: Specify the widget's language using an ISO 639 Set 1 code. The language will default to EN (English) if the parsed language is not supported. All supported languages can be found here.

• method: Specify the payment method that will be pre-selected upon opening the widget. You'll have to use the slug mentioned here e.g. method=apple-pay . If the provided method is not available in the user's geo, the default method will be selected instead.

• baseCurrencyCode: The fiat currency code for transactions (e.g., USD, EUR, GBP). See Supported Fiat currencies for more options.

• lockBaseCurrency: (True/False) Locks the currency selection to the provided baseCurrencyCode. This prevents the user from making payments in other currencies and will remove payment methods where the provided currency is unsupported.

• baseCurrencyAmount: The fiat currency amount to be spent, in integer form. 2 decimals max. Cannot be zero if set.

• quoteCurrencyAmount: The cryptocurrency amount to be purchased, in integer form. 3 decimals max. Minimum 7 EUR and 8 USD equivalent of the given crypto.

• email: Prefills the customer's email address on the login page.

• externalCustomerId: Your unique identifier for the customer.

• redirectUrl: The URL for redirection after purchase completion. Must be URLencoded, e.g. https%3A%2F%2Fwebhook.site You may include dynamic order information by using the following variables in your URL:

  • {orderId} - Will be replaced with the actual order ID

  • {orderStatus} - Will be replaced with the final status of the order

Examples of how the parameter can be used:

Without variables:

redirectUrl=https%3A%2F%2Fwebhook.site

With variables:

redirectUrl=https%3A%2F%2Fwebhook.site%2FSwapped%3ForderId%3D%7BorderId%7D%26orderStatus%3D%7BorderStatus%7D

• responseUrl: When creating an order, you can specify a webhook URL through this parameter - it must be URLencoded (e.g., https%3A%2F%2Fwww.myurl.com). Additionally, you can define a global callback URL via the Swapped.com dashboard to receive order notifications for all your orders.

• customerKYC: The level of Know Your Customer (KYC) verification. customerKYC = 0 means the customer has not completed KYC. customerKYC = 1 means the customer has completed Proof of ID + Liveness Check. customerKYC = 2 means the customer has completed Proof of ID + Liveness Check + Proof of Address.

• style: The Styling ID and widget customization options can be configured on the “Widget Customizations” page within the Swapped.com Dashboard.

• destinationTag: Adds a numeric destination tag (XRP) or text memo (TON) to identify specific recipients or provide transaction context.

• coverFees: (True/False) Sets processing and handling fees to zero for the customer. Fees will be included through the spread.

• minAmount: Sets the minimum order amount in EUR. This cannot be lower than 7 EUR.

• lockAmount: (True/False) Locks the fiat and crypto fields for the user.

• baseCountry: (ISO) The country code for the user's location. This is used to determine the payment methods available to the user. See supported countries for more options. Note that if lockAmount is set to true, the country will not be changeable by the user.

Server-Side URL Signature

Generate a signature to prevent the URL from being modified. This is done using the query string, including '?' and the secret key shared with you.

Example with NodeJS

// Import the crypto module.
import crypto from 'crypto';

// Define the public API key.
const publicKey = 'your_public_key';

// Define the secret API key.
const secretKey = 'your_secret_key';

// Define the currency code.
const currencyCode = 'currency_code';

// Define the wallet address.
const walletAddress = 'your_wallet_address';

// Build URL with query parameters.
const originalUrl = `https://widget.swapped.com?apiKey=${publicKey}&currencyCode=${currencyCode}&walletAddress=${walletAddress}`;

// Create a SHA-256 HMAC signature from the URL's search string, then encode in Base64.
const signature = crypto.createHmac('sha256', secretKey).update(new URL(originalUrl).search).digest('base64');

// Append the URL-encoded signature to the original URL.
const urlWithSignature = `${originalUrl}&signature=${encodeURIComponent(signature)}`;

// Output the final URL with the signature appended.
console.log(urlWithSignature);

Example with PHP

<?php

// Define the public API key.
$publicKey = 'your_public_key';

// Define the secret API key.
$secretKey = 'your_secret_key';

// Define the currency code.
$currencyCode = 'currency_code';

// Define the wallet address.
$walletAddress = 'your_wallet_address';

// Build URL with query parameters.
$originalUrl = "https://widget.swapped.com?apiKey={$publicKey}&currencyCode={$currencyCode}&walletAddress={$walletAddress}";

// Parse the URL into its components.
$parsedUrl = parse_url($originalUrl);

// Create a SHA-256 HMAC signature from the query string, then encode in Base64.
$signature = base64_encode(hash_hmac('sha256', '?'.$parsedUrl['query'], $secretKey, true));

// Append the URL-encoded signature to the URL.
$urlWithSignature = "{$originalUrl}&signature=" . urlencode($signature);

// Output the final URL with the signature appended.
echo $urlWithSignature;

Example iFrame URL

Note: this is a test key, your key will be different.

https://widget.swapped.com/?apiKey=pk_sandbox_rT9bW3sN6mJ8F5hP2cRqLvZ7SaD4XoY9&walletaddress=ltc1q2k0xaafhgt3s8qw03wmajjmlc8gcepdy0un0ah&signature=RyvwgGPnBBfP2VwKz1beHveU4%2BTjPIwRYNj0s6hKNVU%3D

Example iFrame

The iFrame has been optimized for height: 585px; width: 445px;.

<iframe allow="accelerometer; autoplay; camera; encrypted-media; gyroscope; payment; clipboard-read; clipboard-write" src="https://widget.swapped.com?apiKey={pk_live_key}&currencyCode=btc&signature=lorem" title="Buy crypto with Swapped" style="height: 585px; width: 445px; border-radius: 
0.75rem; margin: auto;"></iframe>