> ## Documentation Index > Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt > Use this file to discover all available pages before exploring further. # List Cards > Returns a list of issuing card objects. The objects are sorted in descending order by creation date, with the most recently created object appearing first. ## OpenAPI ````yaml /card-issuance/v1.6/issuing.yaml get /v1/issuing/cards openapi: 3.0.2 info: title: Issuing API version: 0.0.1 description: > UQPAY Issuing API allows you to issue virtual cards, manage cardholders, and monitor card transactions. ## What you can do - Create and manage virtual cards (issue, activate, freeze, cancel) - Onboard and verify cardholders with KYC - Set spending limits and card controls - Recharge and withdraw card balances - Query card transactions and account balances - Transfer funds between issuing accounts - Generate and download reports ## Authentication All requests require a valid auth token obtained via the [Access Token](/account-center/v1.6/api-reference/access-token) endpoint. Include the token in the `x-auth-token` header. ## Idempotency POST requests support the `x-idempotency-key` header to safely retry without creating duplicate resources. contact: name: UQPAY Support Team url: https://www.uqpay.com/support email: support@uqpay.com license: name: Proprietary url: https://www.uqpay.com/legal/api-terms termsOfService: https://www.uqpay.com/legal/terms x-api-id: uqpay-issuing-api-v1.6.0 x-categories: - Card Issuing - Transaction Processing x-features: - Virtual Card Issuance - Real-time Processing - Webhook Notifications - Comprehensive Reporting - Transaction Monitoring servers: - url: https://api-sandbox.uqpaytech.com/api description: Sandbox base URL. - url: https://api.uqpay.com/api description: Production base URL. security: [] tags: - name: Card Lifecycle description: >- Create cards and manage their full lifecycle — issue, retrieve, update, activate, assign, and change status. - name: Card Secure Data description: >- Access sensitive card data (PAN, CVV) through the PCI-compliant endpoint or a tokenized iframe. Availability depends on your PCI status, not the card product. - name: Card Funding description: Load and unload a card's stored balance for prepaid-style cards. - name: Card PIN description: >- Set and manage card PINs. `reset-pin` covers physical cards; `manage-card-pin` covers virtual cards. - name: Card Add-ons description: >- Product-specific card capabilities. Each operation applies only to certain card products — see [Card products](/card-issuance/v1.6/guide/card-products). - name: Card Arts description: >- Manage the visual designs (card arts) available to your issuing account. Set an account-wide default, or pass `card_art_id` when issuing or updating a card to override per card. Available on Personal Visa. - name: Cardholders description: >- You can create cardholders, which are authorized representatives of your business that can be issued cards. - name: Transactions description: >- These APIs allow you to retrieve information on transactions that are made on your user's cards. - name: Products description: >- With this set of APIs, you will be able to create card orders for your customers. - name: Balances description: >- The available and pending amounts for each currency are broken down further by payment source types. You can retrieve it to see the balance currently on your issuing account. - name: Transfers description: Transfer funds between issuing accounts. - name: Reports description: Generate and download issuing reports. - name: Simulator description: Simulate card transactions on the sandbox environment. paths: /v1/issuing/cards: get: tags: - Card Lifecycle summary: List Cards description: >- Returns a list of issuing card objects. The objects are sorted in descending order by creation date, with the most recently created object appearing first. operationId: list-cards parameters: - $ref: '#/components/parameters/XOnBehalfOf' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageNumber' - $ref: '#/components/parameters/PathCardNumber' - $ref: '#/components/parameters/PathCardStatus' - $ref: '#/components/parameters/PathCardholderId' responses: '200': description: OK - Successfully retrieved a list of cards. headers: x-response-id: $ref: '#/components/headers/XResponseId' content: application/json: schema: title: ListCardsResponse properties: total_pages: $ref: '#/components/schemas/TotalPages' total_items: $ref: '#/components/schemas/TotalItems' data: type: array items: $ref: '#/components/schemas/ListCardsResponse' security: - XAuthToken: [] components: parameters: XOnBehalfOf: in: header name: x-on-behalf-of schema: type: string required: false description: > Specifies the sub-account on whose behalf the request is made. This should be set to the `account_id`, which can be retrieved via the [List Connected Accounts](/account-center/v1.6/api-reference/list-connected-accounts) endpoint. If omitted or empty, the request is executed using the master account. More information at [Connected Accounts](/account-center/v1.6/guide/connected-accounts). example: 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be PageSize: name: page_size description: >- The maximum number of items to return per page. This number can be between 10 - 100, and will default to 10 in: query required: true schema: type: integer minimum: 10 maximum: 100 default: 10 PageNumber: name: page_number description: >- The page number to retrieve the next set of items. The number has to be greater than 1, and will default to 1 in: query required: true schema: type: integer minimum: 1 default: 1 PathCardNumber: name: card_number description: The full card number. in: query required: false schema: type: string example: '4096360811214526' PathCardStatus: name: card_status description: >- Retrieve items with the specified card status. Matches any card status if unspecified. in: query required: false schema: $ref: '#/components/schemas/CardStatus' PathCardholderId: name: cardholder_id in: query required: false schema: $ref: '#/components/schemas/CardholderId' headers: XResponseId: description: >- Universally unique identifier (UUID v4) for the response. Helpful for identifying a request when communicating with UQPAY support. schema: type: string format: uuid example: 2adba88e-9d63-44bc-b975-9b6ae3440dde schemas: TotalPages: type: integer example: 1 description: The total pages of available items. TotalItems: type: integer example: 10 description: The total counts of available items. ListCardsResponse: type: object required: - card_id - card_bin - mode_type - card_scheme - card_number - form_factor - card_limit - available_balance - cardholder - card_status - no_pin_payment_amount properties: card_id: $ref: '#/components/schemas/CardId' card_bin: $ref: '#/components/schemas/CardBin' card_scheme: $ref: '#/components/schemas/CardScheme' card_currency: $ref: '#/components/schemas/CardCurrency' card_number: $ref: '#/components/schemas/CardNumber' form_factor: $ref: '#/components/schemas/FormFactor' mode_type: $ref: '#/components/schemas/ModeType' card_product_id: $ref: '#/components/schemas/CardProductId' card_limit: $ref: '#/components/schemas/CardLimit' available_balance: type: string example: 2000.05 description: The available balance, currency refer to `card_currency`. cardholder: $ref: '#/components/schemas/CardholderListCardsResponse' risk_controls: $ref: '#/components/schemas/RiskControls' network_protection: $ref: '#/components/schemas/NetworkProtection' metadata: $ref: '#/components/schemas/Metadata' card_status: $ref: '#/components/schemas/CardStatus' update_reason: $ref: '#/components/schemas/UpdateReason' consumed_amount: $ref: '#/components/schemas/ConsumedAmount' CardStatus: type: string description: > Card status enum. See the Card lifecycle and statuses guide for more information. - `PENDING`: The request to create the card has been received and is under review. - `ACTIVE`: The request to create the card was successful and the card is ready to use. - `FROZEN`: All incoming authorization requests will be declined. The card can be reactivated to accept new authorizations. - `BLOCKED`: The card was blocked by UQPAY due to suspicious activity. - `PRE_CANCEL`: The card is scheduled for cancellation and is in a waiting period during which all incoming authorization requests are declined. It transitions to `CANCELLED` when the waiting period ends. - `CANCELLED`: The card cannot be reactivated from this state, all incoming authorization requests will be permanently declined. - `LOST`: The card has been reported as lost to UQPAY. - `STOLEN`: The card has been reported as stolen to UQPAY. - `FAILED`: The request to create a card using [Create Card](/card-issuance/v1.6/api-reference/create-card) failed. example: ACTIVE enum: - PENDING - ACTIVE - FROZEN - BLOCKED - PRE_CANCEL - CANCELLED - LOST - STOLEN - FAILED CardholderId: type: string description: The cardholder's unique identifier. example: 7c4ff2cd-1bf6-4aaa-bf16-266771425011 format: uuid CardId: type: string example: c0cef051-29c5-4796-b86a-cd5b684bfad7 description: Unique identifier for the card. CardBin: type: string example: '40963608' description: Card number prefix (BIN). CardScheme: type: string example: VISA description: Card scheme. CardCurrency: type: string example: USD description: The card currency. enum: - SGD - USD - XUSD CardNumber: type: string example: '************5668' description: Masked card number FormFactor: type: string example: VIRTUAL description: >- Form of the card - `VIRTUAL` or `PHYSICAL`, currently only support virtual card. enum: - VIRTUAL - PHYSICAL ModeType: type: string example: SHARE enum: - SHARE - SINGLE description: | Mode type enum - SINGLE or SHARE. * `SINGLE` - A single card only has prepaid mode. * `SHARE` - A share card can have debit mode, meaning it is associated with debit program and account. CardProductId: type: string description: The card product's unique identifier. example: 3bd1656b-e691-4aab-a76a-3ead39e7a6f6 format: uuid CardLimit: type: number example: 2100.02 minimum: 0 description: > The total credit limit assigned to the card, currency refer to `card_currency`. This is **not a cumulative balance**, but a fixed credit limit similar to that of a credit card. ##### Field behavior by card product: - **Business Mastercard** and **Personal Visa**: `card_limit` is **required** during card creation and must be **greater than or equal to 0.01**. - **Business Visa**: `card_limit` is **optional**. - If omitted, the system defaults `card_limit` to 0. - If provided, the value must be **greater than or equal to 0**, with up to two decimal places. **Negative values are not allowed.** See [Card products](/card-issuance/v1.6/guide/card-products) for the full capability matrix. CardholderListCardsResponse: type: object required: - amount - currency properties: cardholder_id: $ref: '#/components/schemas/CardholderId' cardholder_status: $ref: '#/components/schemas/CardholderStatus' create_time: description: Time at which the object was created. type: string example: '2024-05-09 15:52:23' email: $ref: '#/components/schemas/CardholderEmail' first_name: description: >- The first name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters. type: string example: Emily last_name: description: >- The last name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters. type: string example: Toy RiskControls: type: object description: > User-customized risk control settings. Supported configurations depend on the card product. See [Card products](/card-issuance/v1.6/guide/card-products) for the capability matrix. properties: enable_3ds: $ref: '#/components/schemas/Enable3ds' allow_3ds_transactions: $ref: '#/components/schemas/Allow3dsTransactions' allowed_mcc: $ref: '#/components/schemas/AllowedMcc' blocked_mcc: $ref: '#/components/schemas/BlockedMcc' NetworkProtection: type: object description: >- ASAF Network Protection state embedded in card response objects. Returned only for Visa cards. properties: enabled: type: boolean example: true description: Whether Network Protection is currently active on the card. card_scheme: type: string nullable: true example: VISA action_code: $ref: '#/components/schemas/NetworkProtectionActionCode' definition: type: string nullable: true example: Lost card, pickup description: Human-readable description of `action_code`. status: $ref: '#/components/schemas/NetworkProtectionStatus' submitted_time: type: string format: date-time nullable: true example: '2026-05-14T09:00:00Z' description: >- Time at which the latest enrollment or removal request was submitted. Metadata: additionalProperties: maxLength: 3200 type: string example: key1: value1 key2: value2 description: >- Any key-value object. Max length = 3200 bytes. This must be valid JSON data. type: object UpdateReason: type: string description: The reason for updating card status. maxLength: 100 minLength: 0 ConsumedAmount: type: string description: >- Reflects the cumulative amount of the card limit that has already been used. example: '51.00' CardholderStatus: description: The cardholder's status. type: string default: SUCCESS enum: - FAILED - PENDING - SUCCESS - INCOMPLETE CardholderEmail: type: string description: The cardholder's email address. example: demo@example.com Enable3ds: type: string description: > Controls whether [3D Secure](https://en.wikipedia.org/wiki/3-D_Secure) is registered for this card. - `Y` — Register 3DS. The challenge behavior at transaction time is then governed by `allow_3ds_transactions`. - `N` — Do not register 3DS. Online transactions bypass 3DS authentication entirely. Supported on **Business Visa** and **Personal Visa** only; ignored on Business Mastercard. See [Card products](/card-issuance/v1.6/guide/card-products). Returned only when explicitly set on the card. When absent, the card follows the account-level 3DS configuration. Modifiable only when the card is in `PENDING` or `ACTIVE` status. enum: - 'Y' - 'N' example: 'Y' Allow3dsTransactions: type: string description: > Determines whether [3D Secure](https://en.wikipedia.org/wiki/3-D_Secure) challenge flow is allowed when a transaction triggers 3DS. - **When creating a card:** Defaults to `Y` if not provided. - **When updating a card:** No default. If not provided, the existing value remains unchanged. Supported on **Business Visa** only. See [Card products](/card-issuance/v1.6/guide/card-products). > **Note:** This field only takes effect when `enable_3ds` is `Y`. If `enable_3ds` is `N`, the card bypasses 3DS entirely and this field has no effect. > **Important:** When set to `N`, your card uses a frictionless 3DS authentication mechanism — transactions complete without OTP input and are treated as cardholder-authenticated. As a result, disputes based on fraud or unauthorized use cannot be raised for such transactions. For enhanced security, it is recommended to keep this set to `Y`. - `Y`: OTP verification may be required. - `N`: No OTP will be required. enum: - 'Y' - 'N' example: 'Y' AllowedMcc: type: array items: type: string description: > Specifies a whitelist of Merchant Category Codes (MCCs) that are permitted for transactions. All transactions under MCCs not listed here will be declined. **Note:** Only one of `allowed_mcc` or `blocked_mcc` can be configured per card. If neither is provided, transactions will follow the default risk control logic. example: null BlockedMcc: type: array items: type: string description: > Specifies a blacklist of Merchant Category Codes (MCCs) that are restricted for transactions. Transactions under these MCCs will be declined, while all other transactions will proceed through the standard UQPAY risk control evaluation. **Note:** Only one of `allowed_mcc` or `blocked_mcc` can be configured per card. If neither is provided, transactions will follow the default risk control logic. example: - '5999' - '6011' NetworkProtectionActionCode: type: string description: > ASAF action code indicating the reason the card is enrolled in Network Protection. - `04` — Pickup card - `41` — Lost card, pickup - `43` — Stolen card, pickup - `46` — Closed account - `54` — Expired card enum: - '04' - '41' - '43' - '46' - '54' example: '41' NetworkProtectionStatus: type: string description: Lifecycle status of an ASAF Network Protection enrollment. enum: - NOT_ENROLLED - ENROLL_PENDING - ENROLL_FAILED - ENROLLED - REMOVAL_PENDING example: ENROLL_PENDING securitySchemes: XAuthToken: type: apiKey in: header name: x-auth-token description: The API token for login provided by UQPay. ````