Data Model & Object Reference

This page provides the full data model: an entity relationship (ER) diagram showing every object and its relationships, followed by a field-level reference table for each object.

Entity relationship diagram

erDiagram
    TENANT ||--o{ PROGRAM : "creates and manages"
    TENANT ||--o{ API_USER : "manages"
    TENANT ||--o{ SUPPORT_TICKET : "raises"
    PROGRAM ||--o{ CARDHOLDER : "onboards"
    PROGRAM ||--o{ CARD_DESIGN_SLOT : "configures (0-5)"
    PROGRAM ||--o{ WALLET : "provisions"
    CARDHOLDER ||--|| CARDHOLDER_ACCOUNT : "has one"
    CARDHOLDER ||--o{ CARD : "holds"
    CARDHOLDER ||--o{ KYC_DOCUMENT : "submits"
    CARD ||--|| CARD_ACCOUNT : "has one"
    CARD ||--o{ DEPOSIT_ADDRESS : "provisioned at issuance"
    CARD ||--o{ OTP_LISTENER : "may have"
    CARD_ACCOUNT ||--o{ TRANSACTION : "records"
    CARD_ACCOUNT ||--o{ FEE : "incurs"
    CARD_DESIGN_SLOT ||--o{ CARD : "selected via cardType"
    WALLET ||--o{ WALLET_TRANSACTION : "records"
    WALLET }o--o{ CARD_ACCOUNT : "transfers to"
 
    TENANT {
        string legalEntityName "cert O field"
        string tradingName "cert OU field"
    }
    PROGRAM {
        int currency "0 USD 1 CAD 2 GBP 3 EUR"
        int transactionLimit "ceiling - inherited"
        boolean threeDSEnabled
    }
    CARDHOLDER {
        int cardholderId PK
        int status "0-7"
        int transactionLimit
        int sumsubEnabled "0 or 1"
        string emailAdr
        string applicationLink
        string dateCreated
    }
    CARD {
        int cardId PK
        int cardholderId FK
        string cardVariant "physical or virtual"
        int cardStatus "0-2"
        int issuerCardStatus "0-4"
        int transactionLimit
        int cardType "0-5"
        string alias
        string maskedCardNumber
    }
    WALLET {
        int walletId PK
        string name
        int walletCurrencyId
        boolean isActive
        boolean isDeleted
        string dateCreated
    }
    CARD_ACCOUNT {
        int ledgerBalance
        int availableBalance
        int currency
    }
    DEPOSIT_ADDRESS {
        string chain
        string address
    }
    TRANSACTION {
        string transId PK
        string authRefNum
        string amount
        int transStatus "1-5"
        int transType
        string merchantName
        string merchantCurrency
        string merchantAmount
        string dateCreated
        string dateSettled
    }
    FEE {
        string feeId PK
        string authRefNum
        string amount
        int transStatus "1-5"
        int feeType
        string dateCreated
        string dateSettled
    }
    OTP_LISTENER {
        string token PK
        int expiresAt "currently null"
    }
    CARD_DESIGN_SLOT {
        int slot "0-5"
        int status "0-2"
    }
    API_USER {
        string id
    }
    SUPPORT_TICKET {
        string ticketId PK
        string status
        int priority "1-5"
        string programId
        int cardholderId
        int cardId
    }

📘
Wallet-to-wallet transfers (POST /wallets/transfer with destinationType = 0) are not shown as a self-referential relationship in the diagram above. The WALLET }o--o{ CARD_ACCOUNT line represents wallet-to-card transfers; the same transfer endpoint also supports wallet-to-wallet, with destinationId referencing another wallet. See Transfer Internal Fiat Funds.

Object field reference

Cardholder

Created via POST /cardholders. Retrieved via GET /cardholders/{cardholderId} (CardholderView).

Identity & compliance (locked once status = 3 or 1)

Field	Type	Constraints	Notes
`firstName`	string	2–50 chars	Legal first name as on government-issued ID
`midName`	string	max 50 chars	Optional legal middle name
`lastName`	string	2–50 chars	Legal last name as on government-issued ID
`gender`	integer enum	`0`/`1`/`2`	See Statuses & Enums
`nationality`	string	2–50 chars	As on government-issued ID
`placeOfBirth`	string	3 chars	ISO 3166-1 Alpha-3 country code (e.g. `USA`)
`dob`	string	`YYYY-MM-DD`	Legal date of birth as on government-issued ID
`adrLine1`	string	4–50 chars	First line of residential address as on proof of address
`adrLine2`	string	max 50 chars	Optional second address line
`city`	string	2–50 chars	City as on proof of address
`state`	string	2–50 chars	State/equivalent. US: 2-letter USPS abbrev. Non-applicable: `XX`
`country`	string	2 chars, Alpha-2	ISO 3166-1 Alpha-2 (e.g. `US`)
`zipCode`	string	5–12 chars	ZIP/postal code. Non-applicable: `00000`
`sumsubEnabled`	integer enum	`0`/`1`	KYC provider selection — locked once Under Review

Contact (always editable)

Field	Type	Constraints	Notes
`emailAdr`	string	6–50 chars
`callingCode`	string	3 digits	ITU dialing code, zero-padded to 3 digits (e.g. `001`)
`cellNum`	string	10–20 digits	Mobile number; dialing code in `callingCode`
`countryCallingCode`	string	2 chars, Alpha-2	Alpha-2 country code associated with `phoneNum` (not a dialing code)
`phoneNum`	string	10–20 digits	Landline; dialing code in `countryCallingCode`

Card personalization & optional

Field	Type	Constraints	Notes
`cardHolderFirstName`	string	max 50 chars	Preferred name on cards — defaults to `firstName`
`cardHolderLastName`	string	max 50 chars	Preferred name on cards — defaults to `lastName`
`employeeID`	string	—	Optional corporate identifier
`transactionLimit`	integer	decimal-implied integer	Per-transaction spending ceiling — capped by Program

System-generated (read-only)

Field	Type	Notes
`cardholderId`	integer	Primary key, auto-generated
`status`	integer enum	0–7 — see Statuses & Enums
`applicationLink`	string	Didit KYC URL — returned on `CardholderView` after submission
`dateCreated`	string	Unix timestamp (seconds)
`kycDocs`	array	See KYC Document object below

KYC document (`kycDocsView`)

Returned as array kycDocs on CardholderView.

Field	Type	Notes
`kycDocID`	integer	Document record ID
`status`	integer	Document-level review status
`docType`	integer	Document type
`lang`	string	Document language
`number`	string	Document number
`issueBy`	string	Issuing authority
`issuerDate`	string	Date of issue
`expireDate`	string	Expiry date
`image_FrontExt`	string	File extension of the front-face image
`image_BackExt`	string	File extension of the reverse-face image

Card (`CardViewMasked`)

Retrieved via GET /cards/{cardId}. Also returned as CardListItem in list responses.

Field	Type	Notes
`cardId`	integer	Primary key
`cardholderId`	integer	Owner cardholder
`type`	string	`physical` or `virtual`
`cardStatus`	integer enum	0–2 — approval status (see Statuses & Enums)
`issuerCardStatus`	integer enum	0–4 — operational status (see Statuses & Enums)
`maskCardNumber`	string	PAN masked to last 4 digits (`****1234`)
`transactionLimit`	integer	decimal-implied integer card-level spending ceiling
`cardType`	integer	0–5 — card design slot selected at issuance
`alias`	string	Display alias
`cryptoAddresses`	array	`[{ chain, address }]` — Deposit Addresses generated at issuance
`contact`	object	Card-level contact details (defaults to cardholder's)
`createdDatetime`	string	Timestamp of issuance

Card sensitive details GET /cards/{cardId}/details

❗️
The full unmasked PAN and CVV/CVC are only returned once the Cardholder is compliance-approved (status = 1). Never log a Card's full PAN or CVV/CVC. See Issue a Virtual Card.

Field	Type	Notes
`cardId`	integer
`cardholderId`	integer
`cardNumber`	string	Full unmasked PAN
`expMonth`	string	Expiry month (`MM`)
`expYear`	string	Expiry year
`cvv`	string	CVV/CVC
`cryptoAddresses`	array	Deposit Addresses

Card balance GET /cards/{cardId}/balance

Field	Type	Notes
`ledgerBalance`	integer	decimal-implied integer — includes pending amounts
`availableBalance`	integer	decimal-implied integer — fully cleared and spendable
`currency`	integer enum	0–3 — see Statuses & Enums

Wallet (`WalletView`)

Field	Type	Notes
`walletId`	integer	Primary key
`name`	string	Display name
`walletCurrencyId`	integer enum	0–3 — see Statuses & Enums
`isActive`	boolean	Whether the wallet is active
`isDeleted`	boolean	Whether the wallet has been deleted
`dateCreated`	string	Creation timestamp
`dateLastModified`	string	Last modification timestamp

🚧
WalletView does not include ledgerBalance or availableBalance. Wallet balance must be inferred from transaction history — see Create & Manage Wallets.

Transaction (`TransactionsViewResponse`)

Field	Type	Notes
`cardId`	integer
`transId`	string	Primary key
`authRefNum`	string	Authorization reference — use to correlate with fee records
`amount`	string	Amount in Card's base currency — see Transactions & Fees
`description`	string
`dateCreated`	string
`dateSettled`	string
`transType`	integer	Transaction type — see Statuses & Enums
`transStatus`	integer enum	1–5 — see Statuses & Enums
`merchantName`	string
`merchantCurrency`	string	Currency as presented by Merchant — may equal Card base currency even for foreign transactions
`merchantAmount`	string	Amount in Merchant's currency — see Transactions & Fees

Fee (`FeesViewResponse`)

Same structure as Transaction with feeId instead of transId and feeType instead of transType:

Field	Type	Notes
`cardId`	integer
`feeId`	string	Primary key
`authRefNum`	string	Links to associated transaction — may be absent for standalone fees
`amount`	string	Note: string type, not an integer as elsewhere
`description`	string
`dateCreated`	string
`dateSettled`	string
`feeType`	integer	Fee type
`transStatus`	integer enum	1–5 — same enum as Transaction status
`merchantName`	string
`merchantCurrency`	string
`merchantAmount`	string	Note: string type, not an integer as elsewhere

OTP Listener

Created via POST /otp/listeners. Retrieved via GET /otp/{token}.

Field	Object	Type	Notes
`token`	Create response	string	Opaque OTP subscription identifier — treat as credential
`expiresAt`	Create response	integer	Currently always `null`
`status`	Retrieve response	string enum	`pending`/`received`/`expired`/`consumed`
`code`	Retrieve response	string	OTP code — present only when `status = received`
`receivedAt`	Retrieve response	integer	Unix timestamp when OTP was generated
`expiresAt`	Retrieve response	integer	Enforced expiry — Unix timestamp, different from subscription `expiresAt`

Transfer response

Returned by POST /wallets/transfer.

Field	Type	Notes
`transId`	integer	Transaction ID for this transfer
`transStatus`	integer enum	0–4 — different enum from Transaction/Fee `transStatus` — see Statuses & Enums

Entity relationship diagram

Object field reference

Cardholder

KYC document (kycDocsView)

Card (CardViewMasked)

Wallet (WalletView)

Transaction (TransactionsViewResponse)

Fee (FeesViewResponse)

OTP Listener

Transfer response

KYC document (`kycDocsView`)

Card (`CardViewMasked`)

Wallet (`WalletView`)

Transaction (`TransactionsViewResponse`)

Fee (`FeesViewResponse`)