Технічна інтеграція 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 без необхідності підключати кожен сервіс окремо. Середній час виходу на новий регіон скорочується вдвічі.
• Безпека: 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 вдвічі знижує час виходу на нові регіони. Наприклад, для запуску в Бразилії достатньо одного 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. Ми використовуємо її при кожній інтеграції, що гарантує відповідність останнім оновленням.