Интеграция Mercuryo: on/off-ramp для криптопроектов

Интеграция Mercuryo: on/off-ramp для криптопроектов

Отметим: когда ваш dApp или биржа упирается в отсутствие фиатного шлюза для СНГ — Mercuryo остаётся одним из немногих провайдеров с реальным покрытием локальных методов оплаты. Мы интегрируем Mercuryo под ключ: от встраивания Widget SDK до настройки серверных callback-уведомлений и мониторинга транзакций. За 5 лет работы мы реализовали более 50 проектов с Mercuryo, что дало нам понимание всех подводных камней интеграции. Mercuryo поддерживает Visa/Mastercard, SEPA, а также локальные способы оплаты для стран СНГ, включая карты и переводы. Благодаря прямому партнёрству с провайдером, мы обеспечиваем минимальные задержки и конкурентоспособные курсы.

Как Mercuryo решает проблему фиатного шлюза?

Mercuryo предоставляет два способа интеграции: виджет для браузера и REST API. Виджет подходит для быстрого запуска покупки/продажи криптовалюты прямо в интерфейсе. API — для кастомизации воронки и обработки платежей на серверной стороне. Оба подхода требуют валидации подписи адреса и проверки callback-запросов. Виджет встраивается за один день, а полноценная интеграция через API занимает до 10 дней.

Проблемы, которые мы решаем

• Некорректная подпись адреса — Mercuryo требует HMAC-SHA512 подпись адреса кошелька. Ошибка в алгоритме приводит к отклонению транзакции. Мы встречали проекты, где использовали SHA256 вместо SHA512 — все такие запросы отклонялись.
• Потеря callback-уведомлений — если не настроить проверку подписи и повторные попытки, платежи могут потеряться. В одном кейсе из нашей практики мы фиксировали до 15% потерянных уведомлений до внедрения ретраев с exponential backoff.
• Ограничения CORS — при встраивании виджета в iframe нужно правильно настроить домены в панели Mercuryo. Частая ошибка — забыть добавить продакшен-домен после тестирования.

Как мы это делаем: стек и кейс

Используем Python + FastAPI для callback-сервера, TypeScript для виджета. Пример кода:

// Mercuryo Widget v4 const mercuryoWidget = { widgetId: process.env.MERCURYO_WIDGET_ID, type: 'buy', // 'buy' или 'sell' currency: 'BTC', fiatCurrency: 'EUR', fiatAmount: '100', address: walletAddress, signature: await getSignedAddress(walletAddress), // серверная подпись onStatusChange: (data) => { if (data.status === 'paid') { handlePaymentComplete(data.transactionId); } }, }; // Встройка через URL const params = new URLSearchParams(mercuryoWidget); const widgetUrl = `https://exchange.mercuryo.io/?${params}`; window.open(widgetUrl, '_blank'); 

import hmac, hashlib def sign_wallet_address(address: str, secret: str) -> str: """Mercuryo требует подпись адреса для защиты от подмены""" return hmac.new( secret.encode(), address.encode(), hashlib.sha512 ).hexdigest() 

import httpx class MercuryoClient: BASE_URL = "https://api.mercuryo.io/v1.6" def __init__(self, api_key: str, secret: str): self.api_key = api_key self.secret = secret async def get_rates(self, from_currency: str, to_currency: str, amount: float) -> dict: async with httpx.AsyncClient() as client: resp = await client.get( f"{self.BASE_URL}/public/rates", params={ "from": from_currency, "to": to_currency, "amount": amount, } ) return resp.json() async def get_transaction(self, tx_id: str) -> dict: async with httpx.AsyncClient() as client: resp = await client.get( f"{self.BASE_URL}/sdk-partner/transactions/{tx_id}", headers={"Sdk-Partner-Token": self.api_key} ) return resp.json()["data"] 

@app.post("/callbacks/mercuryo") async def mercuryo_callback(request: Request): data = await request.json() # Проверка подписи signature = request.headers.get("X-Mercuryo-Signature") body = await request.body() expected = hashlib.sha512(body + MERCURYO_SECRET.encode()).hexdigest() if signature != expected: raise HTTPException(403) status = data["status"] if status == "paid": await process_crypto_delivery(data["id"], data["amount"], data["currency"]) elif status == "failed": await handle_failed_transaction(data["id"]) 

Официальная документация Mercuryo (Mercuryo API).

Какие комиссии у Mercuryo и как на них сэкономить?

Mercuryo взимает комиссию в зависимости от метода оплаты. Для карт она составляет около 3.95%, для банковских переводов SEPA — 2.95%, для локальных методов СНГ — примерно 3.5%. Дополнительно может применяться конвертация валюты. Выбор метода SEPA вместо карт позволяет сэкономить 1% на каждой транзакции. Наша команда помогает оптимизировать маршрут оплаты под вашу аудиторию, что приводит к существенной экономии на комиссиях. Свяжитесь с нами, чтобы получить индивидуальную оценку вашего профиля транзакций.

Процесс работы

1. Аналитика — разбираем вашу воронку: где нужен on-ramp, какие валюты, какой объём.
2. Проектирование — выбираем виджет или API, проектируем схему callback-обработки.
3. Интеграция — встраиваем SDK, настраиваем подпись, пишем обработчики.
4. Тестирование — проводим тестовые транзакции, проверяем callback-уведомления.
5. Деплой — выкатываем в продакшен, настраиваем мониторинг.

Что входит в интеграцию

• Настройка Widget SDK (покупка/продажа криптовалюты).
• REST API для получения курсов и статусов транзакций.
• Серверная подпись адресов и валидация callback-запросов.
• Обработка ошибок и повторные попытки.
• Документация по интеграции для вашей команды.

Сравнение способов интеграции

Widget SDK быстрее в развёртывании примерно в 3 раза, но REST API даёт полный контроль над воронкой.

Сравнение комиссий по методам оплаты

Выбор метода может снизить затраты на 1-2% на транзакцию.

Типичные ошибки при интеграции

• Неверный алгоритм подписи: используйте SHA512, не SHA256.
• Отсутствие проверки статуса транзакции в callback: всегда обрабатывайте статус paid.
• Неправильная обработка ошибок: Mercuryo возвращает ошибки с кодом 4xx/5xx — нужно логировать и повторять.
• Забывают настроить webhook retries: Mercuryo шлёт callback один раз, без подтверждения — потеря необратима.

Получите консультацию по интеграции Mercuryo — оценим ваш проект за 1 день. Свяжитесь с нами, чтобы обсудить детали.