One-Step Card Issuance

The standard card issuance flow is two calls — Create Cardholder first, then Create Card with the returned cardholder_id. One-step mode collapses the two into one call: omit cardholder_id and put the cardholder data into cardholder_required_fields. The system creates the cardholder and issues the card in the same request. Use one-step mode when you issue cards on demand — for example, right after a user signs up, or in a single-screen onboarding flow. If you manage a pool of pre-built cardholders, stay with the traditional two-call flow; passing cardholder_id works exactly as before.

For Personal Visa, follow Apply for Personal Visa to prepare the product’s required information and meet its KYC requirements, then create a card using cardholder_id. Cardholders with an eligible residence and a Red-group nationality must provide proof of address, which does not require a separate approval wait. One-step cardholder_required_fields.identity does not accept proof_of_address or identity_verification; a non-empty value for either attachment returns a parameter error.

Prerequisites

A UQPAY sandbox account with Card Issuance enabled
An API token from Access Token
The target card product’s card_product_id, obtained via List Products

Step 1: Check which fields the product requires

Different card products (BINs) require different cardholder data. List card products and read the required_fields array on your target product — that is the exact list of cardholder fields you must supply to the create-card call.

curl "https://api-sandbox.uqpaytech.com/api/v1/issuing/products?page_number=1&page_size=10" \
  -H "x-auth-token: Bearer {your_auth_token}"

Response (key fields only):

{
  "product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
  "card_bin": "40963608",
  "required_fields": [
    { "name": "first_name",    "type": "string", "required": true },
    { "name": "last_name",     "type": "string", "required": true },
    { "name": "email",         "type": "string", "required": true },
    { "name": "country_code",  "type": "string", "required": true },
    { "name": "phone_number",  "type": "string", "required": true },
    { "name": "date_of_birth", "type": "string", "required": false }
  ]
}

Fields marked required: true must be provided; required: false fields are optional. Object-typed fields such as identity, residential_address, and kyc_verification follow a nested structure — their sub-field rules are given in the product’s fields array.

Step 2: Create the card with cardholder data inline

Put the product’s required fields into cardholder_required_fields and omit cardholder_id:

curl -X POST "https://api-sandbox.uqpaytech.com/api/v1/issuing/cards" \
  -H "Content-Type: application/json" \
  -H "x-auth-token: Bearer {your_auth_token}" \
  -H "x-idempotency-key: {unique_uuid}" \
  -d '{
    "card_product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
    "card_currency": "USD",
    "card_limit": "500.00",
    "cardholder_required_fields": {
      "email": "alex.chen@example.com",
      "first_name": "Alex",
      "last_name": "Chen",
      "country_code": "SG",
      "phone_number": "90851548"
    }
  }'

Response:

{
  "card_order_id": "86411dab-9820-4042-b103-39989deb957d",
  "card_id": "b52e93a8-3c1d-453e-81ac-ec7268fad082",
  "cardholder_id": "a32835fe-141e-41fd-bcce-9fe88b3e8cbd",
  "card_status": "PENDING",
  "order_status": "PROCESSING",
  "create_time": "2026-04-24T18:07:49+08:00",
  "cardholder_status": "SUCCESS",
  "cardholder_created": true,
  "verification_status": "VERIFIED",
  "message": "card creation in progress"
}

A few fields to note:

cardholder_id — the newly-created cardholder. Save this value if you need to manage the cardholder later.
card_status: PENDING + order_status: PROCESSING — the card is being provisioned asynchronously. This is not a failure; wait for the card.create.succeeded webhook before treating the card as active.
cardholder_created: true — the cardholder was created inline as part of this request.

Special case: Sumsub IDV

If the product’s required_fields list kyc_verification, and you ask UQPAY to run identity verification through Sumsub (method: SUMSUB_REDIRECT), the response carries an IDV URL:

{
  "card_id": "ef5c44df-8c31-4adf-88b2-22ff7ce0e6d8",
  "cardholder_id": "9cb41553-e186-4e43-a17a-07f0772c6c75",
  "card_status": "PENDING",
  "cardholder_status": "INCOMPLETE",
  "idv_verification_url": "https://in.sumsub.com/websdk/p/sbx_xxx",
  "idv_url_expires_at": "2026-04-25T18:09:19+08:00",
  "kyc_method": "SUMSUB_REDIRECT",
  "verification_status": "ACTION_REQUIRED"
}

Redirect the cardholder to idv_verification_url before idv_url_expires_at. Once Sumsub confirms verification, the order you already requested follows its existing execution flow, including checks for region, applicable POA, and other issuance requirements. Confirm the final result through the card webhook. Uploading POA does not request a new card or reopen a failed request. If you have already run KYC on your side and want to submit a proof directly, use method: THIRD_PARTY with a kyc_proof block; the response returns verification_status: VERIFIED without any redirect. See Enhanced KYC Card Issuance for the full details.

Waiting for async completion

For every one-step request, the initial HTTP response is only an acknowledgement. The card’s real activation (and the cardholder’s final state) happens asynchronously. Subscribe to these two webhooks before calling the endpoint:

Cardholder KYC Status Changed — cardholder KYC review completed
Card Created — card activated or creation failed

Error handling

Two errors are specific to one-step mode. Both return HTTP 400.

`cardholder_missing_info`

Neither cardholder_id nor cardholder_required_fields was provided.

{
  "type": "cardholder_error",
  "code": "cardholder_missing_info",
  "message": "either cardholder_id or complete cardholder_required_fields must be provided"
}

`cardholder_incomplete_fields`

cardholder_required_fields was provided but missing one or more required keys (for example, email, first_name). The response carries a missing_fields array so you can display a targeted error to your user.

{
  "type": "cardholder_error",
  "code": "cardholder_incomplete_fields",
  "message": "cardholder_required_fields is incomplete for one-step card issuance",
  "missing_fields": ["email", "first_name", "last_name", "country_code"]
}

Other common errors (email_duplicated, phone_number_duplicated, invalid_phone_number, etc.) are the standard cardholder_error codes. See the Create Card API reference for the full list.

Getting Started

Cardholders

Cards

Funding

Controls & Security

Integration

Reference

Prerequisites

Step 1: Check which fields the product requires

Step 2: Create the card with cardholder data inline

Special case: Sumsub IDV

Waiting for async completion

Error handling

`cardholder_missing_info`

`cardholder_incomplete_fields`

​Prerequisites

​Step 1: Check which fields the product requires

​Step 2: Create the card with cardholder data inline

​Special case: Sumsub IDV

​Waiting for async completion

​Error handling

​cardholder_missing_info

​cardholder_incomplete_fields

​Related

Prerequisites

Step 1: Check which fields the product requires

Step 2: Create the card with cardholder data inline

Special case: Sumsub IDV

Waiting for async completion

Error handling

`cardholder_missing_info`

`cardholder_incomplete_fields`

Related