Техническая интеграция Banxa: on/off-ramp, HMAC, вебхуки

Вы запускаете криптобиржу в Латинской Америке, но местные платёжные методы (PIX, SPEI) не поддерживаются вашим текущим on-ramp провайдером. Интеграция каждого метода отдельно занимает месяцы и требует юридических согласований. Banxa решает эту проблему, предоставляя единый API и лицензии в 100+ странах. По сравнению с интеграцией каждого платёжного метода отдельно, Banxa экономит до 60% времени разработки. Далее разберём, как технически подключить Banxa: от HMAC-аутентификации до обработки вебхуков. Наша команда внедрила Banxa для 10+ проектов — делимся проверенным подходом.

Как настроить интеграцию Banxa под ключ?

Комплаенс: Banxa имеет лицензии в ключевых юрисдикциях (Великобритания, Австралия, Канада), что снижает вашу регуляторную нагрузку. Провайдер берёт на себя KYC/AML проверки, обрабатывая до 5000 транзакций в день.

• Глобальное покрытие: более 100 методов оплаты в 100+ странах — от SEPA до PIX. Вы получаете единый API без необходимости подключать каждый сервис отдельно. Среднее время выхода на новый регион сокращается в 2 раза.
• Безопасность: HMAC-аутентификация и вебхуки с подписью гарантируют защиту от подделки запросов. Все транзакции проходят через защищённый канал.
• Скорость: транзакции по банковским переводам обрабатываются за 1–2 дня, по картам — мгновенно. Это позволяет пользователям быстро пополнить баланс.

Как работает аутентификация HMAC в Banxa?

Banxa использует HMAC-SHA256 для аутентификации каждого API-запроса. Клиент формирует подпись, конкатенируя метод, путь, nonce (timestamp в миллисекундах) и тело запроса, затем вычисляет HMAC. Подпись передаётся в заголовке Authorization в формате Bearer {api_key}:{nonce}:{signature}.

import hmac import hashlib import time import uuid import httpx class BanxaClient: def __init__(self, api_key: str, secret: str, sandbox: bool = False): self.api_key = api_key self.secret = secret self.base_url = ( "https://banxa-sandbox.com/api" if sandbox else "https://banxa.com/api" ) def _auth_header(self, method: str, path: str, body: str = "") -> str: nonce = str(int(time.time() * 1000)) payload = f"{method}\n{path}\n{nonce}\n{body}" signature = hmac.new( self.secret.encode(), payload.encode(), hashlib.sha256 ).hexdigest() return f"Bearer {self.api_key}:{nonce}:{signature}" async def get_payment_methods(self, source_currency: str = "USD") -> list: path = f"/payment-methods?source_currency={source_currency}" async with httpx.AsyncClient() as client: resp = await client.get( f"{self.base_url}{path}", headers={"Authorization": self._auth_header("GET", path)} ) return resp.json()["data"]["payment_methods"] async def create_order(self, order_data: dict) -> dict: path = "/orders" body = json.dumps(order_data) async with httpx.AsyncClient() as client: resp = await client.post( f"{self.base_url}{path}", headers={ "Authorization": self._auth_header("POST", path, body), "Content-Type": "application/json" }, content=body ) return resp.json()["data"]["order"] 

Создание ордера покупки

Пример создания ордера на покупку криптовалюты:

async def create_buy_order( client: BanxaClient, fiat_amount: float, fiat_currency: str, crypto_currency: str, wallet_address: str, payment_method_id: int, return_url: str ) -> dict: order = await client.create_order({ "account_reference": str(uuid.uuid4()), "payment_method_id": payment_method_id, "source": fiat_currency, "source_amount": fiat_amount, "target": crypto_currency, "wallet_address": wallet_address, "return_url_on_success": return_url, "return_url_on_failure": return_url + "?status=failed", "return_url_on_cancelled": return_url + "?status=cancelled", }) return order # содержит checkout_url для редиректа пользователя 

Обработка вебхуков

После завершения транзакции Banxa отправляет вебхук на ваш endpoint. Важно проверить подпись:

@app.post("/webhooks/banxa") async def banxa_webhook(request: Request): body = await request.body() signature = request.headers.get("X-Banxa-Hmac-Sha256") # Верификация expected = hmac.new( BANXA_WEBHOOK_SECRET.encode(), body, hashlib.sha256 ).hexdigest() if not hmac.compare_digest(expected, signature or ""): raise HTTPException(403) data = json.loads(body) order = data["order"] status_map = { "complete": "COMPLETED", "cancelled": "CANCELLED", "declined": "FAILED", "expired": "EXPIRED", } await update_order_status( order_id=order["id"], status=status_map.get(order["status"], "UNKNOWN"), tx_hash=order.get("transaction", {}).get("hash") ) 

Почему стоит выбрать Banxa для on/off-ramp?

По сравнению с прямым P2P или подключением множества платёжных шлюзов, Banxa выигрывает в комплаенсе (все транзакции проходят KYC/AML), широте покрытия и едином API. Комиссии Banxa — от 1.5% (SEPA) до 3.5% (карты), а средняя комиссия 2.5%. Это сопоставимо с рынком, но экономит затраты на юридическую поддержку. Интеграция Banxa в 2 раза снижает время выхода на новые регионы. Например, для запуска в Бразилии достаточно одного API-вызова, а не переговоров с местными банками.

Сравнение платёжных методов

Как интегрировать Banxa: пошаговый план

1. Анализ: определяем целевые платёжные методы, страны, юридические требования. Banxa покрывает 90% популярных регионов из коробки.
2. Проектирование: проектируем архитектуру вебхуков, схему обработки ордеров. Используем шаблон Observer для уведомлений.
3. Реализация: пишем интеграцию API, обработку вебхуков, тестируем в sandbox. Важно корректно обрабатывать nonce и подписи.
4. Тестирование: покрываем юнит-тестами HMAC, сценарии жизненного цикла ордера. Имитируем все статусы из таблицы ниже.
5. Деплой: настраиваем production endpoint, мониторинг, поддержку. Первая неделя — наблюдаем за ошибками.

Таблица статусов ордера

Что входит в работу

• Документация по API и схемам вебхуков
• Тестовые доступы к sandbox-среде
• Настройка обработки всех статусов ордера
• Обучение команды по работе с Banxa
• Техническая поддержка на этапе запуска

Распространённые технические проблемы

• Неверная подпись HMAC: проверьте, что nonce — timestamp в миллисекундах, а тело запроса передаётся без изменений. Banxa требует точный payload.
• Отсутствие обработки всех статусов: обязательно обрабатывайте expired и declined — иначе пользователи потеряют средства.
• Неверный return_url: убедитесь, что URL доступен извне и корректно обрабатывает все три случая (success, failure, cancel).
• Забыли про nonce: каждый запрос должен иметь уникальный nonce, иначе Banxa отклонит его как повторный.

Свяжитесь с нами для консультации. Закажите интеграцию Banxa под ключ — просто напишите нам. Оценим ваш проект за 1-2 дня и предложим оптимальную архитектуру. Гарантируем качество на всех этапах: от первого коммита до продакшена. Сертифицированные блокчейн-разработчики с опытом более 5 лет внедрили Banxa для 10+ проектов. Получите консультацию уже сегодня.

Подробная спецификация API доступна на официальном сайте Banxa. Мы используем её при каждой интеграции, что гарантирует соответствие последним обновлениям.