PAYSTAR / ДОКУМЕНТАЦИЯ ДЛЯ РАЗРАБОТЧИКОВ
Callback и события
Обновления платежей и операционные оповещения — отдельные интерфейсы с разными исходными данными подписи.
[01]
Платёжные callback
Получайте настроенные события заявок на своём сервере. Прежний интерфейс описывает HTTP POST на заданный URL с заголовком Signature в запросе.
Исправление P2P: Failed → SuccessПодтверждено владельцем API · только P2P
Подтверждено владельцем API 10 сентября 2026. Та же заявка P2P может быть исправлена из Failed в Success, обычно по инициативе поддержки мерчанта. Сохраните её существующий PayStar externalId и идентификатор мерчанта externalTransactionId; это не новая заявка.
| Сохранённый результат P2P | Входящее обновление | Бизнес-обработка мерчантом |
|---|---|---|
| Failed | Success | После проверки callback по согласованной спецификации профиля обновите существующую заявку до Success. Не отклоняйте обновление только потому, что ранее зафиксирован Failed. |
| Success | Повторный Success | Обрабатывайте идемпотентно: не применяйте один бизнес-эффект дважды. Надёжный ключ доставки/дедупликации ещё нужно согласовать. |
| Success | Failed | Обратный бизнес-переход реализовывать не нужно; не понижайте сохранённый Success. Это не отменяет проверку или согласованное подтверждение и обработку неожиданных сообщений. |
Не удаляйте дубли всех callback только по ID заявки: изменившийся статус существующей заявки не является автоматически дублем. Тело callback, подпись, ACK и повторы по-прежнему определяются отдельной спецификацией уведомлений; здесь не вводятся новый формат JSON, HTTP-подтверждение или срок доставки.
Владелец API подтвердил жизненный цикл и обязательную обработку мерчантом, а не завершённый тест реальной доставки. Причины отказа, допускающие исправление, и его временное окно не подтверждены. Это не указание бесконечно опрашивать каждую заявку Failed.
Настройка и поля тела уведомления
Прежняя документация описывает и статический URL callback, настроенный с PayStar, и отдельный для заявки callbackUrl. Уточните приоритет и выбор событий для вашего профиля.
| Поле | Значение в прежней версии |
|---|---|
| externalId | ID заявки PayStar. |
| status | Состояние заявки в этом уведомлении. |
| amount / currency | Сумма и валюта заявки; представление суммы для подписи нужно подтвердить. |
| orderType | Deposit или Withdrawal. |
| externalParams / orderHistory | Поля зависят от сценария; доступ к чувствительным данным нужно ограничить, а сами данные маскировать. |
Это руководство, а не полная утверждённая схема тела уведомления. Прежние перепутанные карточные поля и несогласованный регистр истории не воспроизводятся.
Проверка подписи — прежний алгоритм
Описанная подпись соединяет следующие значения через точку с запятой, применяет SHA-256, затем шестнадцатеричное кодирование:
externalId;status;amount;orderType;privateKeyУточните точное представление значений и назначенный секрет по проверенному тестовому примеру. Сохраняйте подписываемые значения; не заменяйте алгоритм и не предполагайте формат сериализации чисел.
Подтверждение, повторы и дубли
Прежний источник допускает противоречивые варианты подтверждения: HTTP 200 либо любой код 2xx в ответе. Время повторов и надёжный ключ дедупликации ещё требуют согласования и теста доставки.
Перед production согласуйте тело, канонизацию, приоритет URL, ACK, политику повторов и обработку дублей. Эта документация не превращает прежнюю таблицу повторов в SLA.
Используйте Status API для установления результата неизвестного создания и проверки заявки при необходимости. Открыть методы статуса →
[02]
Операционные события
Операционные оповещения сообщают об активности аккаунта и платформы, например изменении маршрутизации или зависших заявках. Они отделены от платёжных callback и используют отдельный секрет endpoint.
Подписка и тело уведомления
Прежнее руководство настраивает пользовательский endpoint уведомлений в настройках аккаунта. Уточните у PayStar текущую доступность, флаги подписки и ротацию секрета.
| Поле | Значение |
|---|---|
| id | ID типа оповещения; не уникальный ID доставки. |
| createdAt | Точная строка времени оповещения. |
| message | Текст сообщения, который может содержать HTML и переносы строк. |
| fields | Пары метаданных Name/Content. |
Безопасно отображайте сообщение; не считайте произвольный текст уведомления доверенной исполняемой разметкой.
Подпись и границы проверки целостности
createdAt;message;endpointPrivateKeyПрежний алгоритм применяет SHA-256 к UTF-8, затем шестнадцатеричное кодирование. Сохраняйте точный текст времени, пробелы и переносы строк.
В этом описании поля id и fields остаются неподписанными. Считайте их вспомогательными метаданными, а не отдельно аутентифицированными данными. Не используйте исходные данные подписи платёжного callback.
Действующая подписка и проверенный пример подписи всё ещё необходимы. Фиксированное окно защиты от повторного воспроизведения здесь не устанавливается.
Категории событий прежней версии
Смена статусов платежей и зависшие заявки; лимиты; обновления мерчантов и pipeline; маршрутизация и каналы; настройки комиссий; изменения команды; расчёты и проблемы.
Точные актуальные ID и доступность подписок нужно подтвердить. Список категорий не является закрытым enum поддерживаемых событий.
[03]
Перед включением уведомлений
- Уточните интерфейс и используйте его собственный секрет и данные подписи.
- Проверьте заведомо корректный и изменённый тестовые примеры.
- Согласуйте обработку дублей, подтверждение и поведение повторов.
- Проверьте реальную доставку в согласованной нерабочей среде.
Нужны обязательные поля, валюты или лимиты для вашего pipeline?
Уточнить профиль у Егора ↗