Mercuryo Integration for Crypto Purchase in Mobile App

Mercuryo Integration for Crypto Purchase in a Mobile App

Mercuryo is a European on-ramp provider with FCA licensing and support for 100+ countries. Fee is 2.95–3.95% for cards, 1.5% for SEPA. The standout feature — the widget is easily customizable to app colors, and there's a native SDK for iOS.

Two Integration Modes

Widget (https://exchange.mercuryo.io) — WebView or browser. Quick integration, Mercuryo manages KYC and the payment page.

API — full UI control, requires business verification from Mercuryo and technical coordination. Not for startups.

Most mobile wallets use the widget approach.

Widget Signature via HMAC

Mercuryo requires HMAC-SHA512 signature from the string {walletAddress}{secret}:

// Server-side: signing the address
import CryptoKit
let input = "\(walletAddress)\(mercuryoSecret)"
let key = SymmetricKey(data: Data(mercuryoSecret.utf8))
let mac = HMAC<SHA512>.authenticationCode(for: Data(input.utf8), using: key)
let signature = Data(mac).map { String(format: "%02x", $0) }.joined()

Without a correct signature, the widget opens with an error or won't let you complete the purchase. The signature is computed on the server and passed to the app as part of the URL.

Opening the Widget

// Android — Chrome Custom Tabs with Mercuryo widget
val params = buildString {
    append("widget_id=${mercuryoWidgetId}")
    append("&type=buy")
    append("&currency=ETH")
    append("&network=ETHEREUM")
    append("&address=${userWalletAddress}")
    append("&signature=${serverGeneratedSignature}")
    append("&fiat_currency=EUR")
    append("&redirect_url=${URLEncoder.encode("myapp://mercuryo-complete", "UTF-8")}")
    append("&theme=dark")
    append("&lang=en")
}
val widgetUrl = "https://exchange.mercuryo.io/?$params"

CustomTabsIntent.Builder()
    .setColorScheme(CustomTabsIntent.COLOR_SCHEME_DARK)
    .build()
    .launchUrl(context, Uri.parse(widgetUrl))

The network Parameter is Critical

Mercuryo distinguishes network and token separately. currency=USDC&network=ETHEREUM is USDC on Ethereum. currency=USDC&network=POLYGON is USDC on Polygon. Passing the wrong network means the user receives crypto on a different address (if formats match) or the transaction fails.

Supported pairs list: GET https://api.mercuryo.io/v1.6/public/currencies-buy — the authoritative reference.

Callback and Verification

After purchase completion, Mercuryo redirects to redirect_url with parameters status (succeeded, failed, pending) and transaction_id. A webhook on the backend is more reliable than deeplink.

Timeline: 2–3 days for server-side signature generation, widget opening, deeplink callback handling, and status verification via Mercuryo API.