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

# 卡面

> 选择 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`。

<h2 id="where-card-art-appears">
  卡面的展示范围
</h2>

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

* 持卡人已完成 **Enhanced KYC** —— 参见 [Enhanced KYC 发卡](/zh/card-issuance/v1.6/guide/enhanced-kyc-card-issuance)；
* 持卡人已将虚拟卡添加到 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` 会被记录到卡上 —— 但视觉效果只会在持卡人满足上述条件后，在对应钱包中显现。

<h2 id="default-resolution-order">
  默认卡面解析顺序
</h2>

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

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

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

<h2 id="list-available-card-arts">
  列出可用卡面
</h2>

调用 [List Card Arts](/zh/card-issuance/v1.6/api-reference/list-card-arts) 在创建或更新卡片前填充卡面选择器。该接口无查询参数；发卡账户由 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` 标记来自通道系统配置的卡面 —— 通道下所有账户始终可用。

<h2 id="set-the-default-card-art">
  设置默认卡面
</h2>

调用 [Set Default Card Art](/zh/card-issuance/v1.6/api-reference/set-default-card-art) 切换 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"
}
```

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

<h2 id="issue-a-card-with-a-specific-card-art">
  用指定卡面签发卡片
</h2>

在 [Create Card](/zh/card-issuance/v1.6/api-reference/create-card) 请求中传 `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"
  }'
```

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

<h2 id="change-the-card-art-on-an-existing-card">
  变更已发卡的卡面
</h2>

在 [Update Card](/zh/card-issuance/v1.6/api-reference/update-card) 请求中传 `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` 虚拟卡。实体卡卡面在制卡时固化，无法变更。
  * `card_status` 与 `processing_status` 均为 `ACTIVE` 的卡片。冻结、注销或待处理状态的卡片会被拒绝。

  任一条件不满足时，请求会返回 `card_error`。
</Warning>

<h2 id="errors">
  错误
</h2>

| `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`，或改用支持卡面的卡产品。                          |

完整列表参见 [错误码](/zh/card-issuance/v1.6/guide/error-codes)。

<h2 id="related">
  相关阅读
</h2>

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