Quick Start

Get your first Mercuryo Widget integration live in 4 steps.

Prerequisites

Before starting, make sure you have:

• Access to the Mercuryo Dashboard — contact your integration manager if you don't have credentials yet.
• A domain or app that will host the widget.
• A chosen integration method — Redirect, iFrame, or Mobile. See Integration Methods for the differences.

Step 1 — Create a Widget

1. Sign in to the Mercuryo Dashboard.

2. Go to Widgets → Add Widget.

3. In the Domain URL field, the value depends on your integration method:

   • Redirect: enter https://exchange.mercuryo.io
   • iFrame / Mobile: enter your own domain (e.g., https://yourdomain.com)

   Leave no trailing slash or extra characters — a domain mismatch causes the widget.mercuryo.io refused to connect error.

4. Note your Widget ID — you'll need it in every widget URL.

5. Copy your Secret from the bottom of the widget page — needed for signature generation.

Step 2 — Configure Callback URL

1. In the widget settings, fill in the Callback URL field with your server endpoint.
2. Copy the Sign Key — you'll use it to verify incoming callbacks.

See the Callback dashboard to browse, resend, and send test callbacks.

Step 3 — Build the Widget URL

A minimal On-Ramp widget URL looks like this:

https://exchange.mercuryo.io/?widget_id=YOUR_WIDGET_ID&address=USER_WALLET_ADDRESS&merchant_transaction_id=YOUR_TX_ID&signature=v2:GENERATED_SIGNATURE

• widget_id — your Widget ID from the Dashboard.
• address — the user's cryptocurrency wallet address for receiving purchased crypto.
• merchant_transaction_id — your internal transaction ID for tracking.
• signature — security signature. See Signature Generation.

You can pre-fill many more parameters (currency, amount, payment method, etc.). See the full Widget Parameters reference.

Step 4 — Handle Transaction Updates

Choose how to track transaction status changes:

See Callbacks & Webhooks for setup and payload details.

Note: Test with the Sandbox environment before going to production. You can try all flows without using real funds.