Add the widget

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.

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.

Add the script and a button

Paste this into the page you registered, replacing your-widget-id:

HTML

<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.

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.

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.

Configure your widget

Branding, payment options and websites.

Track payments

Statuses, the dashboard and optional webhooks.

Test and go live

What to test in Sandbox and what Live needs.

Welcome

API basics

Ramp

Orchestration

Wallets

Agentic Payments

If it doesn’t work

Next

Configure your widget

Track payments

Test and go live

​If it doesn’t work

​Next

Configure your widget

Track payments

Test and go live

If it doesn’t work

Next