Events

Paymos publishes 13 event types: 8 for invoices and 5 for withdrawals. Subscribe by category at the endpoint level; event names inside a category are not individually selectable.

Invoice events

Event	Meaning	Terminal
invoice.awaiting_payment	A deep reorg removed every counted transfer and the invoice regressed to awaiting payment. The initial transition into awaiting payment does not emit this event	No
invoice.confirming	A payment was detected and is waiting for the required blockchain finality	No
invoice.underpaid_waiting	The received amount is below the expected amount and the invoice can still accept payment	No
invoice.paid	The expected amount was paid	Yes
invoice.paid_over	More than the expected amount was paid; the full received amount is credited	Yes
invoice.underpaid	The invoice reached a final underpaid state	Yes
invoice.expired	The invoice expired without a qualifying payment	Yes
invoice.cancelled	The merchant cancelled the invoice	Yes

Withdrawal events

Event	Meaning	Terminal
withdrawal.created	The withdrawal was accepted and created	No
withdrawal.processing	The outgoing transaction was observed on-chain and its transaction hash is available	No
withdrawal.completed	The outgoing transaction completed on-chain	Yes
withdrawal.failed	The withdrawal failed and reached a final state	Yes
withdrawal.cancelled	The withdrawal was cancelled before completion	Yes

Processing rules

• Route by the exact event_type; ignore unknown future types safely and alert for review.
• Read data.status and data.is_final from the payload instead of reconstructing state from the event name.
• Do not assume delivery order. Parallel delivery and retries can make a newer resource snapshot arrive first.
• A terminal event is final for that resource state machine. Repeated delivery of the same event_id is still a duplicate, not another transition.

See Payload contract for the common envelope and resource fields.