Integration Methods

The Mercuryo Widget supports three integration methods. Choose the one that fits your platform best.

Redirect Integration

The simplest method: redirect users to the widget URL. No embedding required.

const widgetUrl = `https://exchange.mercuryo.io/?widget_id=YOUR_WIDGET_ID`;
window.location.href = widgetUrl;

When to use: Web applications where it's acceptable for users to leave the page. Lowest implementation effort.

In Sandbox, use https://sandbox-exchange.mrcr.io instead.

iFrame Integration

Embed the widget directly in your page using Mercuryo's JavaScript SDK. Users stay on your site.

Setup

Add the widget container to your page <body>:

<div id="mercuryo-widget"></div>

Add the SDK script before </body>:

<!-- Production -->
<script src="https://widget.mercuryo.io/embed.2.1.js"></script>

<!-- Sandbox -->
<script src="https://sandbox-widget.mrcr.io/embed.2.1.js"></script>

Initialize the widget:

mercuryoWidget.run({
  widgetId: 'YOUR_WIDGET_ID',
  host: document.getElementById('mercuryo-widget'),
  address: 'USER_WALLET_ADDRESS',
  merchantTransactionId: 'YOUR_TX_ID',
  signature: 'v2:GENERATED_SIGNATURE'
});

Parameter Names in the JS SDK

Multi-word URL parameters use camelCase in mercuryoWidget.run(). Single-word parameters are identical in both formats.

URL parameter	JS SDK property
`widget_id`	`widgetId`
`fiat_currency`	`fiatCurrency`
`merchant_transaction_id`	`merchantTransactionId`
`fix_payment_method`	`fixPaymentMethod`

See Widget Parameters for the full list with both URL and JS SDK formats.

Example — pre-authenticated user with pre-filled currency:

mercuryoWidget.run({
  widgetId: 'YOUR_WIDGET_ID',
  host: document.getElementById('mercuryo-widget'),
  address: 'USER_WALLET_ADDRESS',
  merchantTransactionId: 'YOUR_TX_ID',
  signature: 'v2:GENERATED_SIGNATURE',
  // Pre-authenticate the user (see Authentication)
  initTokenType: 'sdk_partner_authorization',
  initToken: '0a25dd714163a9006',
  // Pre-fill and lock currency
  fiatCurrency: 'EUR',
  currency: 'USDT',
  fixFiatCurrency: true
});

JS SDK Callbacks

The JS SDK exposes callback properties in mercuryoWidget.run() that fire on widget events. Use these to react to transaction status changes, user actions, and widget lifecycle.

mercuryoWidget.run({
  widgetId: 'YOUR_WIDGET_ID',
  host: document.getElementById('mercuryo-widget'),
  address: 'USER_WALLET_ADDRESS',
  merchantTransactionId: 'YOUR_TX_ID',
  signature: 'v2:GENERATED_SIGNATURE',

  onLoad: () => {
    console.log('Widget is loading');
  },
  onReady: () => {
    console.log('Widget is ready');
  },
  onStatusChange: (data) => {
    console.log('Status changed:', data);
    // { status, merchant_transaction_id, amount, currency, network,
    //   fiat_amount, fiat_currency, payment_method }
  },
  onPaymentFinished: (data) => {
    console.log('Payment finished:', data);
    // { payment_method }
  },
  onSellTransferEnabled: (data) => {
    console.log('Sell address ready:', data);
    // { id, amount, currency, network, address, flow_id }
  },
  onUserLoggedIn: (data) => {
    console.log('User logged in:', data);
    // { token }
  },
  onUserLoggedOut: () => {
    console.log('User logged out');
  }
});

Callback	Fires when	Payload
`onLoad`	Widget starts loading	—
`onReady`	Widget is fully loaded and interactive	—
`onStatusChange`	Transaction status changes (fires on every change)	`{ status, merchant_transaction_id, amount, currency, network, fiat_amount, fiat_currency, payment_method }`
`onPaymentFinished`	On-Ramp: fiat payment processed and KYC check (if any) completed — regardless of outcome	`{ payment_method }`
`onSellTransferEnabled`	Off-Ramp: user has selected a sell method and the crypto deposit address is shown	`{ id, amount, currency, network, address, flow_id }`
`onUserLoggedIn`	User successfully signed in to the widget	`{ token }`
`onUserLoggedOut`	User signed out of the widget	—

iFrame HTML Alternative

If you prefer a plain <iframe> without the JS SDK:

<iframe
  src="https://widget.mercuryo.io/?widget_id=YOUR_WIDGET_ID"
  width="100%"
  height="600px"
  frameborder="0"
  allow="camera"
></iframe>

Note: Camera permission is required. The allow="camera" attribute is mandatory — users need camera access for the KYC liveness test. Without it, KYC will fail.

Dashboard domain setup: In your widget's Domain URL field, enter the exact domain where the widget is embedded. No trailing slashes or characters. A domain mismatch shows the error widget.mercuryo.io refused to connect.

Mobile Integration

iOS

Use the Mercuryo-Widget-Wrapper-iOS library:

import MRCRWidget

let configuration = try WidgetConfiguration(
    widgetId: "YOUR_WIDGET_ID",
    environment: .production,
    params: nil
)

let vc = WidgetAssembly(
    configuration: configuration,
    uiDelegate: self
).build()

self.present(vc, animated: true)

Android — WebView

Use the Mercuryo-Widget-Wrapper-Android library:

import MRCRWidget

class MainActivity : MercuryoWebViewActivity(val viewID: Int) {
    // Widget initialized automatically
}

Android — Custom Tabs

Custom Tabs are required to enable Google Pay in Android apps. WebView does not support Google Pay.

Basic implementation:

val url = "https://exchange.mercuryo.io"
val intent = CustomTabsIntent.Builder().build()
intent.launchUrl(requireContext(), Uri.parse(url))

With custom appearance:

val customTabsIntent = CustomTabsIntent.Builder()
    .setToolbarColor(Color.BLUE)
    .build()
customTabsIntent.setStartAnimations(this, R.anim.slide_in_right, R.anim.slide_out_left)
customTabsIntent.setExitAnimations(this, R.anim.slide_in_left, R.anim.slide_out_right)
customTabsIntent.launchUrl(requireContext(), Uri.parse(url))

Benefits of Custom Tabs vs WebView:

Google Pay works correctly
Consistent URL handling with WebView integration
Better conversion rates for mobile payment options

Mobile Payment Compatibility

Apple Pay

Browser	WebView	Custom Tab
Safari	Fully Compatible	Incompatible
Google Chrome	Incompatible	Incompatible
Chromium Browsers	Incompatible	Incompatible

Google Pay

Browser	WebView	Custom Tab
Safari	Incompatible	Fully Compatible
Google Chrome	Incompatible	Fully Compatible
Chromium Browsers	Incompatible	Fully Compatible

The availability of mobile payment methods may vary depending on the user's device, OS version, and card issuer.

Sandbox & Testing

Signature Generation