Card Programs & Designs

A Card Program is the top-level configuration unit for everything that governs how cards behave within your Tenant: the base currency, transaction-limit ceiling, supported card designs, 3-D Secure enablement, fee structure, and blockchain deposit address types. Card Designs are the visual and physical specifications for cards issued under a Program, managed across up to six design slots.

Both are configured via Account Management, which is available exclusively to Tenants holding production API keys — it is not accessible in the staging environment, and the underlying endpoints are not publicly exposed or documented in the OpenAPI reference. Full Account Management guides are provided separately to production Tenants. This page documents the data model, lifecycle, and operational concepts that underpin Program and Card Design configuration.

📘

Account Management is not publicly exposed. The endpoints that create and configure Programs and Card Designs are available only to Tenants with production API keys, through a separate Account Management interface. They are deliberately not included in the public OpenAPI reference. Full operational guides for Account Management are made available to Tenants in the production environment. If you are a Tenant and do not yet have access, contact your Axys account team.

Card Programs

What a Program configures

A Program is the authoritative source of several properties inherited by everything beneath it in the hierarchy:

Program lifecycle

stateDiagram-v2
    [*] --> Draft: Tenant creates Program (Account Management)
    Draft --> UnderReview: Program submitted for Axys configuration
    UnderReview --> Active: Program approved and configured
    Active --> Suspended: Administrative action
    Suspended --> Active: Issue resolved
    Active --> [*]: Program decommissioned

📘

Once a Program is Active, most of its configuration properties (fee structure, SMS sender, deposit address types) can be updated through Account Management. However, base currency cannot be changed after a Program is created — if you need a different currency, a new Program must be created.

Credential scoping

Each Program operates with its own mTLS client certificate and program-level API key — entirely independent of the Tenant's credentials and of other Programs under the same Tenant. See Program Architecture and mTLS Certificates & CSR.

Card Designs

The six-slot model

Each Program has six Card Design slots, numbered 0 through 5. The slot number maps directly to the cardType field on POST /cards/assign/{cardholderId} (physical card issuance):

A cardType value of 0 in any issuance call always resolves to the Program's default design, even if you forget to pass the field — cardType defaults to 0 in the OpenAPI schema.

Card Design approval lifecycle

Each design slot has its own approval status, independently of the others:

stateDiagram-v2
    [*] --> Pending: Design submitted via Account Management
    Pending --> Approved: Axys approves design
    Pending --> Rejected: Axys rejects design
    Rejected --> Pending: Revised design resubmitted
    Approved --> Pending: Design update submitted (re-review required)
    Approved --> [*]: Slot retired

🚧

A Program cannot issue physical cards until slot 0 is approved. Attempting to issue a physical card (POST /cards/assign/{cardholderId}) before the Program's default design has designStatus = 1 will fail. Virtual cards are not affected by card design status — they carry no physical design.

Design submission requirements

Card design submissions are handled via Account Management. A design submission typically includes:

Card network brand standards govern what must and must not appear on a card face — the specific requirements are published by Visa and Mastercard respectively, and Axys will validate submissions against these during the approval process.

Using cardType at issuance

Only the cardType field links a physical card to a design slot — virtual cards have no design slot and don't use this field. At issuance:

POST /cards/assign/{cardholderId}
{
  "nameOnCard": "J REYES",
  "cardType": 2,
  "alias": "Premium Black Card",
  "transactionLimit": 500000
}

cardType: 2 selects design slot 2. If slot 2's designStatus is not 1 (Approved) at the time of issuance, the request will fail. If cardType is omitted, it defaults to 0 (the Program's default design).

Relationship between Programs and designs

erDiagram
    PROGRAM ||--o{ CARD_DESIGN_SLOT : "has 6 slots"
    CARD_DESIGN_SLOT ||--o{ CARD : "selected via cardType"

    PROGRAM {
        int currency "0 USD 1 CAD 2 GBP 3 EUR"
        int transactionLimit "ceiling"
        boolean threeDSEnabled
    }
    CARD_DESIGN_SLOT {
        int slot "0-5, slot 0 mandatory"
        int designStatus "0 pending 1 approved 2 rejected"
        string name
    }
    CARD {
        int cardType "0-5, selects slot"
        string type "physical or virtual"
    }

What's next

• API Users, Tenants & Programs
• Cards: Virtual & Physical
• 3-D Secure
• Funding & Deposits