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

# Card art

> Choose the artwork shown in Apple Wallet and Google Wallet when an Enhanced virtual card is added to Apple Pay or Google Pay.

A **card art** is the visual design that appears in Apple Wallet or Google Wallet when a cardholder adds an Enhanced virtual card to Apple Pay or Google Pay. Each card art has a stable `card_art_id` that you reference when creating or updating a card.

Every card is issued with exactly one card art. You can:

* **List** the card arts available to an issuing account.
* **Set a default** card art so subsequent card-creation calls don't need to pass `card_art_id`.
* **Override per card** by passing `card_art_id` on Create Card or Update Card.

<h2 id="where-card-art-appears">
  Where card art appears
</h2>

In this release, card art is rendered **in Apple Wallet and Google Wallet**, and only when both of the following are true:

* the cardholder has completed **Enhanced KYC** — see [Enhanced KYC card issuance](/card-issuance/v1.6/guide/enhanced-kyc-card-issuance);
* the cardholder has added their virtual card to Apple Pay or Google Pay.

Card art is not surfaced in your own UI, on physical cards (whose design is fixed at print time and is not controlled by this API), or on cards that have not been added to Apple Pay or Google Pay.

Calls to List Card Arts, Set Default Card Art, and `card_art_id` on Create Card / Update Card still succeed for cards outside this surface — the `card_art_id` is recorded on the card — but the chosen card art only takes visual effect inside the wallet once the conditions above are met.

## Default resolution order

When a Create Card or Update Card request omits `card_art_id`, the platform resolves the default in this order:

1. **Account binding** — a card art explicitly bound to the issuing account.
2. **Master account binding** — if the issuing account has no binding of its own, the platform falls back to bindings on its master account.
3. **Channel system default** — if neither account has a binding, the platform falls back to the channel's system-default card art (configured by UQPAY).

If none of the three resolves — for example, a freshly onboarded channel with no system default and no bindings — Create Card and Update Card return [`card_art_not_configured`](/card-issuance/v1.6/guide/error-codes).

## List available card arts

Call [List Card Arts](/card-issuance/v1.6/api-reference/list-card-arts) to populate your card-art picker before issuing or updating a card. The endpoint takes no query parameters; the issuing account is resolved from your auth token or the `x-on-behalf-of` header.

```bash theme={null}
curl https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/arts \
  -H "x-auth-token: YOUR_API_TOKEN"
```

**Response:**

```json theme={null}
{
  "default_card_art_id": "01KD52C4ZW0Z2XBT7B8M4QX0YZ",
  "card_arts": [
    {
      "card_art_id": "01KD52C4ZW0Z2XBT7B8M4QX0YZ",
      "description": "Premium Black",
      "is_default": true,
      "is_system_config": false
    },
    {
      "card_art_id": "01KD52BKQWDMFF63R1NNQN7A79",
      "description": "Basic Design",
      "is_default": false,
      "is_system_config": true
    }
  ]
}
```

`is_default` marks the card art used when `card_art_id` is omitted on Create Card. `is_system_config` marks card arts that come from the channel's system configuration and are always available to every account on the channel.

## Set the default card art

Call [Set Default Card Art](/card-issuance/v1.6/api-reference/set-default-card-art) to change which card art is used when `card_art_id` is omitted on Create Card. The new value must be one of the card arts returned by List Card Arts.

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/arts/default \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "card_art_id": "01KD52BKQWDMFF63R1NNQN7A79"
  }'
```

**Response:**

```json theme={null}
{
  "default_card_art_id": "01KD52BKQWDMFF63R1NNQN7A79",
  "updated_at": "2026-05-20 10:32:18"
}
```

Setting the default to the channel's system-default card art clears any explicit account-level default — the account then falls back to the system default through the resolution order above.

## Issue a card with a specific card art

Pass `card_art_id` on the [Create Card](/card-issuance/v1.6/api-reference/create-card) request to override the default for one card:

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
    "card_product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
    "card_currency": "USD",
    "card_limit": 1000,
    "card_art_id": "01KD52C4ZW0Z2XBT7B8M4QX0YZ"
  }'
```

The card art is snapshotted onto the card at issuance time. Changing the account's default later does not change the art on cards already issued.

## Change the card art on an existing card

Pass `card_art_id` on the [Update Card](/card-issuance/v1.6/api-reference/update-card) request to change the art on a card that's already issued:

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id} \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "card_art_id": "01KD52BKQWDMFF63R1NNQN7A79"
  }'
```

Card-art updates are processed **asynchronously** — Update Card returns `order_status: PROCESSING`, and the new card art takes effect once the channel confirms the change.

<Warning>
  Card-art updates apply only to:

  * `VIRTUAL` cards. Physical card art is fixed at print time and cannot be changed.
  * Cards whose `card_status` and `processing_status` are both `ACTIVE`. Frozen, cancelled, or pending cards are rejected.

  If either constraint fails, the request returns a `card_error`.
</Warning>

## Errors

| `code`                    | When it appears                                                    | What to do                                                                               |
| ------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `card_art_not_available`  | The `card_art_id` you sent is not in the account's available list. | Call **List Card Arts** to see allowed values, or omit `card_art_id` to use the default. |
| `card_art_not_configured` | No system default and no binding exists for the channel.           | Contact your UQPAY solutions engineer to configure card art for the channel.             |
| `card_art_not_supported`  | The card product does not support card art selection.              | Omit `card_art_id`, or use a card product that supports card art.                        |

See [Error codes](/card-issuance/v1.6/guide/error-codes) for the full reference.

## Related

* [Create Card API](/card-issuance/v1.6/api-reference/create-card)
* [Update Card API](/card-issuance/v1.6/api-reference/update-card)
* [List Card Arts API](/card-issuance/v1.6/api-reference/list-card-arts)
* [Set Default Card Art API](/card-issuance/v1.6/api-reference/set-default-card-art)