Card art

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.

Where card art appears

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;
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:

Account binding — a card art explicitly bound to the issuing account.
Master account binding — if the issuing account has no binding of its own, the platform falls back to bindings on its master account.
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.

Getting Started

Cardholders

Cards

Funding

Controls & Security

Integration

Reference

Where card art appears

Default resolution order

List available card arts

Set the default card art

Issue a card with a specific card art

Change the card art on an existing card

Errors

​Where card art appears

​Default resolution order

​List available card arts

​Set the default card art

​Issue a card with a specific card art

​Change the card art on an existing card

​Errors

​Related

Where card art appears

Default resolution order

List available card arts

Set the default card art

Issue a card with a specific card art

Change the card art on an existing card

Errors

Related