> ## 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. # Create Card > Creates a card and issues it to a cardholder. Two calling modes are supported: - **Traditional mode** — pass `cardholder_id` to issue a card to an existing cardholder. Optionally pass `cardholder_required_fields` to supplement missing cardholder data required by the card product. - **One-step mode** — omit `cardholder_id` and pass a complete `cardholder_required_fields` block. The system creates the cardholder and the card in a single request. See [One-Step Card Issuance](/card-issuance/v1.6/guide/one-step-card-issuance) for the full integration flow. ## OpenAPI ````yaml /card-issuance/v1.6/issuing.yaml post /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: post: tags: - Card Lifecycle summary: Create Card description: > Creates a card and issues it to a cardholder. Two calling modes are supported: - **Traditional mode** — pass `cardholder_id` to issue a card to an existing cardholder. Optionally pass `cardholder_required_fields` to supplement missing cardholder data required by the card product. - **One-step mode** — omit `cardholder_id` and pass a complete `cardholder_required_fields` block. The system creates the cardholder and the card in a single request. See [One-Step Card Issuance](/card-issuance/v1.6/guide/one-step-card-issuance) for the full integration flow. operationId: create-card parameters: - $ref: '#/components/parameters/XOnBehalfOf' - $ref: '#/components/parameters/XIdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/CardCreationRequest' responses: '200': headers: x-response-id: $ref: '#/components/headers/XResponseId' description: Card creation successfully. content: application/json: schema: $ref: '#/components/schemas/CardCreationResponse' title: CardCreationResponse 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 XIdempotencyKey: in: header name: x-idempotency-key schema: type: string format: uuid required: true description: >- A unique identifier (UUID) used to maintain operation idempotency, ensuring that repeated executions of the same operation do not result in unintended effects or duplication. It helps preserve data consistency in the face of network errors, retries, or failures. example: 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be schemas: CardCreationRequest: type: object required: - card_currency - card_product_id properties: card_limit: $ref: '#/components/schemas/CardLimit' card_currency: $ref: '#/components/schemas/CardCurrency' name_on_card: $ref: '#/components/schemas/NameOnCard' cardholder_id: $ref: '#/components/schemas/CardholderId' description: > The unique identifier of the cardholder to issue the card to. Either `cardholder_id` or a complete `cardholder_required_fields` block must be provided. When `cardholder_id` is omitted, the system creates a new cardholder inline using the values in `cardholder_required_fields`. See [One-Step Card Issuance](/card-issuance/v1.6/guide/one-step-card-issuance). card_product_id: type: string description: The card product's unique identifier. example: 7c4ff2cd-1bf6-4aaa-bf16-266771425011 card_art_id: $ref: '#/components/schemas/CardArtId' description: > Card art to apply to the new card. When omitted, the card uses the default card art for the issuing account — see [Card art](/card-issuance/v1.6/guide/card-art) for how the default is resolved. The value must be a card art available to the issuing account. List available card arts via [List card arts](/card-issuance/v1.6/api-reference/list-card-arts). spending_controls: $ref: '#/components/schemas/SpendingControls' risk_controls: $ref: '#/components/schemas/RiskControls' metadata: $ref: '#/components/schemas/Metadata' usage_type: type: string description: > Indicates whether the card is a standard reusable card or a one-time-use card. * `NORMAL` - A standard card that can be used for multiple transactions. * `ONE_TIME` - A one-time-use card that is automatically cancelled after the first transaction event defined by `auto_cancel_trigger`. default: NORMAL enum: - NORMAL - ONE_TIME example: NORMAL auto_cancel_trigger: type: string description: > Defines the transaction event that triggers automatic cancellation of a `ONE_TIME` card. Required when `usage_type` is `ONE_TIME`. * `ON_AUTH` - The card is cancelled immediately after the first authorization is approved. Subsequent authorization requests on the same card will be declined. * `ON_CAPTURE` - The card is cancelled after the first transaction's capture (settlement) succeeds, allowing a full authorization and capture cycle to complete. enum: - ON_AUTH - ON_CAPTURE example: ON_AUTH expiry_at: type: string format: date-time description: >- The absolute expiry date and time of the card. If the card has not been cancelled by a first-transaction event before this time, it is automatically cancelled and any unused balance is released. example: '2026-03-19T18:46:43+08:00' cardholder_required_fields: $ref: '#/components/schemas/CardholderRequiredFields' description: > Cardholder information supplied at card creation time. - In **traditional mode** (`cardholder_id` provided): optional; fields supplied here are used to supplement missing cardholder data before the card is issued. - In **one-step mode** (`cardholder_id` omitted): required and must contain a complete set of cardholder-creation fields (`email`, `first_name`, `last_name`, `country_code`, `phone_number`). The system creates the cardholder inline. CardCreationResponse: type: object required: - card_id - card_order_id - create_time - card_status - order_status properties: card_id: $ref: '#/components/schemas/CardId' card_order_id: $ref: '#/components/schemas/CardOrderId' create_time: $ref: '#/components/schemas/CreateTime' card_status: $ref: '#/components/schemas/CardStatus' order_status: $ref: '#/components/schemas/OrderStatus' risk_controls: $ref: '#/components/schemas/RiskControls' description: >- The risk control settings applied to the card. Echoed from the request, or populated from the card product defaults when not supplied. cardholder_id: $ref: '#/components/schemas/CardholderId' description: > The cardholder's unique identifier. In one-step mode, this is the newly-created cardholder — save this value to reference the cardholder later. cardholder_created: type: boolean description: > `true` when a new cardholder was created inline as part of this request. Omitted otherwise. example: true cardholder_status: $ref: '#/components/schemas/CardholderStatus' verification_status: $ref: '#/components/schemas/VerificationStatus' description: > The KYC verification outcome for the cardholder. Returned when supplement fields triggered KYC processing. kyc_method: type: string description: > Echoes the KYC verification method that was applied. Returned when `cardholder_required_fields.kyc_verification` was supplied in the request. * `THIRD_PARTY` - Merchant-supplied KYC proof was used. * `SUMSUB_REDIRECT` - The cardholder is redirected to Sumsub to complete IDV. enum: - THIRD_PARTY - SUMSUB_REDIRECT example: SUMSUB_REDIRECT idv_verification_url: type: string format: uri description: > The IDV verification URL the cardholder must visit to complete identity verification. Returned only when `kyc_method` is `SUMSUB_REDIRECT`. example: https://in.sumsub.com/websdk/p/sbx_4dwsbDuDbpJsMgou idv_url_expires_at: type: string format: date-time description: >- The expiry time of `idv_verification_url`. Returned only when `kyc_method` is `SUMSUB_REDIRECT`. example: '2026-04-25T17:26:50+08:00' message: type: string description: >- Informational message when card creation is blocked or pending due to KYC requirements (e.g., insufficient KYC, missing fields). 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. CardCurrency: type: string example: USD description: The card currency. enum: - SGD - USD - XUSD NameOnCard: type: string maxLength: 26 example: MARSHALL HU description: > The cardholder name shown on the card. When the [Secure Iframe](/card-issuance/v1.6/guide/secure-iframe-guide) renders the cardholder name (`cardholder_name=true`), this value is used as the default; if omitted, the iframe falls back to `first_name + last_name` from the cardholder record. CardholderId: type: string description: The cardholder's unique identifier. example: 7c4ff2cd-1bf6-4aaa-bf16-266771425011 format: uuid CardArtId: type: string example: 01KD52BKQWDMFF63R1NNQN7A79 description: >- Identifier of a card art. Stable across card products; reuse the same value when creating multiple cards with the same design. SpendingControls: type: array description: Rules that control spending for this card. items: type: object required: - amount - interval properties: amount: type: number description: >- Maximum amount allowed to spend per interval, must be greater than or equal to zero. example: 100.03 minimum: 0 interval: type: string example: PER_TRANSACTION enum: - PER_TRANSACTION description: | Interval (or event) to which the amount applies. This field is mandatory and must be one of: * `PER_TRANSACTION` - Can not exceed the max authorization amount 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' 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 CardholderRequiredFields: type: object description: > Cardholder information supplied at card creation time. Used in two ways: - **Supplement an existing cardholder** — when `cardholder_id` is provided, any fields supplied here fill in gaps on the existing cardholder record before the card is issued. All properties are optional in this mode. - **Create a cardholder inline (one-step card issuance)** — when `cardholder_id` is omitted, this object must contain a complete set of cardholder-creation fields: `email`, `first_name`, `last_name`, `country_code`, and `phone_number`. The system creates the cardholder and issues the card in a single request. See [One-Step Card Issuance](/card-issuance/v1.6/guide/one-step-card-issuance). properties: email: $ref: '#/components/schemas/CardholderEmail' first_name: $ref: '#/components/schemas/CardholderFirstName' last_name: $ref: '#/components/schemas/CardholderLastName' country_code: $ref: '#/components/schemas/CountryCode' phone_number: $ref: '#/components/schemas/CardholderPhoneNumber' date_of_birth: $ref: '#/components/schemas/CardholderDateOfBirth' gender: $ref: '#/components/schemas/Gender' nationality: $ref: '#/components/schemas/Nationality' residential_address: $ref: '#/components/schemas/ResidentialAddress' identity: $ref: '#/components/schemas/Identity' kyc_verification: $ref: '#/components/schemas/KycVerification' CardId: type: string example: c0cef051-29c5-4796-b86a-cd5b684bfad7 description: Unique identifier for the card. CardOrderId: type: string example: c0cef051-29c5-4796-b86a-cd5ee34bfad7 description: ID of the card order. CreateTime: type: string description: Create time at which the object was created. example: '2024-03-21T17:17:32+08:00' 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 OrderStatus: type: string description: | This field will contain the status of the request after processing. * `PENDING` -The initial status of the order request. * `PROCESSING` - If this status shall be subject to webhooks notification. * `SUCCESS` - The final status of the order request is successful. * `FAILED` - The final status of the order request is failed. enum: - PENDING - PROCESSING - SUCCESS - FAILED CardholderStatus: description: The cardholder's status. type: string default: SUCCESS enum: - FAILED - PENDING - SUCCESS - INCOMPLETE VerificationStatus: type: string description: > The KYC verification outcome for the cardholder associated with this card creation request. * `VERIFIED` - The cardholder's identity has been verified. * `UNDER_REVIEW` - AML or KYC review is in progress. * `ACTION_REQUIRED` - The cardholder must complete an action (such as Sumsub IDV) before the card can be activated. enum: - VERIFIED - UNDER_REVIEW - ACTION_REQUIRED example: UNDER_REVIEW 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' CardholderEmail: type: string description: The cardholder's email address. example: demo@example.com CardholderFirstName: description: >- The first name of the cardholder. Must be between 1 and 40 characters, containing only alphabetic characters and spaces. Spaces are not allowed at the beginning or end of the name. type: string example: Emily CardholderLastName: description: >- The last name of the cardholder. Must be between 1 and 40 characters, containing only alphabetic characters and spaces. Spaces are not allowed at the beginning or end of the name. type: string example: Toy CountryCode: type: string description: >- Two-letter country code [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). maxLength: 2 example: SG CardholderPhoneNumber: description: > The cardholder's phone number. See [Phone number validation rules](/card-issuance/v1.6/guide/phone-number-validation-rules-for-cardholder) for length validation details. type: string example: '86683306' CardholderDateOfBirth: description: The cardholder's birth date with `yyyy-mm-dd` format. type: string example: '1990-01-01' Gender: type: string description: | The cardholder's gender. * `MALE` - Male. * `FEMALE` - Female. enum: - MALE - FEMALE example: MALE Nationality: type: string description: >- The cardholder's nationality in ISO 3166-1 alpha-2 format. Required for STANDARD and ENHANCED KYC levels. minLength: 2 maxLength: 2 example: SG ResidentialAddress: type: object description: > The cardholder's residential address. All fields accept only letters (A-Z, a-z), digits (0-9), spaces, and the following punctuation: `, . ' / # ( ) - &`. Requests containing any other character are rejected — correct the value and resubmit. Empty optional fields are not validated. required: - country - city - line1 properties: country: $ref: '#/components/schemas/Country' state: type: string description: State, county, province, or region. maxLength: 128 example: Singapore city: type: string description: City, district, suburb, town, or village. maxLength: 128 example: Singapore district: type: string description: District or sub-region within the city. maxLength: 128 example: Buona Vista line1: type: string description: Address line 1 (e.g., street, PO Box, or company name). maxLength: 255 example: 9 N Buona Vista Dr line2: type: string description: Address line 2 (e.g., apartment, suite, unit, or building). maxLength: 255 example: THE METROPOLIS line_en: type: string description: Address in English. maxLength: 255 example: 9 N Buona Vista Dr, THE METROPOLIS postal_code: type: string description: >- ZIP or postal code. If you intend to issue an Enhanced card, this field must be 4-10 characters long. maxLength: 16 example: '138666' Identity: type: object description: >- The cardholder's identity document information. Required for STANDARD and ENHANCED KYC levels. required: - type - number - front_file properties: type: type: string description: | Identity document type. * `ID_CARD` - National identity card. * `PASSPORT` - Passport. enum: - ID_CARD - PASSPORT example: PASSPORT number: type: string description: Identity document number. example: E12345678 front_file: type: string description: Base64 encoded front side image of the identity document. back_file: type: string description: >- Base64 encoded back side image of the identity document. Required when `type` is `ID_CARD`. hand_file: type: string description: Base64 encoded hand-held identity document photo. KycVerification: type: object description: KYC verification information. Required for ENHANCED KYC level. required: - method properties: method: type: string description: | The KYC verification method. * `THIRD_PARTY` - Merchant has completed verification via a third-party provider and submits proof. * `SUMSUB_REDIRECT` - Redirect the cardholder to Sumsub for IDV verification. enum: - THIRD_PARTY - SUMSUB_REDIRECT example: THIRD_PARTY kyc_proof: $ref: '#/components/schemas/KycProof' Country: type: string description: >- Two-letter country code [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). maxLength: 2 example: SG KycProof: type: object description: >- Third-party KYC verification proof. Required when `method` is `THIRD_PARTY`. required: - provider - reference_id - documents properties: provider: type: string description: The third-party KYC provider name (e.g., `SUMSUB`). example: SUMSUB reference_id: type: string description: >- The reference ID from the third-party provider. Must be at least 10 characters and globally unique. minLength: 10 example: sumsub_ref_1234567890 documents: type: array description: > Compliance report files backing the third-party verification. Each entry points to a file previously uploaded through [Upload A File](/account-center/v1.6/api-reference/upload-file). You must provide an identity verification report — either a standalone `IDV` report or a combined `IDV_AML` report. An anti-money-laundering (`AML`) report is optional. Submit the reports as separate files (`IDV` plus `AML`) or as a single combined file (`IDV_AML`). minItems: 1 items: $ref: '#/components/schemas/KycProofDocument' KycProofDocument: type: object required: - file_id - report_type properties: file_id: type: string description: >- The ID of an uploaded file, returned by [Upload A File](/account-center/v1.6/api-reference/upload-file). example: b3d9d2d5-4c12-4946-a09d-953e82sed2b0 report_type: $ref: '#/components/schemas/KycReportType' KycReportType: type: string description: | The compliance report the file contains. * `IDV` - An identity verification report only. * `AML` - An anti-money-laundering screening report only. * `IDV_AML` - A single file covering both identity verification and anti-money-laundering. enum: - IDV - AML - IDV_AML example: IDV 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 securitySchemes: XAuthToken: type: apiKey in: header name: x-auth-token description: The API token for login provided by UQPay. ````