Payment events
Payment events use the v1.collection.payment_request.payment.* prefix. They report an individual payment from processing through confirmed receipt and Hubpay wallet credit.
Overview
Payment events trigger whenever a payment moves through its life-cycle against a payment request, we emit a webhook so your system can react in real-time (update UI, trigger fulfilment, etc.).
Event catalogue
| Event | When it triggers |
|---|---|
v1.collection.payment_request.payment.created | Reserved for future use. Intended to represent an initial state |
v1.collection.payment_request.payment.pending | Authorised (card), reported as sent (bank transfer), or queued immediately before received when a confirmed crypto deposit is processed |
v1.collection.payment_request.payment.received | Crypto confirmed on-chain, card captured, or bank funds received. For crypto, compliance and later processing may still be in progress |
v1.collection.payment_request.payment.completed | The payment completed and the merchant's Hubpay wallet was credited; applicable crypto compliance gates have cleared |
v1.collection.payment_request.payment.failed | Payment failed due to error or rejection |
v1.collection.payment_request.payment.reversed | Reserved for future use. Intended to represent a post-completion reversal |
Event flow
For crypto, payment.received means the provider confirmed the deposit on-chain. Sender verification, KYT and remitter screening can still be pending, and the provider conversion and fiat-settlement stages are internal. Use payment.completed and confirm API status COMPLETE; this follows applicable compliance clearance, settlement reconciliation and Hubpay wallet credit. See Payment lifecycle and webhooks for the full sequence.
Additional data
Each payment.* event includes the following properties in the data object:
{
"paymentRequestId": "8a282576-18c0-4c0e-b158-44b92eda1afe"
}
Payment events also include paymentId and paymentReference. Additional fields may be present depending on the event type.
See Event format for the webhook envelope schema.
