Program Architecture

The Axys hierarchy

📘

This page is the map for the entire Axys Cards documentation set. The hierarchy, terminology, and ID scoping defined here are referenced from every Concept, Guide, and Recipe that follows — if you read nothing else before integrating, read this.

Axys operates as a single, shared infrastructure layer — the Axys Platform — on top of which many independent Tenants each operate one or more card Programs. Every Cardholder, Card, Account, and Wallet exists within the scope of exactly one Program, and every Program exists within the scope of exactly one Tenant.

flowchart TD
    PLAT["Axys Platform"]
    TEN["Tenant<br/>(licensed entity — certificate field O)"]
    PROGA["Program A<br/>(certificate field OU)"]
    PROGB["Program B<br/>(white-label / co-brand)"]
    CH["Cardholder"]
    CHACC["Cardholder Account<br/>(internal ledger)"]
    WAL["Wallet<br/>(fiat sub-ledger)"]
    CARD["Card — virtual or physical"]
    CACC["Card Account<br/>ledgerBalance / availableBalance"]
    DA["Deposit Addresses<br/>(80+ chains)"]
    DESIGNS["Card Designs<br/>(slots 0–5)"]
    TXN["Transactions & Fees"]
    OTP["3-DS OTP Subscription"]

    PLAT --> TEN
    TEN -->|creates and manages| PROGA
    TEN -->|creates and manages| PROGB
    PROGA --> CH
    PROGA --> DESIGNS
    CH --> CHACC
    CH --> CARD
    CH -.->|may use| WAL
    CARD --> CACC
    CARD --> DA
    CACC --> TXN
    CARD --> OTP
    WAL -.->|transfer| CACC
    DESIGNS -.->|selects| CARD

The sections below define each layer in turn, working down the hierarchy. Solid arrows in the diagram represent ownership/containment; dashed arrows represent optional or transactional relationships.

---

The Axys Platform

The Platform is the underlying infrastructure that Axys operates: the issuer-processor technology, the network connectivity to card schemes, the digital-asset custody and settlement infrastructure, and the compliance tooling. It isn't something you address directly via the API — it's the context in which every Tenant, Program, and Cardholder exists.

Axys is positioned as a turnkey aggregation, automation, and orchestration layer for card issuing — unifying the issuer, program manager, and issuer processor roles that a traditional card program would otherwise need to assemble separately, with built-in network, payment, and digital asset rails. See Stakeholders in a Card Program for how these industry roles map onto the Tenant/Program/Axys hierarchy described on this page.

---

Tenants

A Tenant is a licensed or regulated entity (for example, the e-money institution or bank that holds the platform relationship with Axys) that has been onboarded onto the Axys Platform. A Tenant:

• holds its own mTLS client certificate, whose O (Organization) field identifies the Tenant's legal entity name — see Mutual TLS, Certificates & CSRs
• holds its own tenant-level API credentials, used for Account Management operations such as creating and configuring Programs, managing API users, and configuring network security
• can create and operate one or more Programs — its own branded program, white-label programs on behalf of clients, or co-branded programs

🚧

A Tenant cannot directly create cardholders, issue cards, manage wallets, or perform any other cardholder-facing operation. Every such operation exists only within the scope of a Program and its program-level credentials. If you're holding tenant-level credentials and trying to call an endpoint like POST /cardholders, you're at the wrong layer — see API Users, Tenants & Programs.

A single Tenant operating multiple Programs is the normal "white-label hotel" pattern: one regulated entity, several distinct card programs (each potentially with its own brand, currency, card designs, and even its own end-customer base), all running on the same underlying Axys infrastructure.

In industry terms, the Tenant is considered the issuer — the regulated party whose Programs issue cards to cardholders. Axys itself acts as the issuer processor, aggregating and orchestrating the underlying issuing, processing, and program management roles on the Tenant's behalf. See Stakeholders in a Card Program for the full industry-role mapping, including how Issuer Banks and network membership fit in.

---

Programs

A Program is a specific, configured card program operated under a Tenant. Each Program has its own:

• base currency (one of USD, CAD, GBP, or EUR — see the currency enum in Status & Enum Glossary)
• transactionLimit ceiling, which is inherited by every Cardholder and Card in the Program unless overridden at a lower level (and can never be overridden upward)
• set of Card Designs (six slots — see Card Programs & Card Designs)
• compliance configuration (standard Didit-hosted KYC, or SumSub token-based KYC via sumsubEnabled)

A Program's mTLS client certificate carries one or more OU (Organizational Unit) entries identifying the Program's trading or brand name(s). Critically, the documented Axys API (everything in the Reference section) operates entirely at the Program level — programId is never passed as a parameter because it's implicit in the program-level API key used to authenticate the request. Every cardholder, card, wallet, transaction, and fee you can see through the API belongs to exactly one Program: the one whose credentials you're using.

Each Program is designed and operated by a program manager — typically the Tenant itself, but in white-label or co-brand arrangements, potentially a third party operating in conjunction with the Tenant. See Stakeholders in a Card Program.

---

Cardholders

A Cardholder is always a natural person. KYC, the compliance lifecycle, and ultimate liability for the Cards issued under an Account all attach to an individual — never directly to a corporate entity.

Programs are free to serve corporate clients, but they do so through a Cardholder: the natural person who represents the business and is responsible for the Cards issued under their Account — typically a director, manager, partner, shareholder, entrepreneur, or sole trader. A corporate entity itself never appears as a Cardholder record; see "Corporate use cases" below for how Wallets fit into this pattern.

Cardholders move through a compliance-driven lifecycle (Draft → Under Review → Approved, with decline and error states) — see Cardholders & the Compliance Lifecycle for the full status model and onboarding flow.

On creation (POST /cardholders), Axys automatically provisions the cardholder's Account — see below.

---

Accounts, Wallets & Deposit Addresses

These three terms sound similar but describe genuinely different things, and the distinction matters for how money moves through the platform. This page gives the short version; for the full treatment — including how balances move between them — see Accounts, Wallets & Deposit Addresses.

📘

If you only remember one rule from this table: "Wallet" always means fiat, and a blockchain address on a card is a Deposit Address, never a "wallet." The two are unrelated despite the similar names.

Corporate use cases

Because a Cardholder is always a natural person, a Program serving a corporate client typically combines a Wallet (representing the corporate entity's pooled funds) with one or more Cardholders (the directors, employees, or other individuals authorized to spend on the company's behalf). A typical pattern:

1. The Program creates a Wallet for the corporate client and funds it (via bank transfer or digital asset deposit).
2. Each authorized individual is onboarded as their own Cardholder, with their own KYC and their own Card(s) — e.g. a "director's expense card."
3. Funds are transferred from the corporate Wallet to each Cardholder's Card Account as needed (POST /wallets/transfer).

The corporate entity itself is never a Cardholder and is never directly KYC'd by Axys — liability for each Card sits with the natural person who holds it.

---

Cards

A Card — virtual or physical — is issued to a Cardholder and has:

• its own Card Account (internal ledger — ledgerBalance and availableBalance)
• its own set of auto-generated Deposit Addresses for digital-asset funding
• a cardType (0–5) selecting which of the Program's six Card Design slots applies
• an optional card-level transactionLimit, which inherits the Cardholder's limit (itself capped by the Program's limit) if not set

See Cards: Virtual vs. Physical for the full lifecycle, status model, and the distinction between a card's approval status and its operational status.

---

Card Designs

Each Program has six Card Design slots (numbered 0–5). Slot 0 must be populated with the Program's default design; slots 1–5 are optional. Each design carries its own approval status (Pending, Approved, or Rejected), and cardType at issuance selects which design slot a physical card uses. See Card Programs & Card Designs.

---

Transactions, Fees & 3-D Secure

Every Card Account accumulates Transactions and Fees as money moves in and out — see Transactions & Fees for the full model, including how Axys's settlement and fee structure differs from traditional card-program economics. Cards can also subscribe to 3-D Secure OTP delivery for card-not-present authentication — see 3-D Secure.

---

Credential scoping

Two distinct credential scopes exist, corresponding to the Tenant and Program layers:

Both scopes require a valid mTLS client certificate and an X-API-Key header on every request — see Authentication & Environments.

---

ID reference

---

How this maps to your mTLS certificate

If you've been through onboarding, you already hold at least one client certificate. The certificate's Subject fields tell you which layer it operates at:

• O (Organization) — your Tenant's legal entity name
• OU (Organizational Unit) — one or more trading/brand names, corresponding to your Program(s)
• CN/SAN — the explicit domain(s)/IP(s) you'll call the API from (no wildcards)

For the full certificate issuance and rotation process, see Mutual TLS, Certificates & CSRs.

---

Multi-Program and white-label scenarios

Because every documented endpoint is scoped implicitly to a Program via its API key, running multiple Programs under one Tenant is simply a matter of holding multiple sets of program-level credentials — one per Program. Common patterns:

• Single brand, single Program — the simplest case: one Tenant, one Program, one set of credentials.
• Single Tenant, multiple owned Programs — for example, separate consumer and corporate card programs, each with its own currency, limits, and card designs.
• White-label / co-brand — a Tenant operates a Program on behalf of (or jointly branded with) a separate client business. The client's brand appears in the Program's OU and Card Designs, but the Tenant remains the regulated entity and retains Account Management control over that Program.

In every case, cardholders, cards, wallets, transactions, and fees from one Program are completely invisible to another Program's credentials — there is no cross-Program query capability in the documented API.

---

The full data model

The diagram below shows every object referenced in this documentation, including Tenant-level objects that are part of Axys's Account Management layer. For a field-by-field reference of each object, see Data Model & Object Reference.

erDiagram
    TENANT ||--o{ PROGRAM : "creates and manages"
    TENANT ||--o{ API_USER : "manages"
    PROGRAM ||--o{ CARDHOLDER : "onboards"
    PROGRAM ||--o{ CARD_DESIGN : "configures (slots 0-5)"
    PROGRAM ||--o{ WALLET : "provisions"
    CARDHOLDER ||--|| CARDHOLDER_ACCOUNT : "has"
    CARDHOLDER ||--o{ CARD : "holds"
    CARD ||--|| CARD_ACCOUNT : "has"
    CARD ||--o{ DEPOSIT_ADDRESS : "generates per chain"
    CARD_ACCOUNT ||--o{ TRANSACTION : "records"
    CARD_ACCOUNT ||--o{ FEE : "incurs"
    CARD ||--o{ OTP_LISTENER : "may have"
    CARD_DESIGN ||--o{ CARD : "selected via cardType"
    WALLET ||--o{ WALLET_TRANSACTION : "records"
    WALLET }o--o{ CARD : "transfers to or from"

    TENANT {
        string legalEntityName "certificate field O"
        string tradingNames "certificate field OU values"
    }
    PROGRAM {
        int currency "0 USD, 1 CAD, 2 GBP, 3 EUR"
        int transactionLimit "ceiling for cardholders and cards"
    }
    CARDHOLDER {
        int cardholderId
        int status "0-7 compliance lifecycle"
        int transactionLimit
        int sumsubEnabled "0 or 1"
    }
    CARDHOLDER_ACCOUNT {
        string note "internal ledger, not a REST resource"
    }
    CARD {
        int cardId
        string type "physical or virtual"
        int cardStatus "0-2 approval status"
        int issuerCardStatus "0-4 lifecycle status"
        int transactionLimit
        int cardType "0-5, selects design slot"
    }
    CARD_ACCOUNT {
        int ledgerBalance
        int availableBalance
        int currency "0 USD, 1 CAD, 2 GBP, 3 EUR"
    }
    DEPOSIT_ADDRESS {
        string chain
        string address
    }
    WALLET {
        int walletId
        string name
        int walletCurrencyId
        boolean isActive
        boolean isDeleted
    }
    CARD_DESIGN {
        int slot "0-5, slot 0 mandatory"
        int status "0 pending, 1 approved, 2 rejected"
    }
    TRANSACTION {
        string transId
        string amount
        int transType
        int transStatus
    }
    FEE {
        string feeId
        int feeType
        int feeStatus
    }
    API_USER {
        string id "Account Management"
    }

---

What's next

• New to Axys? Start with Welcome to Axys and Authentication & Environments.
• Setting up a new Tenant or Program? See Onboarding Overview & Checklist.
• Want the full picture on balances and funding? See Accounts, Wallets & Deposit Addresses and Funding & Deposits.
• Ready to onboard your first cardholder? See Cardholders & the Compliance Lifecycle.