Интеграция Mercuryo для покупки крипты в мобильном приложении

Интеграция Mercuryo для покупки крипты в мобильном приложении

Mercuryo — европейский on-ramp провайдер с лицензией FCA и поддержкой 100+ стран. Комиссия 2.95–3.95% для карт, 1.5% для SEPA. Отличительная черта — виджет легко кастомизируется под цвета приложения, и есть нативный SDK для iOS.

Два режима интеграции

Widget (https://exchange.mercuryo.io) — WebView или браузер. Быстрая интеграция, Mercuryo управляет KYC и платёжной страницей.

API — полный контроль UI, требует business verification на стороне Mercuryo и технического согласования. Не для старта.

Большинство мобильных кошельков используют виджет.

Подпись виджета через signature

Mercuryo требует HMAC-SHA512 подпись от строки {walletAddress}{secret}:

// Серверная сторона: подпись адреса
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()

Без корректной подписи виджет открывается с ошибкой или не даёт завершить покупку. Подпись вычисляется на сервере, передаётся в приложение как часть URL.

Открытие виджета

// Android — Chrome Custom Tabs с Mercuryo виджетом
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=ru")
}
val widgetUrl = "https://exchange.mercuryo.io/?$params"

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

Параметр network критически важен

Mercuryo различает сеть и токен отдельно. currency=USDC&network=ETHEREUM — USDC на Ethereum. currency=USDC&network=POLYGON — USDC на Polygon. Передать неправильную сеть — пользователь получит крипту на другой адрес (если адреса совпадают по формату) или транзакция упадёт.

Список поддерживаемых пар: GET https://api.mercuryo.io/v1.6/public/currencies-buy — актуальный справочник.

Callback и верификация

После завершения покупки Mercuryo редиректит на redirect_url с параметрами status (succeeded, failed, pending) и transaction_id. Webhook на бэкенде — надёжнее deeplink.

Сроки: 2–3 дня: серверная генерация подписи, открытие виджета, обработка deeplink-callback, проверка статуса через API Mercuryo.