Інтеграція Mercuryo для купівлі крипти в мобільному додатку
Чому без вбудованого on-ramp падає конверсія?
Уявіть: користувач хоче купити ETH за євро прямо у вашому мобільному гаманці. Якщо немає вбудованого on-ramp, він йде на сторонню біржу, і конверсія падає на 40%. Mercuryo — європейський провайдер з ліцензією FCA, що підтримує понад 100 країн. Комісія: 2.95–3.95% для карток, 1.5% для SEPA. Ми інтегруємо Mercuryo у ваш додаток: віджет за 2–3 дні або кастомний API. За статистикою, вбудований on-ramp підвищує утримання на 25% і збільшує дохід з кожної покупки на 30%.
Як вибрати режим інтеграції: віджет чи API?
Віджет — WebView або браузер. Швидка інтеграція, Mercuryo управляє KYC та платіжною сторінкою. Підходить для MVP і типових гаманців. API — повний контроль UI, потребує business verification у Mercuryo та технічного узгодження. Використовується, коли потрібна унікальна платіжна форма. Більшість гаманців обирають віджет — він покриває 90% сценаріїв.
| Критерій | Widget | API |
|---|---|---|
| Швидкість інтеграції | 1–2 дні | 2–4 тижні |
| Контроль UI | Мінімальний (кольори, мова) | Повний кастом |
| KYC/AML | З боку Mercuryo | Можна вбудувати свою систему |
| Вимоги до сервера | Підпис HMAC + Webhook | Підпис, обмін токенами, обробка ордерів |
| Рекомендація | MVP, гаманці загального призначення | Біржі, white-label рішення |
Як згенерувати підпис для віджета Mercuryo?
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.
Що робити, якщо підпис невалідний?
Перевірте: чи збігається секрет на сервері та в панелі Mercuryo, чи правильна адреса гаманця передана, чи не містить рядок зайвих символів. Помилка підпису — найчастіша проблема при першому запуску віджета.
Відкриття віджета
// 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=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 — актуальний довідник.
Таблиця популярних мереж
| Токен | Мережа | Chain ID | Статус |
|---|---|---|---|
| ETH | Ethereum | 1 | Active |
| USDC | Ethereum | 1 | Active |
| USDC | Polygon | 137 | Active |
| BNB | BSC | 56 | Active |
| AVAX | Avalanche C | 43114 | Active |
Callback та верифікація
Після завершення покупки Mercuryo редиректить на redirect_url з параметрами status (succeeded, failed, pending) та transaction_id. Webhook на бекенді — надійніше за deeplink. Рекомендуємо налаштувати endpoint, який приймає POST-запити з JSON-тілом, що містить статус та підпис верифікації. Для гарантованої доставки реалізуйте механізм повторних спроб та ідемпотентність.
Безпека та Compliance
При інтеграції on-ramp важливо дотримуватися вимог App Store Review Guidelines. Для iOS використовуйте Universal Links для redirect_url, щоб після покупки користувач повертався в додаток. На Android — App Links. Також подбайте про коректне налаштування App Transport Security (ATS) для iOS. Якщо додаток збирає дані для трекінгу, обов'язково запросіть дозвіл ATT (App Tracking Transparency) перед відкриттям віджета. Mercuryo має власні процедури KYC/AML, але ваш додаток повинен коректно обробляти статуси верифікації.
Процес роботи
- Аналітика — вивчаємо вимоги, обираємо режим інтеграції.
- Проектування — визначаємо архітектуру: серверний підпис, обробка callback.
- Реалізація — підключаємо віджет або API, налаштовуємо параметри.
- Тестування — перевіряємо всі сценарії: успішна покупка, помилки, callback, а також тестуємо через TestFlight для iOS.
- Деплой — публікуємо в App Store / Google Play, налаштовуємо моніторинг.
Що входить в роботу
- Документація з інтеграції та схема підпису.
- Реалізація серверного ендпоінта для генерації signature.
- Налаштування віджета або API з урахуванням дизайну додатка.
- Обробка deeplink та webhook для отримання статусів.
- Тестовий аккаунт Mercuryo та консультації з KYC.
- Підтримка 2 тижні після запуску.
Оцінка та строки
Строки: від 2 до 14 днів залежно від режиму інтеграції (віджет — 2–3 дні, API — до 2 тижнів). Вартість розраховується індивідуально. Отримайте консультацію з інтеграції Mercuryo — ми оцінимо ваш проект і запропонуємо оптимальне рішення. Зв'яжіться з нами, щоб прискорити виведення продукту на ринок.
Досвід: 5+ років інтеграції фінтех-рішень, 50+ проектів з on-ramp провайдерами. Джерело: документація Mercuryo Widget SDK (mercuryo.io).