Руководство по интеграции Bet-Flow

Merchant API v2 · Base URL: https://api.bet-flow.com/v1

1. Быстрый старт

Войдите в личный кабинет → Интеграция
Сгенерируйте API-ключи (секрет показывается один раз — сохраните)
Укажите Callback URL (HTTPS)
Добавьте IP whitelist — egress IP ваших серверов
Реализуйте подпись запросов и проверку webhook
Нажмите «Тест» для проверки webhook

2. Безопасность

Требование	Описание
HTTPS	Все запросы только по TLS
HMAC-SHA256	Подпись каждого запроса секретным ключом
Expires	Unix timestamp, рекомендуется now + 300 сек
X-Nonce	UUID на каждый запрос, без повторов (5 мин)
Rate limit	120 req/min на API-ключ
Webhook	Проверка `X-Signature` = HMAC-SHA256(secret, raw body)
IP whitelist	Если задан в ЛК — только указанные IP/CIDR
Secret	Только на backend, ротация при утечке

3. Подпись запроса

Заголовки:

X-API-Key: <public_key>
Expires: <unix_seconds>
X-API-Sign: <hmac_hex>
X-Nonce: <uuid>
Content-Type: application/json

message = Expires + json_body   # POST
message = Expires + query_string # GET
X-API-Sign = hex(HMAC-SHA256(secret, message))

4. Webhook (от Bet-Flow к вам)

{
  "order_id": "0199ee07-dffa-754c-ba2e-c28c2b2ea15a",
  "merchant_order_id": "order-42",
  "status": "success",
  "amount": "1000.00",
  "currency": "RUB",
  "timestamp": 1760635122
}

Проверка: X-Signature = hex(HMAC-SHA256(secret, raw_body)). Ответьте HTTP 200.

5. Основные эндпоинты

Метод	Путь	Описание
POST	/v1/payin	Создать PayIn
GET	/v1/payin?id=	Статус PayIn
POST	/v1/payout	Создать PayOut
GET	/v1/payout?id=	Статус PayOut
GET	/v1/balances	Баланс
GET	/v1/dictionaries/banks	Банки
GET	/v1/dictionaries/currencies	Валюты
GET	/v1/dictionaries/commissions	Комиссии

6. Примеры кода

Python examples/sign.py
Node.js examples/sign.js

Python (создание PayIn)

import hashlib, hmac, json, time, uuid, requests

def sign(body):
    exp = str(int(time.time()) + 300)
    payload = json.dumps(body, separators=(",", ":"))
    sig = hmac.new(SECRET.encode(), (exp + payload).encode(), hashlib.sha256).hexdigest()
    return {"X-API-Key": API_KEY, "Expires": exp, "X-API-Sign": sig,
            "X-Nonce": str(uuid.uuid4()), "Content-Type": "application/json"}

body = {"externalID": "order-42", "currency": "RUB", "amount": "1000", "type": "card"}
requests.post("https://api.bet-flow.com/v1/payin", json=body, headers=sign(body))

7. Legacy API

Для старых интеграций: POST /v1/payment, GET /v1/account/*. Новые проекты — только v2.

Полная спецификация: OpenAPI / Redoc · Markdown: INTEGRATION.md