BlackPay API

Подробная документация по текущей реализации BlackPay API. Структура похожа на API-формат CryptoBot, но ниже описано именно то, как API работает в вашем проекте сейчас.

Содержание

• 1. Базовая информация
• 2. Авторизация
• 3. Формат ответов и ошибок
• 4. Быстрый старт
• 5. Методы API
• 6. Важные особенности реализации

1. Базовая информация

Production URL: https://api.nl.tuna.am/api

Локально: http://127.0.0.1:1333/api

Протокол: HTTPS (production), HTTP (локально)

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

Передавайте API-токен в заголовке:

Black-Pay-API-Token: <YOUR_API_TOKEN>

Если токен отсутствует или неверный, API вернёт 401 UNAUTHORIZED.

3. Формат ответов и ошибок

Успешный ответ

{
  "ok": true,
  "result": { ... }
}

Ошибка

{
  "ok": false,
  "error": {
    "code": 400,
    "name": "ERROR_NAME",
    "message": "Error description"
  }
}

Типовые статусы: 400, 401, 403, 404.

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

Проверка токена — getMe

curl -X GET "https://api.nl.tuna.am/api/getMe" \
  -H "Black-Pay-API-Token: YOUR_TOKEN"

Проверка баланса приложения — getBalance

curl -X GET "https://api.nl.tuna.am/api/getBalance" \
  -H "Black-Pay-API-Token: YOUR_TOKEN"

5. Методы API

GET /getMe

Возвращает информацию о текущем приложении.

{
  "ok": true,
  "result": {
    "app_id": "A798724",
    "name": "Noble Robin Service",
    "payment_processing_bot_username": "blackcrypto_bot"
  }
}

GET /getBalance

Возвращает баланс приложения. Сейчас используется формат массива в result.

{
  "ok": true,
  "result": [
    {
      "currency_code": "USDT",
      "total": "100.0",
      "hold": "20.0",
      "available": "80.0"
    }
  ]
}

POST /createInvoice

Создаёт счёт, привязанный к приложению.

Важно: в текущей реализации для app-счетов поддерживается только USDT.

curl -X POST "https://api.nl.tuna.am/api/createInvoice" \
  -H "Content-Type: application/json" \
  -H "Black-Pay-API-Token: YOUR_TOKEN" \
  -d '{
    "asset": "USDT",
    "amount": "50",
    "description": "Top up app"
  }'

{
  "ok": true,
  "result": {
    "invoice_id": "INVAB12CD34EF",
    "status": "active",
    "hash": "INVAB12CD34EF",
    "asset": "USDT",
    "amount": "50",
    "pay_url": "https://t.me/blsendbot?start=invoice_INVAB12CD34EF",
    "description": "Top up app",
    "created_at": "2026-04-13T16:40:00.000000",
    "allow_comments": true,
    "allow_anonymous": true,
    "paid_at": null,
    "paid_anonymously": null
  }
}

GET /getInvoices

Список счетов приложения.

Параметры: asset, invoice_ids (через запятую), status, offset, count.

curl -X GET "https://api.nl.tuna.am/api/getInvoices?status=active&count=20" \
  -H "Black-Pay-API-Token: YOUR_TOKEN"

{
  "ok": true,
  "result": {
    "items": [
      {
        "invoice_id": "INVAB12CD34EF",
        "status": "active",
        "asset": "USDT",
        "amount": "50",
        "pay_url": "https://t.me/blsendbot?start=invoice_INVAB12CD34EF"
      }
    ]
  }
}

POST /createCheck

Создаёт чек от имени приложения.

Важно: доступ зависит от настройки безопасности приложения can_create_check.

Также сейчас поддерживается только USDT.

curl -X POST "https://api.nl.tuna.am/api/createCheck" \
  -H "Content-Type: application/json" \
  -H "Black-Pay-API-Token: YOUR_TOKEN" \
  -d '{
    "asset": "USDT",
    "amount": "10"
  }'

GET /getChecks

Список чеков приложения.

Параметры: asset, check_ids, status, offset, count.

curl -X GET "https://api.nl.tuna.am/api/getChecks?status=active&count=20" \
  -H "Black-Pay-API-Token: YOUR_TOKEN"

POST /transfer

Перевод средств с баланса приложения на основной кошелёк владельца приложения.

Важно: доступ зависит от настройки безопасности приложения can_transfer.

curl -X POST "https://api.nl.tuna.am/api/transfer" \
  -H "Content-Type: application/json" \
  -H "Black-Pay-API-Token: YOUR_TOKEN" \
  -d '{
    "asset": "USDT",
    "amount": "15"
  }'

{
  "ok": true,
  "result": {
    "asset": "USDT",
    "amount": "15",
    "transferred_at": "2026-04-13T16:42:00.000000"
  }
}

POST /setInvoiceComment

Устанавливает дефолтный комментарий, который показывается плательщику после оплаты счёта приложения.

Поле invoice_id в модели считается deprecated и игнорируется.

curl -X POST "https://api.nl.tuna.am/api/setInvoiceComment" \
  -H "Content-Type: application/json" \
  -H "Black-Pay-API-Token: YOUR_TOKEN" \
  -d '{
    "comment": "Спасибо за оплату!"
  }'

6. Важные особенности реализации

• Для методов createInvoice, createCheck и transfer сейчас поддерживается только USDT.
• Идентификаторы счетов и чеков возвращаются строками вида INV... и CK....
• Максимальное значение count в списках ограничивается до 1000.
• Если метод выключен в безопасности приложения, API вернёт 403 FORBIDDEN.
• Пополнение баланса приложения происходит через оплату счетов, созданных этим приложением.