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

# Add the widget

> Create a widget, register your website and open it from a button on your page.

Add stablecoin buying and selling to your website. Customers complete the payment in an Onstacks window on your page, and you see their transactions in your dashboard.

Start by creating a widget in Sandbox and adding your website.

<Steps>
  <Step title="Create the widget">
    In the dashboard, switch the environment to **Sandbox**, then go to **Settings → Ramps → Website widget** and fill in:

    | Field | What to enter |
    | - | - |
    | **Website** | The address of the page that will open the widget, for example `https://shop.example.com`. In Sandbox, `http://localhost:3000` works too. |
    | **Display name** | The business name the widget shows your customers. |
    | **Widget ID** | A short name made of lowercase letters, digits and hyphens. It can't be changed later. |

    Live has its own widget, with its own ID and settings. You create it the same way once Live access is approved. See [Test and go live](/ramps/widget/go-live).
  </Step>

  <Step title="Add the script and a button">
    Paste this into the page you registered, replacing `your-widget-id`:

    ```html HTML theme={"system"}
    <script
      src="https://js.onstacks.io/embed/1.1.0.js"
      integrity="sha384-cNfWGj5hpTIPM/rc1j0u5sh46v+otoZGpoIbtDf4G3HLU7S+v5xsYAImGeSCmsow"
      crossorigin="anonymous"
    ></script>

    <button id="sell">Sell USDC</button>
    <p id="status"></p>

    <script>
      const status = document.getElementById("status");

      document.getElementById("sell").addEventListener("click", () => {
        status.textContent = "";
        Onstacks.open(
          { widgetId: "your-widget-id", environment: "sandbox", type: "offramp", ref: "order-123" },
          {
            onCompleted: ({ ref }) => {
              status.textContent = `Payment ${ref} received. We'll confirm it shortly.`;
            },
            onFailed: ({ ref }) => {
              status.textContent = `Payment ${ref} didn't go through. You can try again.`;
            },
            onError: ({ reason }) => {
              status.textContent =
                reason === "timeout"
                  ? "The widget didn't load. Check your connection and try again."
                  : "This link has expired. Reload the page and try again.";
            },
          },
        );
      });
    </script>
    ```

    **What you should see.** Clicking the button opens a window over your page with your display name at the top. The customer chooses the amount and currency, signs in with a code sent to their email, completes identity verification the first time, then either sends stablecoins to the address shown (sell) or pays by bank transfer (buy). When they finish, the status line under the button updates.

    Everything in the first argument except `widgetId` is optional:

    | Option | Description |
    | - | - |
    | `widgetId` | **Required.** From **Settings → Ramps → Website widget**. |
    | `environment` | `sandbox` (default) or `live`. Must match the environment the widget was created in. |
    | `type` | Starting direction: `offramp` (customer sells stablecoins, default) or `onramp` (customer buys). The customer can switch if you allow both under **Payment options**. |
    | `asset`, `chain`, `currency`, `amount` | Prefill the form, for example `USDC`, `base`, `NGN`, `100`. The customer can change them within what you allow under **Payment options**. |
    | `wallet` | Buy only: prefill the wallet address the stablecoins go to. |
    | `ref` | Your order or session reference. Returned in `onCompleted` and `onFailed`. |
    | `redirect` | Where to send the customer when they finish a widget link opened as a full page. Must be on one of your redirect origins. Inside the window on your page, your callbacks run instead. |

    Callbacks, inline embedding and error handling: [Script reference](/ramps/widget/embedding).
  </Step>

  <Step title="See the payment in your dashboard">
    Open **Ramps** in the dashboard and set **Source** to **Widget payments**. The payment appears with its status; open it for the amounts, provider and timestamps.

    The `onCompleted` callback tells your page what the widget showed the customer. It isn't proof of payment: before you hand over anything of value, confirm the payment in the dashboard or through a webhook. See [Track payments](/ramps/widget/track-payments).
  </Step>
</Steps>

## If it doesn't work

| What happens | Why, and what to do |
| - | - |
| Nothing happens, and the console says `Onstacks is not defined` | The script didn't load. Check the `src`, and that the `integrity` hash matches the version you load. |
| The console says `Onstacks: widgetId is required` | `widgetId` is missing or has characters other than lowercase letters, digits and hyphens. Copy it from the dashboard. |
| The window opens on a "not found" page | The widget ID doesn't exist in that environment (for example a Sandbox ID with `environment: "live"`), the page's address isn't under **Websites allowed to embed your widget**, or **Accept new widget links** is off. |
| `onError` runs with `timeout` | The widget didn't load within 20 seconds. If your site sets a Content Security Policy, allow `frame-src https://ramp.onstacks.io https://ramp-sandbox.onstacks.io`. |
| `onError` runs with `expired` | A signed link's `exp` has passed. Generate a new link. |

## Next

<CardGroup cols={3}>
  <Card title="Configure your widget" icon="sliders" href="/ramps/widget/settings">
    Branding, payment options and websites.
  </Card>

  <Card title="Track payments" icon="list-check" href="/ramps/widget/track-payments">
    Statuses, the dashboard and optional webhooks.
  </Card>

  <Card title="Test and go live" icon="rocket" href="/ramps/widget/go-live">
    What to test in Sandbox and what Live needs.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.