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

# Apple Pay 与 Google Pay 绑卡

> 介绍如何在接入机构应用内将 DCS 发行的 Visa 卡一键添加到 Apple Wallet 或 Google Wallet，包括令牌化原理、业务接入流程、绑卡交互时序和相关接口。

## 📄 正文

通过推送绑卡（Push Provisioning），持卡人可以在**您的应用内一键**将 DCS 发行的 Visa 卡添加到 **Apple Wallet（iOS）** 或 **Google Wallet（Android）**，无需在钱包应用中手动输入卡号。作为持牌、自有 BIN 的发卡机构，DCS 负责对接 Apple / Google 的令牌化和绑卡授权。

与只能引导用户跳转的部分能力不同，DeCard 托管**提供了自有的绑卡 REST 接口**（`/card/v1/apple-bind-wallet`、`/card/v*/google-bind-wallet`）：您的应用把钱包下发的加密材料转交 DCS，DCS 调用 Visa 令牌化（Tokenization）服务后，返回钱包所需的配置数据，由您的应用回传给系统钱包完成添加。

> **Apple Pay 新接入建议**：优先使用 [DCSProvisioningSDK](../../sdk/apple-pay/installation)。接入机构后端通过 `POST /card/v1/bind-wallet-ticket` 获取临时绑卡凭证（ticket），SDK 随后完成 PassKit 与 DCS 的交互。本页仍保留底层钱包绑卡 REST 接口，供您查询字段、维护现有直连接入或对接 Google Pay。

> **前置条件**：用户需已完成 KYC 并成功开卡，拿到这张卡的标识（Apple 绑卡与 Google V1 用卡号后四位 `cardMantissa`，Google V2 用 `cardId`）。开卡流程见[申请卡](./issuing-cards)。

### 核心概念：令牌化（Tokenization）

数字钱包通过**令牌化**保护卡片安全——令牌化会把真实卡号（PAN）替换为唯一的数字令牌（token）：

* **一卡一设备一令牌**：每个「卡片 × 设备」组合生成独立令牌，互不影响。
* **端到端保护**：交易时使用令牌替代真实卡号，明文卡号不落到商户/钱包侧。
* **令牌生命周期**（5 阶段）：生成（添加卡时创建）→ 激活（身份验证后启用）→ 使用（交易时替代真实卡号）→ 更新（定期轮换确保安全）→ 删除（移卡时销毁令牌）。

### 两条绑卡路径

| 路径                             | 含义                                  | 是否需要本页 API              |
| :----------------------------- | :---------------------------------- | :---------------------- |
| **手动绑卡（Manual Provisioning）**  | 持卡人在 Apple/Google 钱包应用中手动输入卡信息      | 否，DCS 已默认支持，无需开发（步骤见下文） |
| **应用内绑卡（In-App Provisioning）** | 持卡人在**您的应用内**点击“添加到钱包”，应用将卡片安全添加到钱包 | **是**，需调用本页的绑卡接口        |

本页重点说明**应用内绑卡**——您需要完成接入开发并调用 DCS 绑卡 API。手动绑卡无需开发，由持卡人在钱包应用中自行完成。

#### Apple Pay 手动绑卡（iPhone，3 步）

1. **打开钱包应用**：在 iPhone 上打开「钱包」应用，点击右上角的「+」号。
2. **输入卡片信息**：轻点或手持卡片靠近 iPhone 以添加；或轻点「手动输入卡片详细信息」，按屏幕说明操作。
3. **身份验证**：按提示选择验证方式（短信 / 邮件），输入验证码完成认证。

#### Google Pay 手动绑卡（Android，7 步）

1. **打开 Google 钱包应用**：持卡人打开 Google 钱包应用，**必须登录其 Google 账户**才能启用移动支付。
2. **开始添加流程**：持卡人点击「添加到钱包」开始手动绑卡。
3. **选择支付卡**：如出现提示，持卡人选择「支付卡」。
4. **手动输入卡片信息**：持卡人选择「或手动输入详细信息」，**手输卡号、有效期和 CVV**。
5. **同意条款**：持卡人**查看并同意条款和条件**。
6. **身份验证**：DCS 通过短信或电子邮件下发**验证码**，用于身份验证。
7. **完成配置**：持卡人输入验证码，成功后在 Google 钱包应用内收到确认。

> 具体步骤可能因手机型号、软件版本与钱包应用界面更新而略有差异，如有疑问请联系 DCS 团队。

### 四方角色

| 角色                                     | 承担方            | 职责                                         |
| :------------------------------------- | :------------- | :----------------------------------------- |
| 接入机构应用                                 | 您              | 展示“添加到 Apple/Google Pay”按钮、集成钱包 SDK、传递加密材料 |
| Apple Pay 与 Google Pay API             | Apple / Google | 执行令牌化与钱包配置                                 |
| DCS 绑卡服务                               | DCS            | 调用 Visa 令牌化、返回钱包所需配置数据（本页 API）             |
| BIN Sponsor（Apple 侧）/ Issuer（Google 侧） | DCS            | 以发卡机构身份向 Apple/Google 申请配置授权               |

> Apple 侧 DCS 角色为 **BIN Sponsor**、合作方为 **Program Manager**；Google 侧 DCS 角色为 **Issuer**、合作方为 **Program Manager**。

***

## 业务接入流程（上线前一次性）

启用应用内绑卡前，您需要与 DCS、Apple 或 Google 完成一次性的授权与认证。Apple 与 Google 的接入流程不同：

### Apple Pay 接入

| 步骤               | 内容                                                                                                                 |
| :--------------- | :----------------------------------------------------------------------------------------------------------------- |
| ① 角色确认           | 合作方 = Program Manager；DCS = BIN Sponsor                                                                            |
| ② Partner Hub 入驻 | DCS 在 Partner Hub 将合作方设为 Program Manager；合作方签署 NDA 与 Program Manager 协议；DCS 签署与 Apple 的补充协议（Addendum）              |
| ③ 技术集成           | 手动绑卡已由 DCS 支持；Apple Pay 新接入由合作方集成 **DCSProvisioningSDK**，后端获取临时绑卡凭证（ticket），SDK 调用 DCS / Visa 完成绑卡；既有直连接入可继续使用本页接口 |
| ④ 实验室验证          | 每个 Program Manager 须单独通过 Apple 的 **Limited Labs Certification**（需提前预约，约 **2–3 周**）                                 |
| ⑤ 应用上线           | 实验室验证通过、Partner Hub 各步审核完成后，合作方提交应用到商店审核上线                                                                         |

### Google Pay 接入

| 步骤                      | 内容                                                                                                                                     |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| ① 角色确认                  | DCS = Issuer；合作方 = Program Manager                                                                                                     |
| ② Google Wallet Console | 签署 NDA；合作方在 Issuer documentation access form 注册；填写并提交 **Push Provisioning API Access**（公司/应用信息、SDK 调用权限）；确保应用已加入 Google Wallet Console |
| ③ 技术集成                  | 手动绑卡已由 DCS 支持；应用内绑卡由合作方集成 **Google Pay SDK**，调用本页绑卡接口，在应用内提供“添加至 Google Pay”入口                                                         |
| ④ UI/UX 审核              | 按 Google 要求提交 UX/Branding Review                                                                                                       |
| ⑤ Field Testing         | 上线前完成 Google 要求的现场测试并满足 Exit Criteria                                                                                                  |
| ⑥ 应用上线                  | 合作方提交 Launch Approval Form 并勾选 "Program Manager"，再提交应用到 Google Play 审核                                                                 |

> 详尽的厂商侧逐屏操作以 Apple / Google 官方发卡机构文档为准，本页不复制其截图。更多接入细节请联系 DCS 团队。

***

## 应用内绑卡流程

接入完成后，持卡人每次在应用内点击“添加到钱包”，系统都会按下图交互。下图以 Apple 为例；Google 的流程相同，仅请求和响应字段不同。

> 下图展示底层直连时序。使用 DCSProvisioningSDK 时，应用只需把绑卡凭证与卡片参数交给 SDK，SDK 会处理 PassKit 设备数据与 DCS 之间的交换；见[实现指南](../../sdk/apple-pay/implementation)。

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-push-provisioning-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=942b33ba847d992f2a83a1a148e58ec4" alt="应用内绑卡交互时序图" width="800" height="752" data-path="imgs/diagrams/va-push-provisioning-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-push-provisioning-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=b171d9f00a4c3c723d1e935f1e996c15" alt="应用内绑卡交互时序图" width="800" height="752" data-path="imgs/diagrams/va-push-provisioning-dark.svg" />
</Frame>

Apple 应用内绑卡的加密流程分为 9 步：① 应用启动绑卡 → ② 钱包向 Apple 请求证书与随机数 → ③ Apple 返回证书与随机数 → ④ 钱包把证书、随机数及其签名回传应用 → ⑤ 应用转交 DCS 绑卡服务 → ⑥ DCS 生成临时密钥对、加密支付数据和 OTP，并返回加密数据与临时公钥 → ⑦ 应用把加密数据、临时公钥和加密 OTP 发送给钱包 → ⑧ 钱包向 Apple 验证绑卡请求 → ⑨ Apple 与支付网络运营商（PNO）完成绑卡。

Apple Pay 应用内绑卡（In-App Provisioning）加密流程图：

<Frame>
  <img src="https://mintcdn.com/dcs-0bf7a937/U5My61eeN1_eDSDM/imgs/decard-managed/digitalWalletApplePay-inProvisioningFlow.png?fit=max&auto=format&n=U5My61eeN1_eDSDM&q=85&s=404c6a9ae2b43da45ae26ce0a6ddce98" alt="Apple Pay 应用内绑卡加密流程图" width="1870" height="658" data-path="imgs/decard-managed/digitalWalletApplePay-inProvisioningFlow.png" />
</Frame>

***

## 绑卡 API

Apple 绑卡接口为 `POST /card/v1/apple-bind-wallet`（以卡号后四位 `cardMantissa` 定位卡片）。Google 绑卡提供 **V1 / V2** 两个版本，**新接入统一使用 V2**（以 `cardId` 精确定位卡片）。

| 平台     | 版本         | 接口                                 | 定位卡片字段         |
| :----- | :--------- | :--------------------------------- | :------------- |
| Apple  | V1         | `POST /card/v1/apple-bind-wallet`  | `cardMantissa` |
| Google | **V2（推荐）** | `POST /card/v2/google-bind-wallet` | `cardId`       |
| Google | V1         | `POST /card/v1/google-bind-wallet` | `cardMantissa` |

> **Google V2 与 V1 的唯一差异是定位卡片的字段**：V2 以 `cardId` 替代 `cardMantissa` 定位卡片。`externalUserId` 在两版均必填。其余字段一致。

### Apple Pay 绑卡

#### 请求字段

| 字段                        | 类型        | 必填 | 说明                  |
| :------------------------ | :-------- | :- | :------------------ |
| `externalUserId`          | string    | 是  | 用户 ID               |
| `cardMantissa`            | string    | 可选 | 卡号后四位               |
| `applePublicCertificates` | string\[] | 是  | Apple 公钥证书列表（由钱包下发） |
| `appleNonce`              | string    | 是  | Apple 随机数（nonce）    |
| `appleNonceSignature`     | string    | 是  | Apple 随机数签名         |

> 必填字段为 `externalUserId` / `applePublicCertificates` / `appleNonce` / `appleNonceSignature`；`cardMantissa` 可选。

#### 请求示例（已脱敏）

```bash theme={null}
curl -X POST "{{dicard-server}}/card/v1/apple-bind-wallet" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "<external-user-id>",
    "cardMantissa": "<last-4>",
    "applePublicCertificates": ["<apple-public-cert>"],
    "appleNonce": "<apple-nonce>",
    "appleNonceSignature": "<apple-nonce-signature>"
  }'
```

#### 响应

成功返回统一响应结构 `{ code, message, messageDetail, data }`，成功时 `code = SYS_SUCCESS`。`data` 为 Apple Wallet 完成令牌化所需的配置数据：

| `data` 字段            | 类型 / 规格                  | 说明                                                    |
| :------------------- | :----------------------- | :---------------------------------------------------- |
| `encryptedPassData`  | string（0–8192 字符，base64） | 加密的认证数据（含加密后的 PAN、有效期、时间戳）                            |
| `activationData`     | string（0–8192 字符，base64） | 激活数据（含加密的 nonce、nonceSignature、authCode）              |
| `ephemeralPublicKey` | string（0–8192 字符，base64） | 创建 MBPAD 加密信息时生成的 `VISA.ECC.ePK`，P-256 曲线、非压缩格式的 EC 点 |
| `vCardID`            | string（42 字符）            | Visa 定义的卡片唯一 ID，用于生成配置卡数据                             |

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": "",
  "messageDetail": null,
  "data": {
    "encryptedPassData": "<base64>",
    "activationData": "<base64>",
    "ephemeralPublicKey": "<base64>",
    "vCardID": "<42-char-id>"
  }
}
```

### Google Pay 绑卡

#### 请求字段

| 字段                 | 类型     | 必填（V2 / V1）   | 说明                                |
| :----------------- | :----- | :------------ | :-------------------------------- |
| `externalUserId`   | string | 是 / 是         | 用户 ID                             |
| `cardId`           | string | 是 /（V1 无此字段）  | 卡 ID（**仅 V2**）                    |
| `cardMantissa`     | string | （V2 无此字段）/ 可选 | 卡号后四位（**仅 V1**）                   |
| `clientCustomerId` | string | 可选 / 可选       | 用户的 Google 钱包账户 ID（2–36 字符）       |
| `deviceId`         | string | 可选 / 可选       | 用户的 Android 设备 ID，设备唯一标识（2–24 字符） |

> Google V2 的必填字段仅 `externalUserId` / `cardId`；`clientCustomerId` / `deviceId` 均为可选。V1 的必填字段仅 `externalUserId`。

#### 请求示例（V2，已脱敏）

```bash theme={null}
curl -X POST "{{dicard-server}}/card/v2/google-bind-wallet" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "<external-user-id>",
    "cardId": "<card-id>",
    "clientCustomerId": "<google-wallet-account-id>",
    "deviceId": "<android-device-id>"
  }'
```

#### 响应

成功时 `code = SYS_SUCCESS`，`data` 为 Google Pay 令牌化所需数据：

| `data` 字段           | 类型 / 规格       | 说明                                        |
| :------------------ | :------------ | :---------------------------------------- |
| `last4`             | string（4 字符）  | 卡号后四位                                     |
| `opaquePaymentCard` | string        | Google Pay 令牌化所需的不透明卡数据（opaque card data） |
| `vCardID`           | string（42 字符） | Visa 定义的卡片唯一 ID                           |

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": "",
  "messageDetail": null,
  "data": {
    "last4": "<last-4>",
    "opaquePaymentCard": "<opaque-payment-card>",
    "vCardID": "<42-char-id>"
  }
}
```

<Warning>
  所有示例值均为占位符。**切勿**在请求或日志中写入真实的 `externalUserId`、`cardId`、`cardMantissa`、加密材料、API Key/Secret 或任何持卡人个人信息。

  **鉴权**：上例为聚焦业务字段省略了鉴权头，实际调用必须携带 `X-DAPI-API-KEY` / `X-DAPI-SIGN` / `X-DAPI-TIMESTAMP` / `X-DAPI-NONCE`（HMAC-SHA256 签名），规则见[鉴权指南](../../integration-resources/overview)。
</Warning>

***

## 错误处理

绑卡前卡片必须处于**正常可用状态**：已激活、未冻结、未失效。卡状态不正常时先完成激活或解除限制，再发起绑卡。

| 情况                        | 处理建议                                                                                          |
| :------------------------ | :-------------------------------------------------------------------------------------------- |
| 响应 `code` 非 `SYS_SUCCESS` | 按 `message` 提示排查请求参数（`cardId` / `externalUserId` 是否有效、卡是否已激活、加密材料是否完整）                        |
| 钱包侧令牌化失败                  | Apple/Google 钱包内置风控引擎可能拦截绑卡（短时间多次添加、设备被标记、设备与卡地区不匹配等）；建议引导用户**间隔 24–48 小时**后重试，DCS 无法覆盖钱包风控决策 |
| Apple Pay 在用户所在地区不可用      | 钱包侧会报 iOS 错误，DCS 无法绕过 Apple 的地区限制                                                             |

## 测试说明

* Push Provisioning **必须用生产卡测试**——Visa 不提供沙盒令牌化卡片，完整绑卡流程无法在沙盒环境验证。
* iOS 应用须通过 **TestFlight** 安装测试；直接从 Xcode 运行会导致绑卡失败。

> 当前绑卡成功或失败**不会**额外回传 Webhook 事件；接入机构应以本次绑卡 API 与 Apple/Google Wallet 返回结果为准。若需要异步绑卡事件，需要新增系统能力。

## 下一步

* [Apple Pay SDK 安装](../../sdk/apple-pay/installation)——引入 DCSProvisioningSDK 并配置权限声明、App Group 与卡产品配置
* [实现指南](../../sdk/apple-pay/implementation)——获取绑卡凭证并发起应用内绑卡
* [钱包扩展指南](../../sdk/apple-pay/wallet-extensions)——在 Apple Wallet 内提供绑卡入口
* [申请卡](./issuing-cards)——先开卡拿到 `cardId` / `cardMantissa`
* [卡管理 · 概述](./overview)——冻结/解冻、换卡、状态机
* [管理卡片 PIN](./managing-a-cards-pin)——同属卡片管理，PIN 走引导页
* [Webhook 与 WebSocket 实时通知](../../integration-resources/webhook-websocket)——其他卡片与交易事件；当前不含绑卡事件