Cardholders & Compliance

Every Cardholder moves through a compliance-driven lifecycle before any card can be issued to them. This page covers the full status model, the two compliance paths (Didit-hosted KYC and SumSub), which fields become locked once review begins, and the documents collected as part of KYC.

📘

Recall from Program Architecture: a Cardholder is always a natural person, even when the Program serves a corporate client.

The status model

Lifecycle

stateDiagram-v2
    [*] --> Draft: POST /cardholders
    Draft --> UnderReview: Submit to compliance
    UnderReview --> Approved: KYC passes
    UnderReview --> ComplianceDecline: KYC fails
    UnderReview --> AdminDecline: Manually declined
    UnderReview --> Error: Processing error
    ComplianceDecline --> UnderReview: Re-submit (regenerate KYC URL)
    Error --> UnderReview: Re-submit
    Approved --> Deleted
    Draft --> Deleted
    ComplianceDecline --> Deleted
    AdminDecline --> Deleted
    Deleted --> [*]

    note right of Draft
        Status 0 (Pending) is a brief
        transitional state that may be
        observed during any of these
        transitions, rather than a
        resting state.
    end note

Only Cardholders with status = 1 (Approved) can have cards issued to them — see Cards: Virtual & Physical and Issue a Virtual Card.

The onboarding sequence

sequenceDiagram
    participant You
    participant Axys
    participant Cardholder

    You->>Axys: POST /cardholders
    Axys->>You: cardholderId, status = 4 (Draft)

    Note over You,Axys: Optional: edit while in Draft

    You->>Axys: PUT /cardholders/{cardholderId}/kyc-submit
    Axys->>You: status = 3 (Under Review)<br/>applicationLink (Didit KYC URL)

    You->>Cardholder: Share applicationLink

    Cardholder->>Axys: Submit photo ID + proof of address<br/>+ liveness check via applicationLink

    Axys->>Axys: Compliance review

    alt Approved
        Axys->>You: status = 1 (Approved)
    else Declined
        Axys->>You: status = 2 (Compliance Decline)
        You->>Axys: POST /cardholders/{cardholderId}/kyc-url/refresh
        Note over You,Cardholder: Cardholder re-attempts via new link
    end

Two compliance paths

Didit (default)

By default (sumsubEnabled = 0), submitting a Cardholder for review (PUT /cardholders/{cardholderId}/kyc-submit) generates an applicationLink — a hosted URL where the Cardholder completes their KYC:

• Government-issued photo ID
• Proof of address
• Liveness verification

If the link expires or the Cardholder needs to retry, regenerate it with POST /cardholders/{cardholderId}/kyc-url/refresh.

SumSub (token-based)

Setting sumsubEnabled = 1 (at creation via POST /cardholders, or via update before review begins) switches the Cardholder to a SumSub-based compliance flow, which requires a SumSub authentication token rather than the Didit applicationLink.

🚧

The SumSub flow's specific endpoints and token exchange sit alongside the sumsubEnabled flag described here. If your Program uses SumSub, confirm the token-exchange process with your Axys integration contact.

KYC documents

As part of the compliance process, Axys tracks the documents submitted by the Cardholder:

This array is returned as kycDocs on GET /cardholders/{cardholderId}.

Field-lock rules

Once a Cardholder enters status = 3 (Under Review) or status = 1 (Approved), a large set of compliance-relevant fields become permanently locked — they cannot be changed via PUT /cardholders/{cardholderId}/update, even after returning to a non-approved state. Double-check these before submitting for review:

🚧

Every locked field above is identity or KYC-document data — the information that must match the Cardholder's government-issued ID and proof of address. Get these right in your initial POST /cardholders call; there's no path to correct a typo in, say, dob or country after submission without creating a new Cardholder record.

Cardholder Account

On creation, Axys automatically provisions the Cardholder's internal Account — see Accounts, Wallets & Deposit Addresses. This is not a separately addressable resource.

Bank account and deposit-address registration

Approved Cardholders can register an external bank account (for bank-rail funding, with OTP verification) as a sub-resource. Digital-asset deposit addresses, by contrast, are generated automatically per-card at issuance and require no registration. Both are covered in full in Funding & Deposits.

What's next

• Onboard a Cardholder End to End
• Cards: Virtual & Physical
• Accounts, Wallets & Deposit Addresses