> ## 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.

# One-Step Card Issuance

> Create a cardholder and issue a card in a single API call.

The standard card issuance flow is two calls — [Create Cardholder](/card-issuance/v1.6/api-reference/create-cardholder) first, then [Create Card](/card-issuance/v1.6/api-reference/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.

## Prerequisites

<Info>
  * A UQPAY sandbox account with Card Issuance enabled
  * An API token from [Access Token](/account-center/v1.6/api-reference/access-token)
  * The target card product's `card_product_id`, obtained via [List Products](/card-issuance/v1.6/api-reference/list-card-products)
</Info>

## 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.

```bash theme={null}
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):**

```json theme={null}
{
  "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`:

```bash theme={null}
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:**

```json theme={null}
{
  "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`](/card-issuance/v1.6/webhooks/card-created) 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:

```json theme={null}
{
  "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 the verification, UQPAY activates the card automatically and notifies you by webhook.

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](/card-issuance/v1.6/guide/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](/card-issuance/v1.6/webhooks/cardholder-kyc-status-changed) — cardholder KYC review completed
* [Card Created](/card-issuance/v1.6/webhooks/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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/card-issuance/v1.6/api-reference/create-card) for the full list.

## Related

* [Create Card (API reference)](/card-issuance/v1.6/api-reference/create-card)
* [Create and Manage Cardholders](/card-issuance/v1.6/guide/create-and-manage-cardholders)
* [Enhanced KYC Card Issuance](/card-issuance/v1.6/guide/enhanced-kyc-card-issuance)