Glossary

If a term shows up in the docs and a non-specialist might pause on it, it’s defined here. Skim once on the way in, then keep this page open in a tab.

Platform

Tenant: A legal entity (or division of one) operating a QairoPay program. Every API resource is scoped to exactly one tenant. See Tenancy model.
Workspace: An account that holds one or more tenants. Workspace admins can switch between tenants in the dashboard.
Sandbox / Live: The two operationally-identical environments. Sandbox is for development and CI; Live runs real money. Keys never cross. See Sandbox vs live.
API version: A dated snapshot of the API contract (e.g. 2026-05-19). Versions are pinned per tenant; new versions ship roughly quarterly. See Versioning.
Promotion: A first-class verb that copies resource configuration (templates, card programs, webhook endpoints) from sandbox to live. Data is never promoted — only config.

API key: Bearer token used for first-party server-to-server calls. Prefixed qp_sk_ (secret) or qp_pk_ (publishable). See Authentication.
Publishable key: A safe-to-expose key for browser-side calls — limited to pass-template reads and card-field tokenization.
OAuth 2.1 + PKCE: The grant flow third-party platforms use to act on behalf of a QairoPay merchant. Refresh tokens rotate every use.
Webhook signing secret: An HMAC-SHA256 key per webhook endpoint. We sign every outbound delivery; you verify before acting. See Signing.
Idempotency key: A unique string you generate per logical operation. Retries with the same key return the original result. Required on every write endpoint. See Idempotency.
MFA challenge: A one-time second-factor proof required for sensitive admin operations. Surfaced as factor_required in error responses.

Pass: A branded entry in Apple Wallet or Google Wallet — loyalty, membership, coupon, event ticket, boarding pass, or gift card.
Template: The visual and behavioral mold for issued passes. Define once, issue many times.
NFC payload: The bytes a pass emits when tapped against a reader. Signed by your tenant’s NFC envelope key.
Geofence: A lat/long + radius that triggers a wallet notification when the holder enters it.
Scanner SDK: iOS / Android / Linux POS library that reads QairoPay passes and verifies signatures offline.

Cardholder: The end user who carries a QairoPay Spend Card. KYC’d through Persona at first issuance.
Issuing bank (sponsor bank): The chartered U.S. bank that legally issues the Spend Card. QairoPay operates the program; the bank is the contractual issuer.
Processor: The regulated entity that operates the card-network connectivity. Holds the PAN; QairoPay only sees tokens.
Spending controls: Static rules (daily limit, monthly limit, blocked categories, blocked merchants) enforced by the card network in real time.
Real-time auth decisioning: Enterprise feature: a synchronous webhook on every authorization with a 1.5-second response budget for approve/decline.
Dispute: A cardholder challenge to a posted transaction. Filed via QairoPay, executed by the sponsor bank on the card network.
Authorization vs capture: Authorization reserves funds; capture moves them. Most merchants authorize at swipe and capture later (hours to days).

USDC: A U.S. dollar–pegged stablecoin issued by Circle. QairoPay settles eligible flows in USDC.
Aptos: The Layer 1 blockchain QairoPay uses for USDC settlement. Sub-second finality, low fees.
OnRampAdapter: The typed contract every fiat-to-USDC conversion goes through. The Phase 2 implementation is BridgeOnRampAdapter backed by Bridge (by Stripe).
Bridge: The third-party on-ramp service that converts fiat to USDC. Holds the relevant licensing; QairoPay does not directly custody fiat.
Treasury wallet: Where settled USDC lands. QairoPay-managed by default; self-custody by allowlisted Aptos address is available.
Off-ramp: USDC → fiat conversion via a payout. T+1 for U.S. ACH, T+2 international.
Travel Rule: FinCEN rule requiring originator/beneficiary information to be transmitted with transfers above a threshold. QairoPay handles this transparently for on-chain payouts.

Event: A change of state in the platform, delivered as JSON to your registered endpoint. Identified by a dotted-namespace type.
Envelope: The outer JSON shape of an event: id, type, created, tenant_id, live_mode, api_version, data, previous_attributes.
Signature header: QairoPay-Signature: t=<timestamp>,v1=<hmac>. Verify before trusting the payload.
At-least-once delivery: The same event may be delivered more than once if your endpoint is slow or errors. Dedupe on id.
Backoff schedule: The 30 s → 2 min → 10 min → … → 96 h cadence used to retry failed deliveries.

KYB / KYC: Know Your Business (the tenant) / Know Your Customer (the cardholder). KYB at onboarding, KYC at first card issuance.
BSA / AML: Bank Secrecy Act and Anti-Money-Laundering — the regulatory framework MSBs operate under in the U.S.
OFAC SDN: The U.S. Treasury Office of Foreign Assets Control’s Specially Designated Nationals list. Counterparties on it are blocked.
FinCEN MSB: Federal Money Services Business registration. QairoPay holds one. State MTLs (Money Transmitter Licenses) are layered on top where required.
PCI DSS 4.0: Payment Card Industry Data Security Standard. QairoPay holds Service Provider Level 1 attestation.
SOC 2 Type II / ISO 27001: Independent third-party assurance reports covering security controls. Available under NDA.