Skip to content
Ask the docs

Find answers across the QairoPay docs.

Type a question and we'll synthesize an answer from the docs with citations back to the source pages.

Changelog

We version the API by date (2026-05-19). Each entry lists what changed and whether it’s breaking. Breaking changes never apply to your traffic until you opt in (see Versioning).

2026-05-19 — current

Breaking changes

  • cards.spending_controls.allowed_categories removed in favor of blocked_categories. Translate allowed → all-known-minus-allowed when migrating.
  • dispute.reason enum: customer_dispute renamed to customer_complaint to match card-network terminology.
  • settlement.lines[].type now uses snake_case (card_transaction instead of cardTransaction).

Additions

  • New event cardholder.sanctions.alert — emitted when an ongoing-monitoring screen flags a previously-cleared cardholder.
  • New endpoint POST /v1/payouts for on-chain USDC payouts to allowlisted Aptos addresses.
  • New previous_attributes field on all *.updated events.
  • Pass templates support a new relevant_locations array for geofenced notifications.

Fixes

  • passes.list correctly returns archived passes when include_archived=true. Previously they were always excluded.

2026-02-01

Breaking changes

  • Idempotency keys are now required on all POST endpoints. Requests without one return 400 invalid_parameter instead of being processed.
  • Webhook signature header renamed from X-QairoPay-Signature to QairoPay-Signature (no X- prefix per IETF guidance).
  • card.transaction.merchant.category_code now returns the four-digit MCC string; previously it returned QairoPay-normalized labels.

Additions

  • Real-time authorization decisioning endpoint (Enterprise tier).
  • Bulk endpoints: POST /v1/passes/batch, POST /v1/passes/batch_revoke.
  • The TypeScript SDK now ships an async iterator for every list endpoint.

2025-11-01 — deprecated 2027-02-01

Initial Phase 2 API surface.

This version is the first to include Spend Card and USDC settlement. It is supported until 2027-02-01. Migrate to 2026-02-01 or later before then.

Additions

  • Spend Card API: cardholders, cards (virtual / physical), transactions, disputes.
  • Settlement API: settlements, payouts, treasury reports.
  • Webhook events for card, transaction, dispute, settlement, and payout lifecycles.
  • Provisioning payload endpoints for Apple Pay / Google Pay.

2025-06-01 — deprecated 2027-02-01

Initial Phase 1 API surface.

Pass-only API. Templates, passes, scans, basic webhooks. Supported until 2027-02-01.

Subscribe to changelog updates via RSS at /changelog.xml. Email announcements go out to the contact on file for every version; you can also opt into a separate developers@ mailing list for engineering-only notes.