Payment events

Payment events are especially important when handling partial payments, retries, refunds, or reconciliation workflows.

Supported payment events

Event	Description	When it is emitted
`payment:applied`	Emitted when a payment is successfully applied to an order.	After the payment amount is reconciled and affects the order balance.
`payment:failed`	Emitted when a payment attempt fails.	When a payment cannot be completed or confirmed.
`payment:refunded`	Emitted when a payment is refunded.	After a successful refund operation.

Event semantics

`payment:applied`

This event is emitted each time a payment is applied to an order.

Typical use cases:

Update internal accounting or balances
Track partial payments
Reconcile on-chain or provider-side transactions

Note
An order may emit multiple payment:applied events before reaching the paid status.

`payment:failed`

This event indicates that a payment attempt did not succeed.

Examples:

On-chain transaction failed or reverted
Provider rejection
Invalid payment parameters
Insufficient funds

Typical use cases:

Notify the customer of a failed payment
Trigger retry logic
Log failures for reconciliation or support

`payment:refunded`

This event is emitted when a previously applied payment is refunded.

Typical use cases:

Reverse fulfillment
Update merchant balances
Reflect refunds in your accounting system

Important
Refunds do not automatically change the order status unless business rules require it. Always rely on both order and payment events when building refund logic.

Relationship between order and payment events

Payment events represent individual transactions
Order events represent aggregate state

A typical flow may look like:

One or more payment:applied events
A single order:paid event once the order is fully funded