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

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

Відзначимо: коли ваш dApp або біржа впирається у відсутність фіатного шлюзу для СНД — Mercuryo залишається одним із небагатьох провайдерів із реальним покриттям локальних методів оплати. Ми інтегруємо Mercuryo під ключ: від вбудовування Widget SDK до налаштування серверних callback-сповіщень і моніторингу транзакцій. Ми гарантуємо коректну обробку 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. Але REST API дає повний контроль над воронкою.

Порівняння комісій за методами оплати

Вибір методу може знизити витрати на 1-2% на транзакцію.

Типові помилки при інтеграції

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

Отримайте консультацію з інтеграції Mercuryo — оцінимо ваш проєкт за 1 день. Зв'яжіться з нами, щоб обговорити деталі.