События

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

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

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

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

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

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

Событие	Значение	Терминальное
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 идентифицирует одну доставку, а не один платёж.

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

• invoice.paid_late — факт рядом с терминальным решением, не переход: по нему нельзя отметить заказ оплаченным, ошибочным или отменённым. Добавьте заметку к заказу (идемпотентно на инвойс) и не меняйте решение.