跳转到主要内容
卡面（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 发卡；
  • 持卡人已将虚拟卡添加到 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。

​
列出可用卡面

调用 List Card Arts 在创建或更新卡片前填充卡面选择器。该接口无查询参数；发卡账户由 auth token 或 x-on-behalf-of 头解析。
响应：
is_default 标记 Create Card 未传 card_art_id 时使用的卡面。is_system_config 标记来自通道系统配置的卡面 —— 通道下所有账户始终可用。

​
设置默认卡面

调用 Set Default Card Art 切换 Create Card 未传 card_art_id 时使用的默认卡面。新值必须来自 List Card Arts 返回的卡面列表。
响应：
把默认值设置为通道系统默认卡面，会清除当前账户级显式默认 —— 账户随后会按上述解析顺序回退到系统默认。

​
用指定卡面签发卡片

在 Create Card 请求中传 card_art_id，单卡覆盖默认值：
卡面会在签发时快照到卡上。之后修改账户默认卡面不会影响已签发卡片的卡面。

​
变更已发卡的卡面

在 Update Card 请求中传 card_art_id，变更已签发卡片的卡面：
卡面变更采用异步处理 —— Update Card 返回 order_status: PROCESSING，待通道确认后新卡面生效。
卡面变更仅适用于以下情况：
  • VIRTUAL 虚拟卡。实体卡卡面在制卡时固化，无法变更。
  • card_status 与 processing_status 均为 ACTIVE 的卡片。冻结、注销或待处理状态的卡片会被拒绝。
任一条件不满足时，请求会返回 card_error。

​
错误

完整列表参见 错误码。