Платежи и расчёты.

Подключение и адреса

Зарегистрируйтесь самостоятельно на https://delta.ququgate.com/: будет создан test sandbox. Live-проект создаёт администратор после рассмотрения заявки. В кабинете зарегистрируйте домены возврата, URL уведомлений и секрет подписи. Затем выпустите ключ API. Секретное значение ключа показывается один раз.

Каждый запрос ограничен проектом и окружением ключа. API, история, кошелёк и данные уведомлений чужого проекта недоступны. Test и Live используют независимые проекты, ключи и проводки.

Регистрация, проекты и согласование live

На delta.ququgate.com нажмите «Зарегистрироваться»: название, логин от 3 символов, пароль от 12 символов, сайт необязательно. Регистрация создаёт только test sandbox. Email, если используется как логин, не считается подтверждённым. Есть лимиты регистрации по адресу и глобально.

В кабинете настройте HTTPS origin возврата, callback и его отдельный секрет. Создайте test-ключ, скопируйте один раз и храните на сервере. При потере отзовите ключ и выпустите новый. Префиксы новых ключей qg_test_ и qg_live_; принадлежность определяется записью в базе, а не строкой префикса.

Для live заполните сайт и описание бизнеса. Заявка pending рассматривается администрацией: approved создаёт отдельный live-проект с новым секретом уведомлений; rejected содержит комментарий. Платежи, API-ключи, баланс и условия test не переносятся в live.

Выберите одобренный live-проект в переключателе, проверьте настройки callback/return origins, включите 2FA и создайте live-ключ. Только администратор может одобрить заявку; merchant API не позволяет менять environment, права или тарифы.

Самостоятельный test sandbox

Новый test-проект не требует ключей или доступности расчётного партнёра. Создайте платёж на 1–5 EUR и откройте payment_url. На странице есть отметка TEST. Кнопка продолжения открывает тестовый экран: processing, awaiting settlement, complete или cancel.

Действия sandbox обновляют тот же журнал платежей, EUR ledger и очередь подписанных уведомлений проекта. Callback идемпотентен. На live-платеже маршрут симуляции возвращает 404. В sandbox нет выбора реального банка: GET /banks возвращает пустой каталог.

Для нового sandbox установлен демонстрационный курс 1 EUR = 1 USDT с нулевой комиссией и без удержаний. Это условные тестовые суммы, не рыночная котировка и не реальные деньги. Администратор может настроить тестовые удержания. На live эти условия не копируются.

Уведомления test и live имеют environment; поле simulated дополнительно помечает локальную симуляцию. Никогда не выдавайте реальный товар на основании test-платежа. Реальные bank login, списание и callback провайдера проверяются отдельно при live-приёмке.

curl --request POST 'https://kappa.ququgate.com/v1/payments'   --header 'Authorization: Bearer <test-project-key>'   --header 'Content-Type: application/json'   --header 'Idempotency-Key: sandbox-order-001'   --data '{"merchant_order_id":"sandbox-order-001","method":"open_banking","amount":"4.00","currency":"EUR","return_url":"https://shop.example/result"}'
# Сначала зарегистрируйте https://shop.example в origins проекта.
# Откройте payment_url, выберите результат на тестовом экране.

Первый запуск и ежедневная работа

После регистрации откройте «Подготовка проекта». Для sandbox есть кнопка «Создать тестовый платёж · 4 EUR»: разрешённый домен возврата кабинета добавится автоматически. Откройте созданную ссылку и выберите результат; реальные деньги и банк не используются. Для повторной попытки после сетевой ошибки используется тот же Idempotency-Key.

Для своей интеграции настройте домен возврата магазина, серверный callback и секрет, создайте API-ключ. Проверка готовности отдельно показывает настройки, обработчик, ключ, 2FA, доставку уведомлений и действующий курс USDT. Это проверка конфигурации, а не доказательство успешного реального платежа.

Проверка доставки уведомлений относится к текущим URL и секрету. После их изменения прежняя успешная доставка не считается проверкой нового подключения. История доставки доступна в деталях платежа.

В кабинет добавлена смена пароля: текущий пароль, новый от 12 символов и код 2FA, если включена. Все cookie-сеансы аккаунта завершаются; API-ключи остаются действующими и управляются отдельно. Самостоятельное восстановление забытого пароля по email не предоставляется.

Платежи выгружаются CSV с текущими фильтрами, журнал USDT — отдельным CSV. Выгрузка ограничена выбранным проектом и окружением, суммы записаны точными десятичными строками, время UTC. Это последовательное чтение текущего учёта, а не замороженный снимок статусов при одновременном обновлении платежей.

При переключении проекта данные предыдущего проекта очищаются, запоздалые ответы игнорируются. Заголовок X-Project-ID в запросах кабинета защищает от отправки действий из устаревшей вкладки; при несовпадении возвращается 409. Ошибка загрузки одного раздела не завершает сессию всего кабинета.

Live-приёмку администратор проверяет отдельно: реальное подтверждение банка и коррелированный callback провайдера. Успешный sandbox не заменяет эту проверку. В кабинете оператора live-приёмка отображается отдельно от работоспособности обработчика.

Авторизация и ключи

Передавайте Authorization: Bearer <project-api-key>. Для JSON-запросов нужен Content-Type: application/json. Ключ нельзя помещать в URL, публичный JavaScript магазина или логи. Кабинет позволяет выпускать и отзывать ключи своего проекта.

API-ключи и токены сессий хранятся на сервере в виде хэшей. Вход в кабинет поддерживает 2FA. Изменения через API кабинета требуют cookie сессии и X-CSRF-Token из GET /api/merchant/session. Bearer API и cookie API кабинета разделены.

curl 'https://kappa.ququgate.com/v1/methods' \
  --header 'Authorization: Bearer <project-api-key>'

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

POST /payments принимает запрос и устойчиво сохраняет операцию до ответа 202. Передайте обязательный Idempotency-Key длиной до 200 символов. При сетевой ошибке повторите тот же JSON с прежним ключом: API вернёт тот же платёж (200), не создавая новый запрос обработки.

Номер merchant_order_id уникален в проекте. Другой JSON с тем же ключом или тот же номер заказа с другим ключом отклоняется с 409. Сумма передаётся десятичной строкой: EUR, максимум два знака. Test: 1–5 EUR, Live: 1–15000 EUR.

return_url должен иметь HTTPS origin из зарегистрированного списка проекта. URL возврата покупателя и URL серверных уведомлений выполняют разные задачи. Возврат браузера не подтверждает оплату.

curl --request POST 'https://kappa.ququgate.com/v1/payments' \
  --header 'Authorization: Bearer <project-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-2026-001-create' \
  --data '{"merchant_order_id":"order-2026-001","method":"open_banking","amount":"4.00","currency":"EUR","return_url":"https://shop.example/payment-result"}'

{
  "id": "<payment-id>",
  "merchant_order_id": "order-2026-001",
  "status": "queued",
  "amount": "4.00",
  "currency": "EUR",
  "settled": false,
  "payment_url": "https://astra.ququgate.com/c/<opaque-token>",
  "environment": "test",
  "created_at": 1794220000.0,
  "updated_at": 1794220000.0
}

Методы, банки и плательщик

GET /methods возвращает разрешённые операции, валюту, лимиты и enabled. GET /banks?country=DE возвращает банки нужной страны; без country — весь доступный каталог. Bank ID непрозрачен и не переносится в другой проект или окружение. Обновляйте каталог перед выбором банка.

Если банк не выбран, покупатель выберет его на странице оплаты. required_fields перечисляет дополнительные поля payer. additional_fields_at_checkout=true означает, что оставшиеся сведения покупатель введёт на форме. Пароли и одноразовые коды банка API не принимает.

В customer.ip указывается реальный IP покупателя. При включённой проверке имени/IP обязательны достоверные customer.full_name и customer.ip. Подстановка IP сервера магазина или фиктивного имени может помешать оплате.

Статусы и подтверждение

Текущее состояние читается через GET /payments/{id}. Нормальный цикл: queued → awaiting_customer → pending → settlement_pending → succeeded. Стадии могут быть пропущены, если финальное подтверждение получено раньше промежуточного.

Товар или услугу следует считать окончательно оплаченными только при succeeded и settled=true. Предварительное принятие ещё может закончиться отменой. Повторный или запоздавший callback не должен давать повторный зачёт.

История платежей и событий

История хранится на сервере внутри проекта и сохраняется после перезапуска. Платёж содержит устойчивый ID, номер заказа, сумму, валюту, среду, текущий статус и время создания/изменения. Отдельный журнал содержит принятые переходы состояний и время каждого события.

Для полной выгрузки используйте GET /history/payments. Ответ содержит items и next_cursor. Передавайте next_cursor следующему запросу без изменения фильтров. Так страницы не теряют записи даже при одинаковом времени создания. Новые платежи, появившиеся позднее первой страницы, доступны после обновления истории с начала.

Фильтры: status, since (включительно), until (исключительно), limit 1–100. Время — Unix seconds UTC. Курсор связан с проектом и фильтрами; чужой, повреждённый или несовместимый курсор отклоняется. Число записей на странице можно менять. Фильтр статуса отражает состояние на момент каждого запроса; это не снимок всей базы на одну дату.

GET /payments/{id}/events возвращает события этого платежа. Повторные доставки одного события не добавляют повторный переход. Старый GET /payments?before=timestamp остаётся совместимым; для полной истории используйте курсоры.

GET /v1/history/payments?status=succeeded&limit=25
Authorization: Bearer <project-api-key>

{
  "items": [ { "id": "<payment-id>", "status": "succeeded", "amount": "4.00", "currency": "EUR", "…": "остальные поля платежа" } ],
  "next_cursor": "<opaque-cursor-or-null>"
}

Кошелёк проекта

У каждого проекта есть свой учётный кошелёк EUR. Его сумма относится только к этому проекту и окружению. GET /wallets возвращает список кошельков; GET /balance — краткий объект кошелька; GET /wallets/{id} — тот же объект по ID.

pending — предварительно принятые платежи, ожидающие окончательного зачисления. confirmed — сумма окончательно подтверждённых зачислений в учёте проекта. Подтверждение переводит сумму из pending в confirmed; отмена снимает pending и не увеличивает confirmed. При прямом финальном подтверждении создаётся только confirmed.

Учётный confirmed не равен сумме, доступной к выводу у расчётного партнёра. В текущем API нет выплат, возвратов, комиссий и FX. available_for_withdrawal=null и withdrawals_enabled=false означают, что такая возможность не предоставляется; null не означает нулевой остаток.

{
  "id": "<wallet-id>",
  "project_id": "<project-id>",
  "environment": "test",
  "currency": "EUR",
  "confirmed": "4.00",
  "pending": "0.00",
  "available_for_withdrawal": null,
  "withdrawals_enabled": false,
  "source": "project_ledger",
  "updated_at": 1794220000.0
}

Проводки и история баланса

GET /wallets/{id}/entries возвращает неизменяемую историю проводок: items и next_cursor. Страницы можно читать с limit 1–100. У записи есть ID, payment_id, номер заказа, тип, изменение confirmed/pending и остатки после проводки.

Каждое изменение записывается сбалансированной проводкой внутри одной транзакции с изменением статуса и зачётом платежа. Одна операция не может быть зачислена повторно после повтора callback или перезапуска. Проводки не редактируются и не удаляются через API.

occurred_at — время финансового события; recorded_at — время записи в журнал. При переносе существующей подтверждённой истории запись может иметь recorded_at позднее occurred_at. Курсоры непрозрачны и связаны с кошельком проекта.

Баланс USDT, комиссия, роллинг и резерв

GET /settlement/balance возвращает учётный USDT баланс текущего проекта: available, rolling_reserve, reserve, fees, awaiting_conversion_count и awaiting_conversion_eur. EUR методы /balance и /wallets сохраняют прежний смысл и валюту. Баланс внешнего расчётного подключения читается оператором отдельно.

USDT — внутренний журнал расчётов: он не подтверждает наличие USDT в блокчейне и не является ответом внешнего API о фактическом остатке. on_chain_balance=null, withdrawals_enabled=false. В этой версии нет отправки USDT, адресов вывода, сетей TRC20/ERC20, выплат или возвратов.

Администратор задаёт условия по проекту: enabled, fee_bps, rolling_bps, rolling_days, reserve_bps. 100 basis points = 1%. Роллинг необязателен: rolling_bps=0 отключает удержание; при ненулевом проценте задайте положительный срок, например 10, 60 или 180 дней. Срок до 3650 дней. Сумма процентов роллинга и отдельного резерва не превышает 100%.

Курс — утверждённое число USDT за 1 EUR; обязательны источник, quoted_at и valid_until. Курс не загружается автоматически с биржи и не предполагает равенство EUR/USD/USDT. Условия и действующий курс фиксируются при создании платежа. Окончательный расчёт допускается только после подтверждённого succeeded и receipt.

Формула: gross=floor6(EUR×rate); fee=floor6(gross×fee_bps/10000); net=gross−fee; rolling=floor6(net×rolling_bps/10000); reserve=floor6(net×reserve_bps/10000); available=net−rolling−reserve. Все суммы — целые micro-USDT (6 знаков), без float. Округление вниз; остаток после удержаний остаётся в available.

Если условия или курс не утверждены/истекли до создания платежа, EUR receipt сохраняется, а платёж попадает в awaiting_conversion. Неизвестная USDT сумма не оценивается нулём: awaiting_conversion_eur и количество показываются отдельно. Администратор может выполнить отдельный расчёт по текущей сохранённой версии условий; действие записывается с actor.

Роллинг освобождается автоматически после receipt.created + rolling_days×86400 секунд UTC, отдельной идемпотентной проводкой в available. При остановке worker освобождение догоняется после запуска. Отдельный reserve не имеет автоматического срока: его освобождает администратор с суммой, основанием и Idempotency-Key; отрицательный остаток запрещён.

GET /settlement/entries даёт курсорную историю conversion, rolling_release и reserve_release: payment_id, deltas, время, курс/условия и срок освобождения. Новые настройки не пересчитывают старые платежи; повторный callback или освобождение не удваивает сумму. Проводки нельзя редактировать или удалять.

curl 'https://kappa.ququgate.com/v1/settlement/balance'   --header 'Authorization: Bearer <project-key>'
curl 'https://kappa.ququgate.com/v1/settlement/entries?limit=50'   --header 'Authorization: Bearer <project-key>'
# Ответ next_cursor передайте следующему запросу, пока он не станет null.

4.00 EUR × 1.100000 = 4.400000 USDT gross
fee 2.5% = 0.110000; net = 4.290000
rolling 10% = 0.429000; reserve 5% = 0.214500
available = 3.646500 USDT
После срока роллинга available = 4.075500; reserve = 0.214500.

Как различаются суммы

Платформа хранит несколько разных показателей. Не используйте их как взаимозаменяемые. Баланс расчётного партнёра относится ко всему его подключению, а не автоматически к каждому проекту.

Данные партнёра запрашиваются оператором отдельно через настроенный GET-метод. Показываются сумма, валюта, доступное к выводу при наличии такого поля, HTTP-статус и время получения. При 401/403, ошибке или неизвестной схеме новая сумма не выдумывается. Последний успешный снимок помечается устаревшим; отсутствие данных отображается без суммы.

Внешний API продавца получает только свой project_ledger. Общий баланс партнёра не раскрывается между проектами.

Уведомления продавцу

Сервер отправляет POST application/json на URL уведомлений проекта. Тело содержит event_id, type=payment.updated и payment с публичными полями платежа. Проверяйте подпись по исходным байтам тела до декодирования JSON.

X-Signature — hex HMAC-SHA256(secret, timestamp + "." + raw_body). X-Timestamp — Unix seconds. X-Event-ID совпадает с event_id тела. Рекомендуемое окно проверки timestamp — ±300 секунд. После устойчивого сохранения события отвечайте 2xx; учитывайте event_id идемпотентно.

При повторе доставки event_id остаётся прежним, timestamp и подпись обновляются. Порядок не гарантируется. До 12 попыток с увеличением интервала до часа; в кабинете доступны журнал и повтор исчерпанной failed-доставки. Redirect не выполняется.

Если URL не задан, событие имеет состояние not_configured и не отправляется. URL должен быть публичным HTTPS. При смене URL или секрета новые настройки применяются к новым платежам; сохраните предыдущий секрет до завершения старых операций.

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str):
    stamp = headers["X-Timestamp"]
    if abs(time.time() - int(stamp)) > 300:
        return False
    expected = hmac.new(
        secret.encode(), stamp.encode() + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, headers["X-Signature"])

# Затем сохраните event_id с уникальным ограничением,
# примените событие один раз и верните 2xx. Не логируйте secret.

Работа в кабинете

• Регистрация: самостоятельный test-проект; заявка и одобрение администрацией для live. Для выпуска live-ключа требуется 2FA.
• Интеграция: origins возврата, серверный callback, собственный секрет, оформление.
• Ключи: выпуск, однократное копирование, отзыв. Ключ привязан к проекту/среде.
• Платежи: создание ссылки, список с фильтрами и постраничной загрузкой, история статусов и попыток доставки.
• Кошелёк: pending, confirmed, журнал неизменяемых проводок с постраничной загрузкой.
• Подтверждённая сумма — учёт проекта. Вывод средств и произвольное редактирование баланса не предоставляются.

Логотип и оформление оплаты

Логотип размещается на https://astra.ququgate.com/brand/… . Короткий адрес https://astra.ququgate.com/brand/logo показывает текущий логотип. Загрузка доступна оператору: PNG, JPEG, WEBP, GIF или безопасный SVG, до 1 МиБ. Растровые изображения нормализуются и очищаются от метаданных; активное содержимое SVG не принимается.

Поля профиля: title, logoUrl, logoHeight, primaryColor, bgColor, spacing, radius, modalShadow. Цвет — #RRGGBB; spacing — sm/md/lg; radius/modalShadow — none/sm/md/lg. Высота логотипа — 10–500 пикселей, строка "48" или "48px".

Профиль фиксируется при создании платежа. Старые операции сохраняют свои условия. Своя страница показывает сумму, номер заказа, состояние, этапы и действие покупателя. Во время обработки повторная кнопка оплаты скрывается. Переход по начальной ссылке сам по себе не означает оплату.

В hosted-режиме подтверждение выполняется на защищённой странице платёжного партнёра; затем покупатель возвращается на QUQUGATE. Подключение собственного домена обработки настраивается оператором после согласования.

Страница оплаты: EN по умолчанию; кнопки EN/RU или ?lang=ru. Логотип: https://astra.ququgate.com/static/images/logo.png; favicon и иконки также на astra.

Хранение и восстановление истории

Платежи, принятые статусы, проводки, события и очередь уведомлений сохраняются в серверной базе. Разделение проектов и сред применяется к чтению и изменению. Перезапуск приложения не очищает финансовую историю.

Текущая версия не удаляет историю платежей и проводок автоматически. Изменения настроек и секретов не перезаписывают параметры уже принятых операций. Перенос старых подтверждённых зачислений в журнал кошелька идемпотентен и не удваивает сумму.

Для собственного отчёта последовательно прочитайте /history/payments и /wallets/{id}/entries до next_cursor=null. Время хранится как Unix seconds UTC; кабинет отображает его в часовом поясе браузера. Не размещайте персональные данные в номере заказа.

Резервное копирование и восстановление выполняются оператором. Финансовый журнал не является резервной копией: для восстановления нужны защищённая копия базы и отдельный ключ шифрования.

Ошибки и неопределённый результат

Не создавайте новый заказ, чтобы обойти unknown. Система сверяет незавершённые операции и принимает подтверждения асинхронно. До окончательного подтверждения не зачисляйте платёж повторно и не выдавайте его за успешный.

Ошибка создания с подтверждённой валидацией становится failed. Timeout или потерянный ответ остаются unknown до сверки. Противоречивые финальные события требуют расследования оператором. Старое промежуточное событие не откатывает финальное состояние.

Для поддержки сохраните payment ID и request_id ответа. Не отправляйте API-ключи, секреты, банковские пароли или OTP.

Справочник API

Машиночитаемая схема доступна по /openapi.json. Операции API кабинета описаны в текстовой версии; они используют session/CSRF и не открывают операторские настройки.