> ## 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. # Issue Card > Issue a card under the respective card account. This can be either a physical, which is a traditional tangible card made of plastic, or a virtual card, which is a digital version of a physical card that can be used for online transactions or transactions made through a mobile device. When issuing a card, the productId must be specified and determines the card product to issue. The card product determines the card type, card face, card features, benefits, interest rates, capabilties, etc. The list of available productIds is static will be provided by your solution manager based on your pre-determined card product offering(s). The card will be chosen from the available inventory and given out in numerical order according to its card number. If you wish to issue a specific card, you may specify the card number suffix (up to the full card numberA) using the `cardSuffix` field. If the card number is not part of the `productId` or already issued, the request will fail. Multiple cards can be issued under the a single card account. Once the request has been processed: - The card will be created in the system under the respective card account. - The card can then be activated and used for making purchases. ## OpenAPI ````yaml /issuing/api-reference/openapi.yaml post /cards 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: /cards: post: tags: - Cards summary: Issue Card description: >- Issue a card under the respective card account. This can be either a physical, which is a traditional tangible card made of plastic, or a virtual card, which is a digital version of a physical card that can be used for online transactions or transactions made through a mobile device. When issuing a card, the productId must be specified and determines the card product to issue. The card product determines the card type, card face, card features, benefits, interest rates, capabilties, etc. The list of available productIds is static will be provided by your solution manager based on your pre-determined card product offering(s). The card will be chosen from the available inventory and given out in numerical order according to its card number. If you wish to issue a specific card, you may specify the card number suffix (up to the full card numberA) using the `cardSuffix` field. If the card number is not part of the `productId` or already issued, the request will fail. Multiple cards can be issued under the a single card account. Once the request has been processed: - The card will be created in the system under the respective card account. - The card can then be activated and used for making purchases. operationId: issueCard requestBody: required: true content: application/json: schema: type: object required: - cardAccountId - type - productId - embossedName properties: type: type: string enum: - physical - virtual description: >- The `type` field determines the type of card to issue. It can be either a physical card or a virtual card. A physical card is a traditional, tangible card that is made of plastic or other materials and can be used for both online and in-person transactions at retail card terminals. A virtual card is a digital / online only version of a payment card, which can be used for online transactions or for transactions made through a mobile device when binding to wallets or payment apps. cardAccountId: type: string example: c8e2752d-6bd7-4244-a9f6-580f5640eaeb description: >- The `cardAccountId` field specifies the card account under which the card will be issued. This field is used to issue and link the newly issued card to a particular card account, which must have already been created prior to issuing the card. The card account is an account that holds the funds, balances, and transactions that are used to make purchases with the card. Multiple cards issued under the same card account share the same balance and limit. productId: type: string format: uuid description: Product ID of the card product to be issued embossedName: type: string maxLength: 22 example: CHAN TAI MAN description: >- The embossedName field specifies the name that is embossed or printed on a physical card. This is the name that appears on the front of the card. Allowed characters: basic latin letters (A-Z, a-z), hyphens("-"), whitespace(" "), periods("."), and commas(","). Accented letters, apostrophes, and numeric characters are not permitted. Examples of valid names: - "CHAN TAI MAN" - "John Smith" - "Mary-Jane" - "John, Jr." - "Mary A." Examples of invalid names: - "11" (contains numeric characters) - "John123" (contains numeric characters) - "José María" (contains accented letters) - "O'Connor-Smith" (contains apostrophe) - "a" (too short after processing) - "John@Doe" (contains invalid characters) cardSuffix: type: string example: '8888' description: >- Specify a card suffix to issue a specific card. This field can be used to have fine control over card selection during issuing process. The specified card must be available in the inventory and not already issued. cardholderInfo: $ref: '#/components/schemas/CardholderInfo' xid: $ref: '#/components/schemas/Xid' xmetadata: $ref: '#/components/schemas/Xmetadata' responses: '200': description: Card Issue Successful content: application/json: schema: $ref: '#/components/schemas/Card' components: schemas: 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' 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 Card: type: object properties: id: $ref: '#/components/schemas/Id' description: >- Card ID of issued card. All card related endpoints require this ID for operation. cardAccountId: type: string format: uuid description: Card account ID of the card xid: $ref: '#/components/schemas/Xid' xmetadata: $ref: '#/components/schemas/Xmetadata' status: type: string enum: - active - pending-issue - pending-activation - locked - suspended - cancelled embossedName: type: string description: Embossed name on the card network: type: string description: Card network enum: - mastercard product: $ref: '#/components/schemas/CardProduct' type: object description: Card product expiryMonth: type: string description: Card expiry month example: 9 expiryYear: type: string description: Card expiry month example: 2030 last4: type: string description: Last 4 digits of the card number replacedBy: type: string description: Card id of the card that replaced this card cardLimit: type: number description: Card limit dailyAtmLimit: type: number description: Daily ATM limit dailyPurchaseLimit: type: number description: Daily Purchase limit dailyLimit: type: number description: Daily limit singleTransactionLimit: type: number description: Single transaction limit availableLimit: type: number description: >- Available limit chargeable on the card, taking into account all limits. cardPresentLimit: type: number description: Card present limit. cardNotPresentLimit: type: number description: Card not present limit. mobile: type: string description: Card cell phone number cardEmail: type: string format: email description: Email address associated with the card example: john.doe@example.com 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 CardProduct: type: object properties: id: $ref: '#/components/schemas/Id' type: string format: uuid description: Card product ID name: type: string description: Product name imageUrl: type: string description: Card product image URL, an image of card face without any embossing cardType: type: string description: Card Type cardImageDetails: type: object properties: cardOrientation: type: string enum: - LANDSCAPE - PORTRAIT cardWidth: type: string description: Card image width cardHeight: type: string description: Card image height cardNameFontSize: type: string description: Card Name Font Size cardNameFontWeight: type: string description: Card Name Font Weight cardNameLineHeight: type: string description: Card Name Line Height cardNameLetterSpacing: type: string description: Card Name Letter Spacing cardNamePosition: type: string description: Card position cardNameCoordinates: type: array items: type: number description: Coordinates of embossed name on the card image cardNameColor: type: string description: Card Name Color securitySchemes: Basic: type: http scheme: basic Bearer: type: http scheme: bearer bearerFormat: JWT ````