Інтеграція Mercuryo для покупки крипто в мобільному додатку
Mercuryo — європейський on-ramp провайдер з ліцензією FCA та підтримкою 100+ країн. Комісія 2.95–3.95% для карт, 1.5% для SEPA. Відмінна риса — віджет легко кастомізується під кольори додатку, та є нативний SDK для iOS.
Два режими інтеграції
Віджет (https://exchange.mercuryo.io) — WebView або браузер. Швидка інтеграція, Mercuryo управляє KYC та платіжною сторінкою.
API — повний контроль UI, вимагає business verification з боку Mercuryo та технічного узгодження. Не для старту.
Більшість мобільних гаманців використовують віджет.
Підпис віджета через HMAC
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("¤cy=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=uk")
}
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.