卡面 - UQPAY Developer Docs

卡面（card art）是持卡人将 Enhanced 虚拟卡添加到 Apple Pay 后，在 Apple Wallet 中看到的视觉设计。每个卡面都有一个稳定的 card_art_id，在创建或更新卡片时引用它。每张卡只关联一个卡面。你可以：

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

卡面的展示范围

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

持卡人已完成 Enhanced KYC —— 参见 Enhanced KYC 发卡；
持卡人已将虚拟卡添加到 Apple Pay。

卡面不会展示在你自己的 UI、实体卡（其设计在制卡时固化，与本接口无关）、或未添加到 Apple Pay 的卡上。对于不满足上述范围的卡片，调用 List Card Arts、Set Default Card Art，以及在 Create Card / Update Card 中传 card_art_id 仍然会成功 —— card_art_id 会被记录到卡上 —— 但视觉效果只会在持卡人满足上述条件后，在 Apple Wallet 中显现。

默认卡面解析顺序

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

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

如果三步都未命中 —— 例如新接入通道既无系统默认也无绑定 —— Create Card 与 Update Card 会返回 card_art_not_configured。

列出可用卡面

调用 List Card Arts 在创建或更新卡片前填充卡面选择器。该接口无查询参数；发卡账户由 auth token 或 x-on-behalf-of 头解析。

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

响应：

{
  "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 切换 Create Card 未传 card_art_id 时使用的默认卡面。新值必须来自 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"
  }'

响应：

{
  "default_card_art_id": "01KD52BKQWDMFF63R1NNQN7A79",
  "updated_at": "2026-05-20 10:32:18"
}

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

用指定卡面签发卡片

在 Create Card 请求中传 card_art_id，单卡覆盖默认值：

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 请求中传 card_art_id，变更已签发卡片的卡面：

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，待通道确认后新卡面生效。

卡面变更仅适用于以下情况：

VIRTUAL 虚拟卡。实体卡卡面在制卡时固化，无法变更。
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`，或改用支持卡面的卡产品。

完整列表参见错误码。

Documentation Index

​卡面的展示范围

​默认卡面解析顺序

​列出可用卡面

​设置默认卡面

​用指定卡面签发卡片

​变更已发卡的卡面

​错误

​相关阅读