---
title: "Create Card"
method: POST
path: "/v1/issuing/cards"
tags: ["Card Lifecycle"]
---

# Create Card

`POST /v1/issuing/cards`

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.

## Headers

- `x-on-behalf-of` string
- `x-idempotency-key` string, uuid

## Request body

- CardCreationRequest
  - `card_limit` number — 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.
  - `card_currency` 'SGD' | 'USD' | 'XUSD', required — The card currency.
  - `name_on_card` string — 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.
  - `cardholder_id` string, uuid — The cardholder's unique identifier.
  - `card_product_id` string, required — The card product's unique identifier.
  - `card_art_id` string — Identifier of a card art. Stable across card products; reuse the same value when creating multiple cards with the same design.
  - `spending_controls` object[] — Rules that control spending for this card.
    - `amount` string, required — Maximum amount allowed to spend per interval, as a decimal string. Must be greater than or equal to zero.
    - `interval` 'PER_TRANSACTION', required — 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
  - `risk_controls` RiskControls — 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.
    - `enable_3ds` 'Y' | 'N' — 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.
    - `allow_3ds_transactions` 'Y' | 'N' — 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.
    - `allowed_mcc` string[] — 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.
    - `blocked_mcc` string[] — 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.
  - `metadata` Metadata — Any key-value object. Max length = 512 bytes. This must be valid JSON data.
  - `usage_type` 'NORMAL' | 'ONE_TIME' — 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`.
  - `auto_cancel_trigger` 'ON_AUTH' | 'ON_CAPTURE' — 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.
  - `expiry_at` string, date-time — 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.
  - `cardholder_required_fields` CardholderRequiredFields — 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).
    - `email` string — The cardholder's email address.
    - `first_name` string — 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.
    - `last_name` string — 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.
    - `country_code` string — Two-letter country code [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
    - `phone_number` string — 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.
    - `date_of_birth` string — The cardholder's birth date with `yyyy-mm-dd` format.
    - `gender` 'MALE' | 'FEMALE' — The cardholder's gender. * `MALE` - Male. * `FEMALE` - Female.
    - `nationality` string — The cardholder's nationality in ISO 3166-1 alpha-2 format. Required for STANDARD and ENHANCED KYC levels.
    - `residential_address` ResidentialAddress — 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.
      - `country` string, required — Two-letter country code [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
      - `state` string — State, county, province, or region.
      - `city` string, required — City, district, suburb, town, or village.
      - `district` string — District or sub-region within the city.
      - `line1` string, required — Address line 1 (e.g., street, PO Box, or company name).
      - `line2` string — Address line 2 (e.g., apartment, suite, unit, or building).
      - `line_en` string — Address in English.
      - `postal_code` string — ZIP or postal code. If you intend to issue an Enhanced card, this field must be 4-10 characters long.
    - `identity` Identity — The cardholder's identity document information. Required for STANDARD and ENHANCED KYC levels.
      - `type` 'ID_CARD' | 'PASSPORT', required — Identity document type. * `ID_CARD` - National identity card. * `PASSPORT` - Passport.
      - `number` string, required — Identity document number.
      - `front_file` string, required — Base64 encoded front side image of the identity document.
      - `back_file` string — Base64 encoded back side image of the identity document. Required when `type` is `ID_CARD`.
      - `hand_file` string — Base64 encoded hand-held identity document photo.
    - `kyc_verification` KycVerification — KYC verification information. Required for ENHANCED KYC level.
      - `method` 'THIRD_PARTY' | 'SUMSUB_REDIRECT', required — 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.
      - `kyc_proof` KycProof — Third-party KYC verification proof. Required when `method` is `THIRD_PARTY`.
        - `provider` string, required — The third-party KYC provider name (e.g., `SUMSUB`).
        - `reference_id` string, required — The reference ID from the third-party provider. Must be at least 10 characters and globally unique.
        - `documents` KycProofDocument[], required — 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`).
          - `file_id` string, required — The ID of an uploaded file, returned by [Upload A File](/account-center/v1.6/api-reference/upload-file).
          - `report_type` 'IDV' | 'AML' | 'IDV_AML', required — 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.

## Response `200`

Card creation successfully.

- CardCreationResponse
  - `card_id` string, required — Unique identifier for the card.
  - `card_order_id` string, required — ID of the card order.
  - `create_time` string, date/time, required — The timestamp when the record was created in the system. Timestamp follows the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard.
  - `card_status` 'PENDING' | 'ACTIVE' | 'FROZEN' | 'BLOCKED' | 'PRE_CANCEL' | 'CANCELLED' | 'LOST' | 'STOLEN' | 'FAILED', required — 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.
  - `order_status` 'PENDING' | 'PROCESSING' | 'SUCCESS' | 'FAILED', required — 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.
  - `risk_controls` RiskControls — 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.
    - `enable_3ds` 'Y' | 'N' — 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.
    - `allow_3ds_transactions` 'Y' | 'N' — 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.
    - `allowed_mcc` string[] — 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.
    - `blocked_mcc` string[] — 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.
  - `cardholder_id` string, uuid — The cardholder's unique identifier.
  - `cardholder_created` boolean — `true` when a new cardholder was created inline as part of this request. Omitted otherwise.
  - `cardholder_status` 'FAILED' | 'PENDING' | 'SUCCESS' | 'INCOMPLETE' — The cardholder's status.
  - `verification_status` 'VERIFIED' | 'UNDER_REVIEW' | 'ACTION_REQUIRED' — 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.
  - `kyc_method` 'THIRD_PARTY' | 'SUMSUB_REDIRECT' — 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.
  - `idv_verification_url` string, uri — The IDV verification URL the cardholder must visit to complete identity verification. Returned only when `kyc_method` is `SUMSUB_REDIRECT`.
  - `idv_url_expires_at` string, date-time — The expiry time of `idv_verification_url`. Returned only when `kyc_method` is `SUMSUB_REDIRECT`.
  - `message` string — Informational message when card creation is blocked or pending due to KYC requirements (e.g., insufficient KYC, missing fields).

---

[API](https://skmtc.dev/uqpay/apis/authentication-api.md) · [All operations](https://skmtc.dev/uqpay/apis/authentication-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/uqpay/authentication-api/revisions/cef532a10777/schema)