> ## Documentation Index
> Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 卡面

> 选择 Enhanced 虚拟卡或实体卡绑定 Apple Pay 或 Google Pay 后，在 Apple Wallet 与 Google Wallet 中展示的视觉设计。

**卡面**（card art）是持卡人将 Enhanced 虚拟卡或实体卡添加到 Apple Pay 或 Google Pay 后，在 Apple Wallet 或 Google Wallet 中看到的视觉设计。每个卡面都有一个稳定的 `card_art_id`，在创建或更新卡片时引用它。

每张卡只关联一个卡面。你可以：

* **列出**发卡账户可用的卡面。
* **设置默认**卡面，后续创建卡片时无需再传 `card_art_id`。
* **单卡覆盖**：在 Create Card 或 Update Card 接口中传 `card_art_id`。

## 卡面的展示范围

本次发布中，卡面**在 Apple Wallet 与 Google Wallet 中渲染**，且仅当同时满足以下两个条件时生效：

* 持卡人已完成 **Enhanced KYC** —— 参见 [Enhanced KYC 发卡](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/enhanced-kyc-card-issuance.md)；
* 持卡人已将虚拟卡或实体卡添加到 Apple Pay 或 Google Pay。

卡面不会展示在你自己的 UI 或未添加到 Apple Pay / Google Pay 的卡上。对于实体卡，本接口更新钱包中展示的卡面，卡片上的印刷图案保持不变。

对于不满足上述范围的卡片，调用 List Card Arts、Set Default Card Art，以及在 Create Card / Update Card 中传 `card_art_id` 仍然会成功 —— `card_art_id` 会被记录到卡上 —— 但视觉效果只会在持卡人满足上述条件后，在对应钱包中显现。

## 默认卡面解析顺序

当 Create Card 或 Update Card 请求未传 `card_art_id` 时，平台按以下顺序解析默认卡面：

1. **账户绑定** —— 显式绑定到发卡账户的卡面。
2. **主账户绑定** —— 发卡账户没有自己的绑定时，回退到其主账户的绑定。
3. **通道系统默认** —— 两个账户都没有绑定时，回退到通道的系统默认卡面（由 UQPAY 配置）。

如果三步都未命中 —— 例如新接入通道既无系统默认也无绑定 —— Create Card 与 Update Card 会返回 [`card_art_not_configured`](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/error-codes)。

## 列出可用卡面

调用 [List Card Arts](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/list-card-arts.md) 在创建或更新卡片前填充卡面选择器。该接口无查询参数；发卡账户由 auth token 或 `x-on-behalf-of` 头解析。

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

**响应：**

```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` 标记 Create Card 未传 `card_art_id` 时使用的卡面。`is_system_config` 标记来自通道系统配置的卡面 —— 通道下所有账户始终可用。

## 设置默认卡面

调用 [Set Default Card Art](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/set-default-card-art.md) 切换 Create Card 未传 `card_art_id` 时使用的默认卡面。新值必须来自 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"
  }'
```

**响应：**

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

把默认值设置为通道系统默认卡面，会清除当前账户级显式默认 —— 账户随后会按上述解析顺序回退到系统默认。

## 用指定卡面签发卡片

在 [Create Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-card.md) 请求中传 `card_art_id`，单卡覆盖默认值：

```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"
  }'
```

卡面会在签发时快照到卡上。之后修改账户默认卡面不会影响已签发卡片的卡面。

## 变更已发卡的卡面

在 [Update Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-card.md) 请求中传 `card_art_id`，变更已签发卡片的卡面：

```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"
  }'
```

卡面变更采用**异步**处理 —— Update Card 返回 `order_status: PROCESSING`，待通道确认后新卡面生效。

> [!WARNING]
>
> 卡面更新支持 `VIRTUAL` 虚拟卡和 `PHYSICAL` 实体卡。`card_status` 与 `processing_status` 必须均为 `ACTIVE`。冻结、注销或待处理状态的卡片会被拒绝，并返回 `card_error`。

## 错误

| `code` | 出现场景 | 处理方式 |
| - | - | - |
| `card_art_not_available` | 传入的 `card_art_id` 不在该账户的可用列表中。 | 调用 **List Card Arts** 查看允许的取值，或省略 `card_art_id` 改用默认值。 |
| `card_art_not_configured` | 通道既无系统默认也无任何绑定。 | 联系你的 UQPAY solutions engineer 为该通道配置卡面。 |
| `card_art_not_supported` | 所选卡产品不支持卡面选择。 | 省略 `card_art_id`，或改用支持卡面的卡产品。 |

完整列表参见 [错误码](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/error-codes.md)。

## 相关阅读

* [Create Card API](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-card.md)
* [Update Card API](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-card.md)
* [List Card Arts API](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/list-card-arts.md)
* [Set Default Card Art API](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/set-default-card-art.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.