> For the complete documentation index, see [llms.txt](https://docs.swapped.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapped.com/swapped-ramp/off-ramp-integration/iframe-initialization.md).

# iFrame initialization

## Required Parameters

* <mark style="color:red;">`apiKey`</mark>: Your publishable API key, also known as the public key.
* <mark style="color:red;">`signature`</mark>: Your HMAC-SHA256 signature of the full query string, base64-encoded.

## Optional Parameters

* <mark style="color:red;">`email`</mark>: Pre-fills the customer's email address on the login page.
* <mark style="color:red;">`customerKYC`</mark>: The level of Know Your Customer (KYC) verification.
  * 0 = the customer has not completed KYC.&#x20;
  * 1 = the customer has completed Proof of ID + Liveness Check.&#x20;
  * 2 = the customer has completed Proof of ID + Liveness Check + Proof of Address.
* <mark style="color:red;">`externalCustomerId`</mark>: Your unique identifier for the customer.
* <mark style="color:red;">`baseCountry`</mark>: User's ISO country code. Used to determine available payout methods. See [supported countries](/swapped-ramp/endpoints/misc.-endpoints/get-supported.md) for the full list.
* <mark style="color:red;">`method`</mark>: The method the user will receive their payout in. (e.g. bank transfer, Skrill) A full list of supported methods can be found [here](/swapped-ramp/off-ramp-integration/supported-payout-methods.md).&#x20;
* <mark style="color:red;">`minAmount`</mark>: Sets the minimum order amount in EUR. This cannot be lower than 7 EUR.
* <mark style="color:red;">`userSendsFunds=false`</mark>: This parameter enables merchants to send crypto on behalf of their users. Must be set to false, will default to True.
* <mark style="color:red;">`fiatCurrencyCode`</mark>: Fiat payout currency (e.g. EUR, USD). Required for <mark style="color:red;">`userSendsFunds=false`</mark> flow.&#x20;
* <mark style="color:red;">`cryptoCurrencyCode`</mark>: The crypto the user is selling (e.g. BTC, ETH). Required for <mark style="color:red;">`userSendsFunds=false`</mark> flow.&#x20;
* <mark style="color:red;">`cryptoCurrencyAmount`</mark> : Locks the cryptocurrency amount to be sent. Required for <mark style="color:red;">`userSendsFunds=false`</mark> flow.
* <mark style="color:red;">`fiatCurrencyAmount`</mark>: Locks the fiat amount the user will receive. Required for <mark style="color:red;">`userSendsFunds=false`</mark> flow.
* <mark style="color:red;">`submerchant`</mark>: Submerchant identifier for multi-tenant setups

**Note:** Only one of the following must be passed. If <mark style="color:red;">`cryptoCurrencyAmount`</mark> and <mark style="color:red;">`fiatCurrencyAmount`</mark> both are passed, <mark style="color:red;">`cryptoCurrencyAmount`</mark> will take precedence.&#x20;

***

### Example with PHP

{% code overflow="wrap" %}

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

{% endcode %}

### Example with NodeJS

{% code overflow="wrap" %}

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

{% endcode %}

***

### iFrame Embed Example

{% code overflow="wrap" %}

```html
<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>

```

{% endcode %}

***

### Order Status Flow&#x20;

`payment_pending → order_processing → payout_pending → order_completed`\
                                  `↘ order_cancelled`

**Status Definitions:**&#x20;

<mark style="color:blue;">`payment_pending`</mark>: Awaiting the user’s crypto deposit.

<mark style="color:blue;">`order_processing`</mark>: Crypto detected, awaiting blockchain confirmation.

<mark style="color:blue;">`payout_pending`</mark>: Crypto has been confirmed on the blockchain, and the payout to the user is pending.

<mark style="color:blue;">`order_completed`</mark>: Crypto received and fiat sent to the user.

<mark style="color:blue;">`order_cancelled`</mark>: 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:

```javascript
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:

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

#### Data:

```typescript
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](/swapped-ramp/off-ramp-integration/cryptocurrencies-and-confirmations.md) 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.swapped.com/swapped-ramp/off-ramp-integration/iframe-initialization.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.