Card art

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

A card art is the visual design that appears in Apple Wallet when a cardholder adds an Enhanced virtual card to Apple 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.

Where card art appears

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

• the cardholder has completed Enhanced KYC — see Enhanced KYC card issuance;
• the cardholder has added their virtual card to Apple 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.

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

List available card arts

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

curl https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/arts \
  -H "x-auth-token: YOUR_API_TOKEN"

Response:

{
  "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 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.

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:

{
  "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 request to override the default for one card:

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 request to change the art on a card that’s already issued:

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.

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.

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 for the full reference.

Related

• Create Card API
• Update Card API
• List Card Arts API
• Set Default Card Art API