🔗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, also known as the public key.

• signature: Your HMAC-SHA256 signature of the full query string, base64-encoded.

Optional Parameters

• email: Pre-fills the customer's email address on the login page.

• customerKYC: The level of Know Your Customer (KYC) verification.

  • 0 = the customer has not completed KYC.

  • 1 = the customer has completed Proof of ID + Liveness Check.

  • 2 = 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.

• externalCustomerId: Your unique identifier for the customer.

• baseCountry: User's ISO country code. Used to determine available payout methods. See supported countries for the full list.

• method: The method the user will receive their payout in. (e.g. bank transfer, Skrill) A full list of supported methods can be found here.

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

• userSendsFunds=false: This parameter enables merchants to send crypto on behalf of their users. Must be set to false, will default to True.

• fiatCurrencyCode: Fiat payout currency (e.g. EUR, USD). Required for userSendsFunds=false flow.

• cryptoCurrencyCode: The crypto the user is selling (e.g. BTC, ETH). Required for userSendsFunds=false flow.

• cryptoCurrencyAmount : Locks the cryptocurrency amount to be sent. Required for userSendsFunds=false flow.

• fiatCurrencyAmount: Locks the fiat amount the user will receive. Required for userSendsFunds=false flow.

Note: Only one of the following must be passed. If cryptoCurrencyAmount and fiatCurrencyAmount both are passed, cryptoCurrencyAmount will take precedence.

---

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';

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

// 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 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';

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

// 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);

---

iFrame Embed Example

<iframe allow="accelerometer; autoplay; camera; encrypted-media; gyroscope; payment; clipboard-read; clipboard-write" src="https://widget.swapped.com/sell?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>

---

Order Status Flow

payment_pending → order_processing → payout_pending → order_completed                ↘ order_cancelled

Status Definitions:

payment_pending: Awaiting the user’s crypto deposit.

order_processing: Crypto detected, awaiting blockchain confirmation.

payout_pending: Crypto has been confirmed on the blockchain, and the payout to the user is pending.

order_completed: Crypto received and fiat sent to the user.

order_cancelled: Order cancelled (may include a refund if crypto was sent).

Iframe Order Data Event

The order data will be posted from the iframe when the user presses continue from the payout summary.

If you'd like to allow your frontend access to the order data, you can check for order data events like so:

window.addEventListener('message', function (event) {
  // Verify origin
  if (event.origin !== 'https://widget.swapped.com') return

  const { type, data } = event.data
  if (type === 'SWAPPED_ORDER_DATA') {
    console.log('New order data:', data)
    // Optional: Update your UI
  }
})

All messages are wrapped like this:

{
  type: 'SWAPPED_ORDER_DATA',
  data: {
    crypto: "BTC",
    network: "mainnet",
    amount: "0.001",
    address: "0x...",
    order_id: "ord_123456",
    timestamp: 1643723400000
  }
}

Data:

interface OrderPostMessageData {
    crypto: string       // e.g., "BTC", "ETH", "USDC"
    network: string      // e.g., "mainnet"
    amount: string       // Amount in crypto
    address: string      // Wallet address (may be blank)
    order_id: string     // Unique order ID
    timestamp: number    // Unix timestamp of event
}

Sending payments on behalf of users

This flow enables merchants to initiate and send crypto on behalf of their users, streamlining the off-ramp experience.

Flow:

1. The user enters payout details in the Swapped widget.

2. The user sees an order summary showing the expected fiat amount.

3. The user confirms, creating the order.

4. Swapped sends a callback to the merchant with order details.

5. The merchant sends the specified crypto amount to Swapped.

6. Swapped waits for the required blockchain confirmations (varies by crypto and network, see here for the full list).

7. Once confirmed, Swapped sends the fiat to the user.

8. The widget displays a final confirmation based on the actual crypto received.