Event catalog

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.

Payment events

Event	When it fires
`payment.authorized`	Risk checks passed; payment is authorized.
`payment.needs_confirmation`	Holder approval required before capture.
`payment.confirmed`	Biometric verification completed.
`payment.captured`	On-chain transaction finalised.
`payment.refunded`	Refund processed on the payment.
`payment.voided`	Authorization cancelled before capture.
`payment.failed`	Sponsor transaction failed on-chain.
`payment.risk_declined`	Spending rule blocked authorization.

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.

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.

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.
`dispute.expired`	The dispute window closed without a response; outcome recorded.

Settlement events

Event	When it fires
`payment.settlement_batch_completed`	A USDC settlement batch was confirmed on-chain. Payload includes the Aptos transaction hash.
`payment.settlement_batch_failed`	A settlement batch failed on-chain; manual review opened.
`payment.settlement_retry_requested`	A super-admin queued a failed payment for retry.
`payment.settlement_manually_triggered`	A super-admin manually triggered the settlement cycle.

Billing events

Event	When it fires
`billing.trial_started`	Tenant started a 30-day trial.
`billing.plan_changed`	Plan tier changed via self-serve or admin action.
`billing.subscription_canceled`	Subscription set to cancel at period end.
`billing.payment_method_updated`	A new payment method was attached to the tenant.
`billing.addon_toggled`	A metered add-on was enabled or disabled.
`billing.portal_accessed`	A Stripe Customer Portal session was created.
`billing.enterprise_quote_requested`	A sales-assisted quote was requested.
`billing.dunning_state_overridden`	Super-admin overrode the tenant’s dunning state.
`billing.enterprise_quote_provisioned`	Super-admin provisioned an enterprise plan for the tenant.

Webhook delivery events

When an endpoint is automatically disabled after exhausting its retry budget, a webhook_endpoint.disabled event is emitted to all other active endpoints on your account.

Event	When it fires
`webhook_endpoint.disabled`	An endpoint hit the 5-attempt retry-exhaustion threshold and was auto-disabled.

Sample payload:

{
  "id": "wevt_01HXYZ",
  "type": "webhook_endpoint.disabled",
  "created": 1716144300,
  "api_version": "2026-04-01",
  "data": {
    "endpoint_id": "whe_01HABC",
    "disabled_reason": "retry_exhausted",
    "attempt_count": 5
  }
}

To re-enable the endpoint after fixing the underlying connectivity issue:

curl -X PATCH https://api.qairopay.com/v1/webhook-endpoints/whe_01HABC \
  -H "Authorization: Bearer $QAIROPAY_API_KEY" \
  -d '{"status": "enabled"}'

See Retries and delivery for the full auto-disable flow.

Other events

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.
`api_key.created`	An API key was created in the dashboard.
`api_key.revoked`	An API key was revoked.

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.