Документация API

Базовый цикл: создать инвойс → отправить клиента на страницу оплаты → получить подписанный webhook. Префикс /v1. Аутентификация — заголовок X-Api-Key.

OpenAPI 3 спека (JSON) Получить ключи

Поддерживаемые сети

1. Создать инвойс

POST /v1/invoices
X-Api-Key: pk_...
Idempotency-Key: order-1042        # необязательно, защищает от дублей
Content-Type: application/json

{ "network": "ton", "asset": "USDT", "amount": "25.00", "order_id": "1042" }

Ответ содержит id, pay_address, pay_uri, expires_at. Отправьте покупателя на /pay/.

2. Статус инвойса

GET /v1/invoices/<id>
X-Api-Key: pk_...
→ { "status": "paid", "amount_received": "25", "settlement": { "net": "...", "revenue": "..." } }

Статусы: pending → detected → paid (а также underpaid/overpaid/expired).

3. Webhook

При смене статуса шлём POST на ваш webhook URL. Заголовок X-Signature = HMAC-SHA256(тело, api_secret). Проверьте подпись и свежесть (timestamp) до обработки.

// Node — signature check
import crypto from "node:crypto";
const sig = crypto.createHmac("sha256", API_SECRET).update(rawBody).digest("hex");
if (sig !== req.headers["x-signature"]) return res.sendStatus(401);
const evt = JSON.parse(rawBody);            // event: invoice.paid, ...
if (Date.now() - new Date(evt.timestamp) > 5*60_000) return res.sendStatus(400); // anti-replay

Хардненинг

• Idempotency-Key на создание инвойса — ретраи не плодят дубли.
• Rate limit 120 запросов/мин на ключ.
• Webhook: X-Signature (HMAC), X-Webhook-Id (идемпотентность), timestamp (anti-replay).