Events

Paymos publishes 16 event types: 8 for invoices, 5 for withdrawals and 3 for payment channels. 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

Payment channel events

Event	Meaning	Terminal
payment_channel.deposit.confirming	A transfer arrived at a channel address and is waiting for the required blockchain finality	No
payment_channel.deposit.reorged	A chain reorganization dropped the transaction. The same deposit can return to confirming if it is re-included	No
payment_channel.deposit.confirmed	The deposit settled and the net amount is credited to your balance	Yes

There is no failed event: a deposit that reorgs and never returns simply stays reorged.

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.
• Deduplicate business state on the resource id inside data (inv_…, wdr_…, pcd_…), which is stable across every transition and every endpoint. event_id identifies one delivery, not one payment.

See Payload contract for the common envelope and resource fields.