К статьям BlackPay

BlackPay API

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

Тестирование API: для быстрого старта используйте готовый тестовый бот.

Скачать Test API Bot (MEGA)

Содержание

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

Production URL: https://api.blackcrypto.pro/api

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

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

Все методы ниже требуют заголовок авторизации Black-Pay-API-Token.

Нужен готовый клиент для ручных проверок?

Скачать Test API Bot (MEGA)

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, 409, 502.

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

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

curl -X GET "https://api.blackcrypto.pro/api/getMe" \
  -H "Black-Pay-API-Token: YOUR_TOKEN"

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

curl -X GET "https://api.blackcrypto.pro/api/getBalance" \
  -H "Black-Pay-API-Token: YOUR_TOKEN"

Если хотите тестировать не через curl, а через интерфейс с кнопками:

Скачать Test API Bot (MEGA)

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.blackcrypto.pro/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.blackcrypto.pro/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.blackcrypto.pro/api/createCheck" \
  -H "Content-Type: application/json" \
  -H "Black-Pay-API-Token: YOUR_TOKEN" \
  -d '{
    "asset": "USDT",
    "amount": "10"
  }'

POST /activateCryptoBotCheck

Активирует чек CryptoBot через userbot и зачисляет сумму на баланс приложения.

Важно: поддерживается только USDT. Один и тот же чек можно зачислить только один раз для приложения.

curl -X POST "https://api.blackcrypto.pro/api/activateCryptoBotCheck" \
  -H "Content-Type: application/json" \
  -H "Black-Pay-API-Token: YOUR_TOKEN" \
  -d '{
    "check_link": "https://t.me/CryptoBot?start=CQKpqT0JjHXq"
  }'
{
  "ok": true,
  "result": {
    "app_id": "A798724",
    "status": "credited",
    "check_code": "CQKpqT0JjHXq",
    "asset": "USDT",
    "amount": "0.1",
    "activated_at": "2026-04-27T23:55:00.000000",
    "total": "1.12",
    "hold": "0",
    "available": "1.12"
  }
}

Если этот чек уже обрабатывался ранее для данного приложения, API вернёт ошибку:

{
  "ok": false,
  "error": {
    "code": 409,
    "name": "CHECK_ALREADY_PROCESSED",
    "message": "This CryptoBot check was already processed for this app"
  }
}

POST /createCryptoBotWithdrawCheck

Создаёт CryptoBot-чек на вывод из баланса приложения и возвращает ссылку активации.

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

curl -X POST "https://api.blackcrypto.pro/api/createCryptoBotWithdrawCheck" \
  -H "Content-Type: application/json" \
  -H "Black-Pay-API-Token: YOUR_TOKEN" \
  -d '{
    "asset": "USDT",
    "amount": "0.5"
  }'
{
  "ok": true,
  "result": {
    "asset": "USDT",
    "requested_amount": "0.5",
    "amount": "0.5",
    "bot_check_url": "https://t.me/CryptoBot?start=CQ...",
    "status": "active",
    "created_at": "2026-04-27T23:57:00.000000",
    "total": "0.62",
    "hold": "0",
    "available": "0.62"
  }
}

GET /getChecks

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

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

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

POST /transfer

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

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

curl -X POST "https://api.blackcrypto.pro/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.blackcrypto.pro/api/setInvoiceComment" \
  -H "Content-Type: application/json" \
  -H "Black-Pay-API-Token: YOUR_TOKEN" \
  -d '{
    "comment": "Спасибо за оплату!"
  }'

Для проверки всех методов по кнопкам (включая activateCryptoBotCheck и createCryptoBotWithdrawCheck):

Скачать Test API Bot (MEGA)

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

Если нужно, следующим шагом добавим в эту страницу разделы с примерами на Python/JavaScript и таблицу всех возможных ошибок для каждого метода.