Создайте заявку
ФИО, банк, сумма и внешний ID. Ответ 202 сохраняет место в очереди.
От первого запроса до подтверждённой оплаты — с готовыми примерами для сайта и Telegram-бота.
https://api.cashwellpay.com/api/v1ФИО, банк, сумма и внешний ID. Ответ 202 сохраняет место в очереди.
При ready скачайте PNG на сервере и добавьте кнопку с payment_url.
Подтверждение приходит через GET или подписанный webhook со статусом paid.
API-ключ от администратора платформы и ваш backend. Свяжите внешний ID с авторизованным пользователем и сохраните исходные данные до первого POST.
Выберите язык. Задайте QR_API_BASE и QR_API_KEY в окружении сервера; не передавайте ключ в браузер клиента.
Для знакомства сначала используйте учебный сценарий ниже или dart run bin/lifecycle_demo.dart из архива. Учебные сценарии не обращаются к платёжному API.
Внешний ID, ключ операции, исходные ФИО/банк/сумму, владельца заявки и полученный id. Это позволяет восстановиться после потери ответа.
Скачайте PNG с Bearer на сервере. Для Telegram загрузите байты через sendPhoto; для сайта отдавайте PNG через свой маршрут с проверкой владельца.
Учебный сценарий с вымышленными данными. Кнопки меняют пример на странице. Реальные запросы, счета и платежи не выполняются.
Начните с создания заявки. Исходный запрос и его ID будут сохранены в примере.
Числа иллюстративные. В работе используйте 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.
Обязательно проверьте корректность введённых данных. В случае предоставления фейковых данных ваш кабинет и баланс будут заморожены. ФИО указывайте полностью: фамилию, имя и отчество, без сокращений. Для каждой заявки указывайте ФИО фактического плательщика, от которого будет оплата.
Откройте метод, чтобы увидеть назначение и пример ответа. Точные типы — в OpenAPI JSON.
Используйте status. Техническое generation_status может остаться ready после оплаты.
Продолжайте GET с сохранённым ID. Ссылки ещё нет.
Можно скачать PNG и показать ссылку. Оплата не подтверждена.
Зафиксируйте подтверждение один раз по ID заявки. Ссылки уже null.
Уберите изображение и кнопку оплаты.
QR недоступен. Возможен последующий статус paid при поздней оплате.
Покажите ошибку. Новые ID не являются восстановлением исходной операции.
Сохраните 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 секунд. |
Фиксированные минутные окна. Очередь площадки также ограничена; при заполнении — 429 queue_full. Предпочитайте webhook и GET для восстановления.
Передайте администратору публичный HTTPS URL на порту 443. Для webhook выдаётся отдельный секрет. GET позволяет сверить актуальное состояние.
Content-Type: application/json
X-QR-Event-ID: evt_example_paid
X-QR-Timestamp: 1795251605
X-QR-Signature: sha256=<HMAC в hex>HMAC-SHA256 от timestamp + "." + raw_body. Сравнение за постоянное время; в примерах допускается ±300 секунд.
Уникальный ID и монотонный sequence для заявки. События повторяются и могут приходить не по порядку.
Ответ 2xx — после устойчивой записи. Бизнес-действие также защищается по ID заявки.
Оплаченная заявка может снова прийти в более новом событии после уточнения. Уникальный event.id не заменяет уникальную бизнес-операцию по order.id. При расхождении запросите GET и сохраните корректировку отдельно.
Доставка как минимум один раз: ID и тело стабильны, timestamp и подпись обновляются. Сетевые сбои, 408/429 и 5xx повторяются с увеличением задержки, до 20 попыток в пределах 24 часов. Постоянная ошибка, например 401, может остановить доставку раньше. После исправления получателя администратор может вернуть событие в очередь.
Пауза webhook останавливает доставку. Смена URL/секрета закрывает незавершённые события старой конфигурации и переснимает их актуальное состояние. Уже доставленную историю сверяйте GET. Промежуточные состояния могут объединяться; webhook для creating не отправляется.
Проверяющие приёмники: Dart и Node.js. Модель inbox и SQL — в руководстве для рабочего запуска.
Общий курс трейдера: ставка × 1,06. При создании сохраняются trader_rate и expected_usdt. Новый курс не меняет принятую заявку.
Используйте Decimal или целые минимальные единицы. Передавайте суммы строками; отображайте возвращённый expected_usdt, без собственного округления через double.
expected_usdt — начислено по подтверждённым оплатам; paid_usdt — отмеченные выплаты площадке; payable_usdt — остаток.
Полный итог может быть null. Известный промежуточный итог не является окончательным балансом. При complete = true неоплаченные заявки всё ещё могут быть активны.
Выплаты платформы площадке и выплаты площадки своим трейдерам — разные уровни учёта. API сообщает расчёт; сам перевод USDT он не выполняет.
Создание с повтором, ожидание QR, защищённый PNG, фото и кнопка оплаты. Вызывайте после собственной проверки трейдера.
HTTP-клиент ↗Telegram-адаптер ↗Webhook-приёмник ↗Форма, опрос, PNG, серверный ключ, локальный ID и проверка подписей. Демонстрация для одного пользователя.
Открыть server.mjs ↗Для команды и нескольких процессов замените демонстрационные авторизацию и файловое состояние своей БД.
Mock-сервер в Dart: потеря ответа, восстановление, QR и повтор webhook. Без обращения к платёжному API.
Открыть учебный сценарий ↗dart run bin/lifecycle_demo.dartSQL-схема, reconciliation и проверочные сценарии: рабочая интеграция. Все параметры ответов: API_INTEGRATION.md.