События

Paymos публикует 16 типов событий: 8 для инвойсов, 5 для выводов и 3 для платёжных каналов. Подписка настраивается по категории endpoint'а; отдельные события внутри категории не выбираются.

События инвойсов

Событие	Значение	Терминальное
invoice.awaiting_payment	Глубокий реорг удалил все учтённые переводы, и инвойс вернулся к ожиданию оплаты. Первичный переход в ожидание оплаты это событие не создаёт	Нет
invoice.confirming	Платёж обнаружен и ожидает требуемой финальности блокчейна	Нет
invoice.underpaid_waiting	Получено меньше ожидаемой суммы, но инвойс ещё может принять доплату	Нет
invoice.paid	Ожидаемая сумма оплачена	Да
invoice.paid_over	Получено больше ожидаемой суммы; мерчанту зачисляется вся полученная сумма	Да
invoice.underpaid	Инвойс перешёл в финальное состояние недоплаты	Да
invoice.expired	Инвойс истёк без подходящей оплаты	Да
invoice.cancelled	Мерчант отменил инвойс	Да

События выводов

Событие	Значение	Терминальное
withdrawal.created	Вывод принят и создан	Нет
withdrawal.processing	Исходящая транзакция обнаружена в блокчейне, доступен её хеш	Нет
withdrawal.completed	Исходящая транзакция завершена в блокчейне	Да
withdrawal.failed	Вывод завершился ошибкой и перешёл в финальное состояние	Да
withdrawal.cancelled	Вывод отменён до завершения	Да

События платёжных каналов

Событие	Значение	Терминальное
payment_channel.deposit.confirming	На адрес канала пришёл перевод, он ждёт требуемой финальности блокчейна	Нет
payment_channel.deposit.reorged	Реорганизация цепочки отменила транзакцию. Тот же депозит вернётся в confirming, если транзакция снова попадёт в блок	Нет
payment_channel.deposit.confirmed	Депозит рассчитан, сумма net зачислена на баланс	Да

События об ошибке нет: депозит, отменённый реорганизацией и не вернувшийся в цепочку, просто остаётся в reorged.

Правила обработки

• Маршрутизируйте по точному event_type; неизвестный будущий тип безопасно пропускайте и отправляйте на разбор.
• Читайте data.status и data.is_final из payload, не восстанавливайте состояние только по названию события.
• Не полагайтесь на порядок доставки. Параллельная доставка и retry могут привести более новый снимок ресурса раньше старого.
• Терминальное событие завершает state machine ресурса. Повторная доставка того же event_id остаётся дублем, а не новым переходом.
• Дедуплицируйте бизнес-состояние по идентификатору ресурса внутри data (inv_…, wdr_…, pcd_…): он одинаков для всех переходов и всех endpoint'ов. event_id идентифицирует одну доставку, а не один платёж.

Общая оболочка события и поля ресурсов описаны в Контракте тела события.