> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rampnow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget Mode Integration

> Embed Rampnow directly into your application for a seamless user experience

<Note>
  Widget Mode keeps users on your platform throughout the entire transaction flow via iframe or redirect.
</Note>

## Overview

Widget Mode allows you to embed Rampnow's on-ramp and off-ramp services directly into your application. Users complete transactions within an overlay or iframe without ever leaving your platform.

<div style={{display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '1rem'}}>
  <Card title="iFrame or Redirect" icon="code-branch">
    Choose between **iFrame** (embedded) or **Redirect** mode
  </Card>

  <Card title="Quick Setup" icon="bolt">
    Get started in minutes with URL parameters
  </Card>

  <Card title="All Payment Methods" icon="credit-card">
    Support for all available Rampnow payment modes
  </Card>

  <Card title="Customizable" icon="sliders">
    Pre-fill amounts, currencies and wallet addresses
  </Card>
</div>

<Tip>
  Want programmatic control with event handling and TypeScript support? Use the [Rampnow SDK](/api-reference/sdk) instead — it wraps Widget Mode with a developer-friendly API and a React hook.
</Tip>

***

## URL Parameters

Configure the widget by passing parameters in the URL:

| Parameter          | Required     | Default                               | Description                                                                     |
| ------------------ | ------------ | ------------------------------------- | ------------------------------------------------------------------------------- |
| `apiKey`           | **Required** | —                                     | Your unique API key from the [Partner Dashboard](https://partner.rampnow.io)    |
| `orderType`        | Optional     | `buy`                                 | Transaction type: `buy` or `sell`                                               |
| `srcChain`         | **Required** | `buy`: `fiat`<br />`sell`: `ethereum` | Source chain for the asset user is spending                                     |
| `srcCurrency`      | Optional     | `buy`: `EUR`<br />`sell`: `ETH`       | Currency user is spending (fiat for buy, crypto for sell)                       |
| `srcAmount`        | Optional     | `100`                                 | Amount in source currency                                                       |
| `dstCurrency`      | Optional     | `buy`: `ETH`<br />`sell`: `EUR`       | Currency user receives (crypto for buy, fiat for sell)                          |
| `dstChain`         | **Required** | `buy`: `ethereum`<br />`sell`: `fiat` | Destination chain for received currency                                         |
| `paymentMode`      | Optional     | Lowest fee                            | Payment method: `card`, `google_pay`, `apple_pay`, `open_banking`, `sepa`, etc. |
| `walletAddress`    | Optional     | —                                     | User's crypto wallet address                                                    |
| `walletAddressTag` | Optional     | —                                     | Wallet tag/memo for supported chains (XRP, XLM, etc.)                           |
| `externalOrderId`  | Optional     | —                                     | Your internal order ID for tracking                                             |

***

## iFrame Mode

Embed the widget directly on your page for a seamless experience.

<Steps>
  <Step title="Create Container">
    Add a container element in your HTML:

    ```html theme={null}
    <div id="ramp-container"></div>
    ```
  </Step>

  <Step title="Construct Widget URL">
    Build your URL with the required parameters:

    ```
    https://app.rampnow.io/order/quote?apiKey=YOUR_API_KEY&srcCurrency=EUR&srcAmount=250&dstCurrency=BTC&dstChain=bitcoin&walletAddress=0xYourWalletAddress
    ```
  </Step>

  <Step title="Initialize iFrame">
    Embed the widget using an iframe:

    ```html theme={null}
    <iframe 
      src="https://app.rampnow.io/order/quote?apiKey=YOUR_API_KEY&srcCurrency=EUR&srcAmount=250&dstCurrency=BTC&dstChain=bitcoin&walletAddress=0xYourWalletAddress" 
      title="Rampnow Widget"
      width="100%"
      height="600px"
      frameborder="0"
      allow="payment">
    </iframe>
    ```
  </Step>
</Steps>

<Tip>
  The widget will be embedded inside your container, providing an in-page experience for users.
</Tip>

***

## Redirect Mode

Redirect users to Rampnow's hosted page for a simpler integration.

<Steps>
  <Step title="Construct Widget URL">
    Build your URL with the required parameters:

    ```
    https://app.rampnow.io/order/quote?apiKey=YOUR_API_KEY&srcCurrency=EUR&srcAmount=250&dstCurrency=BTC&dstChain=bitcoin&walletAddress=0xYourWalletAddress
    ```
  </Step>

  <Step title="Redirect User">
    Redirect the user to the constructed URL:

    ```javascript theme={null}
    window.location.href = "https://app.rampnow.io/order/quote?apiKey=YOUR_API_KEY&srcCurrency=EUR&srcAmount=250&dstCurrency=BTC&dstChain=bitcoin&walletAddress=0xYourWalletAddress";
    ```
  </Step>
</Steps>

In this example, the user buys **250 EUR** worth of **BTC** on the Bitcoin chain, with crypto sent to `0xYourWalletAddress`.

***

## Webhook Integration

Track transaction status in real-time by configuring webhooks in your Rampnow Partner Dashboard.

<Tip>
  [Set up webhooks](/api-reference/webhook) to receive notifications when users start or complete transactions.
</Tip>

***

## When to Use Widget Mode

<AccordionGroup>
  <Accordion title="Ideal For" icon="check">
    * Platforms wanting a deeply integrated user experience
    * Partners looking for quick integration with minimal code
    * Applications needing all available payment modes
    * Teams wanting consistent, pre-built UI
  </Accordion>

  <Accordion title="Benefits" icon="bolt">
    * Fastest integration method — no custom UI needed
    * All payment methods supported out of the box
    * Pre-fill user data for convenience
    * Automatic updates without code changes
  </Accordion>
</AccordionGroup>

***

## Next Steps

<div style={{display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '1rem'}}>
  <Card title="Rampnow SDK" icon="cube" href="/api-reference/sdk">
    Upgrade to the SDK for event handling, TypeScript support, and a React hook
  </Card>

  <Card title="Webhooks" icon="bell" href="/api-reference/webhook">
    Set up server-side transaction notifications
  </Card>

  <Card title="Supported Assets" icon="coins" href="/quickstart/resources/supported-assets">
    View supported cryptocurrencies and fiat currencies
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Explore the complete API documentation
  </Card>
</div>