This is the canonical event list. The shape of data for each event matches the same resource shape returned by the corresponding GET endpoint in the API reference.
Pass events
| Event | When it fires | Notable fields |
|---|
pass.created | A pass is issued. | data.pass |
pass.installed | The holder adds the pass to a wallet for the first time. | data.pass, data.pass.platform (apple/google) |
pass.updated | Any field on the pass changes. | data.pass, previous_attributes |
pass.scanned | A scanner reads the pass barcode or NFC payload. | data.scan (scanner id, lat/long, verification result) |
pass.revoked | The pass is revoked. | data.pass.revoke_reason |
pass.removed | The holder removes the pass from the wallet. | data.pass |
Pass template events
| Event | When it fires |
|---|
pass_template.created | A template is created. |
pass_template.updated | A template is edited; updates fan out to all issued passes. |
pass_template.archived | A template is archived. No new issuance allowed. |
Card events
| Event | When it fires | Notable fields |
|---|
card.created | A virtual or physical card is issued. | data.card |
card.shipped | A physical card has been printed and handed off to the carrier. | data.card.shipping.tracking_number |
card.activated | The cardholder activates the card. | data.card |
card.suspended | The card is suspended (by you, the cardholder, or fraud rules). | data.card.suspend_reason |
card.resumed | A suspended card is resumed. | data.card |
card.terminated | The card is permanently terminated. | data.card.terminate_reason |
Transaction events
| Event | When it fires | Notable fields |
|---|
card.transaction.authorized | The network requests an authorization. Fires before approval. | data.transaction.merchant, data.transaction.amount_cents |
card.transaction.declined | The network or sponsor bank declined. | data.transaction.decline_reason |
card.transaction.captured | The merchant has captured a previously authorized transaction. | data.transaction |
card.transaction.refunded | A refund posted. | data.transaction.refunds |
card.transaction.reversed | A previously captured transaction was reversed. | data.transaction |
Real-time authorization (opt-in)
If you opt into real-time authorization decisioning (Enterprise feature):
| Event | When it fires | Response budget |
|---|
card.transaction.authorization_request | Synchronous webhook before the network response. Reply with { approve: true } or { approve: false, decline_reason: "..." }. | 1.5 seconds |
If you don’t respond in time we fall back to the static spending controls.
Dispute events
| Event | When it fires |
|---|
dispute.created | A dispute is filed. |
dispute.updated | The dispute moves between stages (needs_response → submitted → won / lost). |
dispute.evidence_required | The sponsor bank needs more evidence by a deadline. |
Cardholder / KYC events
| Event | When it fires |
|---|
cardholder.created | A cardholder record is created. |
cardholder.kyc.completed | Persona has returned a verification result. |
cardholder.kyc.requires_action | Persona has flagged the verification for manual review. |
cardholder.sanctions.alert | An ongoing-monitoring sanctions or PEP hit fired. The cardholder is automatically frozen pending review. |
Settlement and payout events
| Event | When it fires |
|---|
settlement.scheduled | A settlement is queued for the next netting cycle. |
settlement.completed | USDC has landed in your treasury wallet on Aptos. The on-chain tx hash is in the payload. |
settlement.failed | The on-ramp leg failed; manual review opened. |
payout.created | A payout request was accepted. |
payout.completed | The off-ramp fiat payout (or on-chain payout) has settled. |
payout.failed | The payout was rejected or returned. |
Program lifecycle
| Event | When it fires |
|---|
program.activated | Your KYB and program setup completed; live issuance is now allowed. |
program.suspended | A regulator, sponsor bank, or QairoPay risk action suspended issuance. |
program.resumed | Suspension lifted. |
| Event | When it fires |
|---|
promotion.created | A sandbox → live (or vice versa) promotion was performed. |
webhook_endpoint.disabled | An endpoint hit the retry-exhaustion threshold and was auto-disabled. |
api_key.created / .revoked | A key was created or revoked in the dashboard. |
A note on payload stability
Within a given api_version, the shape of data for each event is stable. New optional fields may appear; required fields cannot disappear. When QairoPay ships a new API version, the version is pinned per-tenant — events keep arriving in the version you have pinned. See Versioning for how to bump safely.