Payment Flows

On-Ramp — Crypto Purchase

Users buy cryptocurrency with fiat money using a payment card, Apple Pay, Google Pay, or APMs (alternative payment methods, e.g. Revolut Pay).

Flow Overview

  1. (Optional) Fetch data to pre-fill the widget and show rates on your side.
  2. Generate the widget URL with required parameters.
  3. Show the widget (redirect or embed).
  4. The user completes payment.
  5. Mercuryo sends crypto to the user's wallet.
  6. Track transaction status via callbacks or API.

Step 1 — Fetch Pre-fill Data (Optional)

Use these endpoints before opening the widget to display rates and available currencies on your own UI, and to build the widget URL with relevant parameters.

Endpoint Purpose
GET /v1.6/public/data-by-ip Get user's country code from IP address
GET /v1.6/lib/currencies List of supported currencies with availability flags per country
GET /v1.6/public/card-countries Check if user's country supports card payments
GET /v1.6/public/currency-limits Min/max transaction limits for a currency pair
GET /v1.6/widget/buy/rate Current exchange rate and fee for a specific transaction

Filtering by country: combine data.country.code from data-by-ip with data from lib/currencies. For crypto-network pairs, check widget_onramp_enabled flag and verify the user's country is not in restricted_countries_onramp. For fiat currencies, check onramp_enabled and restricted_countries_onramp.

Step 2 — Build the Widget URL

Example URL for purchasing 0.001 BTC with USD:

https://exchange.mercuryo.io/?widget_id=67710925-8b40-4767-846e-3b88db69f04d
  &type=buy
  &currency=BTC
  &fix_currency=true
  &amount=0.001
  &fix_amount=true
  &fiat_currency=USD
  &address=bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
  &merchant_transaction_id=tx_123456
  &signature=v2:83a6473f7b0aade8cd794c38f435d8db...

Parameter summary:

Parameter Required Description
widget_id Yes Your Widget ID
type No Lock to buy
currency No Pre-select crypto (e.g., BTC)
fix_currency No Prevent the user from changing crypto
amount No Pre-fill crypto amount
fix_amount No Lock the crypto amount
fiat_currency No Pre-select fiat (e.g., USD)
address Yes (On-Ramp) User's wallet to receive purchased crypto
merchant_transaction_id Yes Your transaction ID (also used in signature)
signature Yes See Signature Generation

See the full Widget Parameters reference for all available options.

Step 3 — Show the Widget

  • Redirect: window.location.href = widgetUrl
  • iFrame JS SDK: mercuryoWidget.run({ widgetId: '...', host: ..., address: '...', ... })
  • Mobile: use iOS or Android wrapper

See Integration Methods for code examples.

Step 4 — User Flow in the Widget

Depending on what you pre-filled, the user may need to:

  • Enter the crypto amount and currency (if not pre-filled)
  • Provide their wallet address (if address was not passed)
  • Sign in or register with Mercuryo (skip with Silent Authentication)
  • Complete KYC (skip with SumSub share token if already verified on your side)
  • Select a payment method and complete payment

Step 5 — Track Transaction Status

After the user completes payment, Mercuryo sends crypto to the wallet address. Track the transaction status:

  • Callbacks — Mercuryo POSTs to your callback URL on every status change. See Callbacks.
  • API Polling — GET /v1.6/sdk-partner/transactions?merchant_transaction_id=tx_123456

See Transaction Types & Statuses for all possible status values.

Previous
Widget Parameters
Next
Off-Ramp (Sell)