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

REST v1 · базовый URL: https://donpay.app

1. Авторизация

Каждый запрос авторизуется секретным ключом проекта в заголовке Authorization:

Authorization: Bearer sk_live_XXXXXXXXXXXXXXXXXXXX

Ключи выпускаются в разделе «Проекты» после одобрения. Не публикуйте секретный ключ в клиентском коде.

2. Создание платежа

POST /api/public/v1/payments

curl -X POST https://donpay.app/api/public/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "method": "sbp",
    "description": "Заказ #12345",
    "client_reference": "order_12345",
    "return_url": "https://your.site/thanks"
  }'

Поля: amount — сумма в ₽ (обяз.); method — sbp или card; client_reference — ваш ID заказа (уникальный в рамках проекта, обеспечивает идемпотентность); metadata — произвольный JSON.

Ответ:
{
  "payment": {
    "id": "0f9a…",
    "status": "pending",
    "amount": 500,
    "currency": "RUB",
    "pay_url": "https://qr.nspk.ru/...",
    "external_id": "...",
    "client_reference": "order_12345"
  }
}

Перенаправьте клиента на pay_url — он оплатит по СБП.

3. Проверка статуса

GET /api/public/v1/payments/{id}

curl https://donpay.app/api/public/v1/payments/0f9a… \
  -H "Authorization: Bearer sk_live_..."
4. Вебхуки

Когда платёж оплачен, мы шлём POST на ваш webhook_url из настроек проекта.

Заголовки:
X-DonPay-Event: payment.succeeded
X-DonPay-Signature: HMAC_SHA256(webhook_secret, raw_body)
Тело:
{
  "event": "payment.succeeded",
  "payment": {
    "id": "0f9a…",
    "project_id": "…",
    "status": "paid",
    "amount": 500,
    "net_amount": 475,
    "currency": "RUB",
    "client_reference": "order_12345",
    "external_id": "…",
    "paid_at": "2026-07-29T12:00:00Z"
  }
}

Проверяйте подпись, сравнивая HMAC-SHA256 сырого тела с заголовком X-DonPay-Signature — используйте функцию сравнения в постоянное время.

Пример (Node.js):
import crypto from "crypto";
const sig = req.headers["x-donpay-signature"];
const expected = crypto.createHmac("sha256", process.env.DONPAY_WEBHOOK_SECRET)
  .update(rawBody).digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) return res.status(401).end();

Отвечайте 200 OK — иначе мы будем считать доставку неуспешной.

5. Комиссии и вывод

С каждого платежа удерживается комиссия платформы (настраивается индивидуально при одобрении проекта). Чистая сумма зачисляется на баланс аккаунта и доступна к выводу в USDT TRC-20.

6. Коды ошибок
  • 401 unauthorized — неверный или отсутствующий ключ
  • 403 not_approved — проект ещё не одобрен
  • 400 invalid_amount / bad_json — ошибка тела запроса
  • 503 no_gateway / gateway_off — шлюз не подключён
  • 502 gateway_error / gateway_unreachable — ошибка шлюза