QR Integration / Developers
API v1.0.0OpenAPI ↗
REST · JSON · SERVER TO SERVER

QR Integration API

От первого запроса до подтверждённой оплаты — с готовыми примерами для сайта и Telegram-бота.

Базовый адрес APIhttps://api.cashwellpay.com/api/v1
01

Создайте заявку

ФИО, банк, сумма и внешний ID. Ответ 202 сохраняет место в очереди.

02

Покажите QR

При ready скачайте PNG на сервере и добавьте кнопку с payment_url.

03

Дождитесь оплаты

Подтверждение приходит через GET или подписанный webhook со статусом paid.

Что понадобится

API-ключ от администратора платформы и ваш backend. Свяжите внешний ID с авторизованным пользователем и сохраните исходные данные до первого POST.

ПЕРВЫЕ ШАГИ

Первый запрос, готовый QR, статус

Выберите язык. Задайте QR_API_BASE и QR_API_KEY в окружении сервера; не передавайте ключ в браузер клиента.

Создание и получение QR
С рабочим ключом этот код создаёт реальную заявку.

Для знакомства сначала используйте учебный сценарий ниже или dart run bin/lifecycle_demo.dart из архива. Учебные сценарии не обращаются к платёжному API.

Что сохранить у себя

Внешний ID, ключ операции, исходные ФИО/банк/сумму, владельца заявки и полученный id. Это позволяет восстановиться после потери ответа.

Как выдать изображение

Скачайте PNG с Bearer на сервере. Для Telegram загрузите байты через sendPhoto; для сайта отдавайте PNG через свой маршрут с проверкой владельца.

ИНТЕРАКТИВНЫЙ ПРИМЕР

Одна заявка: 1 000 ₽ → подтверждение

Учебный сценарий с вымышленными данными. Кнопки меняют пример на странице. Реальные запросы, счета и платежи не выполняются.

DEMO · БЕЗ ЗАПРОСОВ К API
Сумма заявки1 000,00 ₽
Курс этой заявки91,5628 ₽/USDT
Расчёт после оплаты10,92146592 USDT
Результат в вашей системе

Начните с создания заявки. Исходный запрос и его ID будут сохранены в примере.

Не создана
Исходный POST /orders

Числа иллюстративные. В работе используйте trader_rate и expected_usdt из конкретной заявки.

КОНТРАКТ ЗАПРОСА

Какие данные передавать

POST /orders принимает только четыре поля. Суммы — десятичные строки; даты ответов — Unix seconds UTC.

ПолеПримерПравило
external_idобязательноmerchant-order-123Уникальный внутри площадки. 1–128 ASCII-символов; первый — буква или цифра, далее также ._:/-.
full_nameобязательноИванов Иван ИвановичПолные ФИО фактического плательщика, до 200 символов. В каждой заявке может быть другой плательщик.
bankобязательноСбербанкБанк, с которого будет оплата. 2–100 символов без управляющих символов.
amount_rubобязательно"1000.50"50–35 000 ₽, до двух знаков после точки. JSON-число, запятая, экспонента и лишние поля отклоняются.
Обязательные заголовки

Authorization: Bearer <API_KEY> и Idempotency-Key: merchant-order-123. Ключ операции имеет те же ASCII-ограничения, что и внешний ID.

Предупреждение для плательщика

Обязательно проверьте корректность введённых данных. В случае предоставления фейковых данных ваш кабинет и баланс будут заморожены. ФИО указывайте полностью: фамилию, имя и отчество, без сокращений. Для каждой заявки указывайте ФИО фактического плательщика, от которого будет оплата.

СПРАВОЧНИК

Все методы API

Откройте метод, чтобы увидеть назначение и пример ответа. Точные типы — в OpenAPI JSON.

Загружаем публичную схему…
ЖИЗНЕННЫЙ ЦИКЛ

По какому статусу принимать решение

Используйте status. Техническое generation_status может остаться ready после оплаты.

creating

Создаётся

Продолжайте GET с сохранённым ID. Ссылки ещё нет.

ready

Доступен QR

Можно скачать PNG и показать ссылку. Оплата не подтверждена.

paid

Оплачено

Зафиксируйте подтверждение один раз по ID заявки. Ссылки уже null.

cancelled

Отменено

Уберите изображение и кнопку оплаты.

expired

Срок истёк

QR недоступен. Возможен последующий статус paid при поздней оплате.

failed

QR не получен

Покажите ошибку. Новые ID не являются восстановлением исходной операции.

needs_review

Нужно уточнение

Сохраните ID, дождитесь сверки. Не создавайте автоматическую замену.

НАДЁЖНОСТЬ

Повторы без повторного счёта

До первого запроса

Сохраните пользователя, данные, external_id и Idempotency-Key в локальной записи. Затем выполняйте POST.

Если ответ потерян

Повторите прежние идентификаторы и тело. Ответ снова будет 202, но заявка уже может быть ready или paid.

Новый ключ с прежним external_id и теми же данными тоже вернёт существующую заявку. Для новой самостоятельной заявки нужен новый внешний ID. Изменение данных в повторе приводит к 409.

СитуацияДействие
Таймаут / обрывПовторить исходный POST с прежним телом и обоими ID. Потеря ответа не доказывает отказ генерации.
400 / 422Исправить формат полей; не повторять неверный запрос бесконечно.
401Проверить API-ключ и его отзыв; остановить повторы с неверным ключом.
403Проверить паузу площадки или лимиты. Существующие заявки можно читать.
404Сверить ID и площадку. Чужой ID также возвращает 404.
409Сверить данные и ID; для PNG дождаться ready. Не обходить конфликт сменой ключа.
429Выдержать Retry-After, затем повторить ту же операцию.
503 / временный сбойУвеличивать интервал между попытками. При недоступном свежем курсе новая заявка не создаётся.
408 / 413Проверить доставку и размер JSON. Тело ограничено 16 КиБ и временем приёма 10 секунд.
120 запросов / ключ / минуту20 новых заявок / ключ / минуту2–5 сек. интервал опроса

Фиксированные минутные окна. Очередь площадки также ограничена; при заполнении — 429 queue_full. Предпочитайте webhook и GET для восстановления.

ОБРАТНЫЕ УВЕДОМЛЕНИЯ

Подтверждение оплаты автоматически

Передайте администратору публичный HTTPS URL на порту 443. Для webhook выдаётся отдельный секрет. GET позволяет сверить актуальное состояние.

Заголовки входящего POST
Content-Type: application/json
X-QR-Event-ID: evt_example_paid
X-QR-Timestamp: 1795251605
X-QR-Signature: sha256=<HMAC в hex>
01Проверьте подпись

HMAC-SHA256 от timestamp + "." + raw_body. Сравнение за постоянное время; в примерах допускается ±300 секунд.

02Сохраните событие

Уникальный ID и монотонный sequence для заявки. События повторяются и могут приходить не по порядку.

03Подтвердите приём

Ответ 2xx — после устойчивой записи. Бизнес-действие также защищается по ID заявки.

order.updated · подтверждённая оплата
Дедупликация события и защита от повторного начисления — разные проверки.

Оплаченная заявка может снова прийти в более новом событии после уточнения. Уникальный event.id не заменяет уникальную бизнес-операцию по order.id. При расхождении запросите GET и сохраните корректировку отдельно.

Повторы, пауза и смена секрета

Доставка как минимум один раз: ID и тело стабильны, timestamp и подпись обновляются. Сетевые сбои, 408/429 и 5xx повторяются с увеличением задержки, до 20 попыток в пределах 24 часов. Постоянная ошибка, например 401, может остановить доставку раньше. После исправления получателя администратор может вернуть событие в очередь.

Пауза webhook останавливает доставку. Смена URL/секрета закрывает незавершённые события старой конфигурации и переснимает их актуальное состояние. Уже доставленную историю сверяйте GET. Промежуточные состояния могут объединяться; webhook для creating не отправляется.

Проверяющие приёмники: Dart и Node.js. Модель inbox и SQL — в руководстве для рабочего запуска.

РАСЧЁТЫ

Курс заявки и остаток USDT

Общий курс трейдера: ставка × 1,06. При создании сохраняются trader_rate и expected_usdt. Новый курс не меняет принятую заявку.

Рубли1 000,00
÷
Курс заявки91,5628
→
Возвращённый expected_usdt10,92146592

Используйте Decimal или целые минимальные единицы. Передавайте суммы строками; отображайте возвращённый expected_usdt, без собственного округления через double.

GET /balance

expected_usdt — начислено по подтверждённым оплатам; paid_usdt — отмеченные выплаты площадке; payable_usdt — остаток.

Если complete = false

Полный итог может быть null. Известный промежуточный итог не является окончательным балансом. При complete = true неоплаченные заявки всё ещё могут быть активны.

Выплаты платформы площадке и выплаты площадки своим трейдерам — разные уровни учёта. API сообщает расчёт; сам перевод USDT он не выполняет.

ГОТОВЫЕ МАТЕРИАЛЫ

Подключение на Dart и на сайте

NODE.JS

Backend для сайта

Форма, опрос, PNG, серверный ключ, локальный ID и проверка подписей. Демонстрация для одного пользователя.

Открыть server.mjs ↗

Для команды и нескольких процессов замените демонстрационные авторизацию и файловое состояние своей БД.

OFFLINE DEMO

Полный цикл без ключа

Mock-сервер в Dart: потеря ответа, восстановление, QR и повтор webhook. Без обращения к платёжному API.

Открыть учебный сценарий ↗dart run bin/lifecycle_demo.dart

Все файлы одним архивом

Dart, Node.js, контрактные проверки, полный протокол и рабочий запуск.

↓ Скачать ZIP
ПЕРЕД ПОДКЛЮЧЕНИЕМ ТРЕЙДЕРОВ

Проверьте восстановление после сбоев

  • Потерянный ответ POST восстанавливает прежнюю заявку без второго счёта.
  • После перезапуска известны владелец, ID и исходные данные заявки.
  • Повторный или старый webhook не создаёт повторного бизнес-действия.
  • Поздняя оплата после expired и needs_review учитываются без автоматического повтора платежа.
  • При закрытии заявки QR и кнопка убираются; API-ключ не попадает в браузер или Telegram.
  • При 429 соблюдается Retry-After; при ротации ключа сохраняется чтение прежних заявок.

SQL-схема, reconciliation и проверочные сценарии: рабочая интеграция. Все параметры ответов: API_INTEGRATION.md.