> ## Documentation Index > Fetch the complete documentation index at: https://developer.utgl.io/llms.txt > Use this file to discover all available pages before exploring further. # Create Card Account > Create a card account ## OpenAPI ````yaml POST /cardaccounts openapi: 3.1.0 info: title: API Reference version: '1.0' servers: - url: https://access.utgl.io/v1 - url: https://sandbox.access.utgl.io/v1 security: - Basic: [] - Bearer: [] tags: - name: Accounts - name: Transactions - name: Card Accounts - name: Card Products - name: Cards - name: Digital Custody - name: Fee - name: Payout paths: /cardaccounts: post: tags: - Card Accounts summary: Create Card Account description: | Create a card account operationId: createCardAccount requestBody: required: true content: application/json: schema: type: object title: Create Card Account Request required: - name - identityType - accountType - phoneNumber - currency properties: name: type: string description: > Name of card account, this is a human-friendly non unique name for a card account and can be changed later. The card account name is used to identify the card account in reports and in the user interface phoneNumber: type: string example: '+85255551234' description: |- Phone number of card holder This phone number should be pre verified by the partner. xid: $ref: '#/components/schemas/Xid' xmetadata: $ref: '#/components/schemas/Xmetadata' identityType: type: string description: > Type of identity of card holder. Currently only individual is supported. enum: - individual - corporate individual: $ref: '#/components/schemas/CardholderInfo' accountType: type: string enum: - asset-link - prepaid - fixed-limit description: >- The accountType field specifies the type of card account to create. This field is used to distinguish between two types of card accounts: asset-link and prepaid. An `asset-link` card account is backed by combined asset value from a an associated account, which determines the available credit limit of the card account. Repayment on this type of account is settled through the backing account automatically through asset repayments. A `prepaid` card account, on the other hand, is pre-funded directly by a top-up action. This operates as a prepaid or pre-funded card model. A `fixed-limit` card account has a predetermined credit limit that remains unchanged and is not affected by the value of any associated assets. Repayments on this type of account are settled through alternative methods rather than asset repayments. Please note that the accountType field cannot be changed after the card account has been created. currency: type: string minLength: 3 maxLength: 3 description: > Currency of card account. Must be a valid ISO 4217 currency code. Please consult your solution manager to ensure the correct account currency for your offered card products enum: - HKD - USD assetLink: type: object description: > Asset link configuration of card account, applicable only when accountType is asset-link If assetLink is not provided, an account will be created and linked to this card account for both asset backing and repayment. properties: accountId: type: string format: uuid description: >- account to bind to, serves as source for asset backing and repayment creditAccount: type: array description: > This is array of accountIds where the fixed-limit credit come from, the total limit of all the card accounts (under the same credit account) add up cannot exceed the credit account asset balance. When accountType is set to fixed-limit, this additional parameter needs to be passed in. example: - 90dde354-826a-4a0a-b1cb-7f2fc361ad5b items: type: string format: uuid limit: type: number example: '10000' description: > This is the predetermined credit limit for fixed-limit card account. When accountType is set to fixed-limit, this additional parameter needs to be passed in. settlementAccount: type: string format: uuid description: > This is the settlement account for fixed-limit card account. When accountType is set to fixed-limit, this additional parameter needs to be passed in. example: de22c824-b8bd-4825-8db5-e5bdd2371dfb responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CardAccount' components: schemas: Xid: type: string description: >- External identifier, unique across all resources created under this account. Xmetadata: type: object description: External metadata example: key1: value1 key2: - value2.1 - value2.2 additionalProperties: true oneOf: - type: string - type: array items: type: string CardholderInfo: type: object description: > Individual card holder identity information. This is required when account type is individual. required: - firstName - lastName - email - dateOfBirth - annualIncome - document - address - occupation - position properties: dateOfBirth: type: string pattern: \d{4}-\d{2}-\d{2} example: '1985-07-20' description: Date of birth (YYYY-MM-DD) firstName: type: string example: John Anthony description: First name of cardholder lastName: type: string example: CHAN description: Last name / Surname of cardholder firstNameLocal: type: string example: John Anthony description: First name of cardholder on ID lastNameLocal: type: string example: CHAN description: Last name / Surname of cardholder on ID email: type: string example: john.doe@example.com description: Email address of cardholder mobile: type: string example: '+85255551234' description: |- Phone number of card holder This phone number should be pre verified by the partner. annualIncome: type: string example: '100000' description: Annual income of card holder in USD occupation: type: string example: accountant description: >- Occupation of card holder. Retrieve a list of valid occupations from /v1/occupations endpoint. Required and validated against the list of valid occupations. position: type: string example: senior management description: >- Position of card holder. Retrieve a list of valid positions from /v1/positions endpoint. Required and validated against the list of valid positions. document: type: object description: | Government Issued Identification Document Information required: - type - front - number - country properties: type: type: string description: > The following types are accepted for ID documents. - Permanent HKID - Valid Passport - China National ID - Exit-Entry Permit for Travelling to and from Hong Kong and Macao (EEP) - Japanese National ID - Japanese Driving License - Malaysian National ID enum: - passport - drivers-license - national-id front: description: > The front of a document file encoded in data URI base64 encoded format The following mime types are accepted for ID documents - PDF documents: application/pdf - JPEG image files: image/jpeg - PNG image files: image/png - GIF image files: image/gif type: string example: >- data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDQo8P3hwYW5lbCBiYXNlPSIwIiBuYW1lPSJMYXllciAxIiBjb2xvcj0iIzAwMDAwMCI+CjwvYnVmZmVyPgo8L3BhcmVudD4KPC9 back: description: > The back of a document file encoded in data URI base64 encoded format The following mime types are accepted for ID documents - PDF documents: application/pdf - JPEG image files: image/jpeg - PNG image files: image/png - GIF image files: image/gif example: >- data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDQo8P3hwYW5lbCBiYXNlPSIwIiBuYW1lPSJMYXllciAxIiBjb2xvcj0iIzAwMDAwMCI+CjwvYnVmZmVyPgo8L3BhcmVudD4KPC9 type: string number: type: string description: Identification document number. example: A12345678 country: type: string format: ISO3166-1 alpha-2 example: HK description: > Issuing country of identification document in ISO3166-1 alpha-2 format The following countries/regions are not accepted - Afghanistan - Albania - Belarus - Bosnia and Herzegovina - Central African Republic - Crimea - Democratic Republic of the Congo (also Zaire) - Ethiopia - Guinea Bissau - Haiti - Iran - Iraq - Kosovo - Libya - Mali - Montenegro - Myanmar - Nicaragua - North Korea (DPRK) - North Macedonia - Somalia - South Sudan - Sudan and Darfur - Syria - Venezuela - Yemen expiryDate: type: string pattern: \d{4}-\d{2}-\d{2} example: '2025-12-31' description: Expiry date of identification document (YYYY-MM-DD) address: type: string minLength: 1 maxLength: 500 example: 123 Main Street, Anytown, USA description: Address of the card holder. gender: type: string enum: - MALE - FEMALE example: MALE description: | Gender of cardholder. Required from February 1, 2026. Optional until then. nationality: type: string minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ example: HK description: > Nationality of cardholder in ISO 3166-1 alpha-2 format (e.g., HK, US, CN). Required from February 1, 2026. Optional until then. If nationality is not HK, at least one supporting document is required. supportingDocuments: type: array description: | Supporting documents required for non-Hong Kong citizens. Required if nationality is provided and is not HK. Each document must be one of the accepted document types. items: $ref: '#/components/schemas/SupportingDocument' CardAccount: type: object title: Card Account required: - balance - available - limit - currency - outstanding - disputeAmount - accountType - identityType properties: id: $ref: '#/components/schemas/Id' xid: $ref: '#/components/schemas/Xid' xmetadata: $ref: '#/components/schemas/Xmetadata' name: type: string description: Name of card account example: JOHN CHAN accountNumber: type: string description: Account number of card account example: 002-010-1234567-0001 balance: type: number description: >- The current real-time balance of the card account in the account currency. All transactions in the account are added up to calculate this balance. Purchases and cash withdrawals increase it, while payments and credits decrease it. For prepaid accounts, the balance will always be negative to indicate a debit balance. example: 10000.25 balanceUsdEquivalent: type: number description: The equivalent balance of the card account in USD. example: 10000.25 balanceHkdEquivalent: type: number description: The equivalent balance of the card account in HKD. example: 10000.25 outstanding: type: number description: >- The outstanding balance in the card account currency that needs to be repaid. appliable to asset-link mode only. example: 7500.5 disputeAmount: type: number description: >- The card account amount currently under dispute in the card account currency. Returns 0 when there is no disputed amount. example: 250 available: type: number description: >- The available spendable amount on the card account. It is calculated by subtracting the balance from the assigned credit limit. This value represents the total available spendable limit in the account and applies to all account types. A positive value indicates that the card account has available spendable limit. For pre-paid mode accounts, this is the only value that should be used to determine the account's current available balance. example: 825.3 limit: type: number description: > In Asset-link mode, this is the credit limit assigned to the card account. For prepaid accounts, the limit is always zero. example: 10000.25 currency: type: string description: Currency of the card account. example: HKD accountType: type: string enum: - asset-link - prepaid - fixed-limit assetLink: type: object description: Asset link configuration properties: accountId: type: string description: >- Account ID of the asset account (appliable to: accountType=asset-link only) phoneNumber: type: string example: '+85212345678' description: > Contact phone number of card holder, also used to receive 3DS one time passcodes. Phone number of card holder, also used to receive 3DS one time passcodes. Partner must ensure that this phone number has been verified. identityType: type: string description: >- The type of identity associated with the card holder. Must be either "individual" or "corporate". enum: - individual - corporate walletId: type: string example: 0ebd3c68-af60-4a6e-aaa9-040d8e64aa8e description: The walletId is one of the Waillets bound to a card account. status: type: string example: active description: The status of card account. enum: - active - frozen settlementAccountId: type: string format: uuid description: Settlement account id for the fixed limit card account example: abcb107d-d98d-49ee-8456-73fa693dbb55 settlementAccountName: type: string description: Settlement account name for the fixed limit card account example: JOHN CHAN settlementAccountNumber: type: string description: Settlement account number for the fixed limit card account example: 002-010-1234567-0001 SupportingDocument: type: object description: | Supporting document for non-Hong Kong citizens. Required if nationality is not HK. required: - documentType - file properties: documentType: type: string enum: - IMMIGRATION_ENDORSEMENT - WORK_VISA - EMPLOYMENT_CONTRACT - SALARY_PAYSLIP - TENANCY_AGREEMENT - ADDRESS_PROOF - BANK_STATEMENT - TRAVEL_PERMIT_FRONT - TRAVEL_PERMIT_BACK - PROOF_OF_VISIT description: > Type of supporting document. Accepted document types: - IMMIGRATION_ENDORSEMENT: Hong Kong Immigration Endorsement / Landing Slip - WORK_VISA: Valid Hong Kong Work Visa - EMPLOYMENT_CONTRACT: Employment Contract from a Hong Kong company - SALARY_PAYSLIP: Salary Payslip from a Hong Kong company issued within the last 3 months - TENANCY_AGREEMENT: Hong Kong Tenancy / Rental Agreement - ADDRESS_PROOF: Hong Kong Address Proof issued within the last 3 months (e.g., an utility or telecommunication bill) - BANK_STATEMENT: Hong Kong Bank Statement issued within the last 3 months - TRAVEL_PERMIT_FRONT: Front side of the Exit-Entry Permit for Travelling to and from Hong Kong and Macao (EEP / 回鄉證). Must be submitted together with TRAVEL_PERMIT_BACK. - TRAVEL_PERMIT_BACK: Back side of the Exit-Entry Permit for Travelling to and from Hong Kong and Macao (EEP / 回鄉證). Must be submitted together with TRAVEL_PERMIT_FRONT. - PROOF_OF_VISIT: Proof of a recent visit or current stay in Hong Kong (e.g., a hotel booking or flight ticket dated within the last 7 days) example: WORK_VISA file: type: string description: | Supporting document file encoded in data URI base64 encoded format. The following mime types are accepted: - PDF documents: application/pdf - JPEG image files: image/jpeg - PNG image files: image/png - GIF image files: image/gif example: >- data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDQo8P3hwYW5lbCBiYXNlPSIwIiBuYW1lPSJMYXllciAxIiBjb2xvcj0iIzAwMDAwMCI+CjwvYnVmZmVyPgo8L3BhcmVudD4KPC9 Id: type: string format: uuid description: ID of resource securitySchemes: Basic: type: http scheme: basic Bearer: type: http scheme: bearer bearerFormat: JWT ````