Apple Pay 与 Google Pay 绑卡 - DCS Technical Documentation

📄 正文

通过推送绑卡（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。接入机构后端通过 POST /card/v1/bind-wallet-ticket 获取临时绑卡凭证（ticket），SDK 随后完成 PassKit 与 DCS 的交互。本页仍保留底层钱包绑卡 REST 接口，供您查询字段、维护现有直连接入或对接 Google Pay。

前置条件：用户需已完成 KYC 并成功开卡，拿到这张卡的标识（Apple 绑卡与 Google V1 用卡号后四位 cardMantissa，Google V2 用 cardId）。开卡流程见申请卡。

核心概念：令牌化（Tokenization）

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

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

两条绑卡路径

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

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

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

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

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

打开 Google 钱包应用：持卡人打开 Google 钱包应用，必须登录其 Google 账户才能启用移动支付。
开始添加流程：持卡人点击「添加到钱包」开始手动绑卡。
选择支付卡：如出现提示，持卡人选择「支付卡」。
手动输入卡片信息：持卡人选择「或手动输入详细信息」，手输卡号、有效期和 CVV。
同意条款：持卡人查看并同意条款和条件。
身份验证：DCS 通过短信或电子邮件下发验证码，用于身份验证。
完成配置：持卡人输入验证码，成功后在 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 之间的交换；见实现指南。

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

绑卡 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 可选。

请求示例（已脱敏）

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，用于生成配置卡数据

{
  "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，已脱敏）

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

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

所有示例值均为占位符。切勿在请求或日志中写入真实的 externalUserId、cardId、cardMantissa、加密材料、API Key/Secret 或任何持卡人个人信息。鉴权：上例为聚焦业务字段省略了鉴权头，实际调用必须携带 X-DAPI-API-KEY / X-DAPI-SIGN / X-DAPI-TIMESTAMP / X-DAPI-NONCE（HMAC-SHA256 签名），规则见鉴权指南。

错误处理

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

情况	处理建议
响应 `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 安装——引入 DCSProvisioningSDK 并配置权限声明、App Group 与卡产品配置
实现指南——获取绑卡凭证并发起应用内绑卡
钱包扩展指南——在 Apple Wallet 内提供绑卡入口
申请卡——先开卡拿到 cardId / cardMantissa
卡管理 · 概述——冻结/解冻、换卡、状态机
管理卡片 PIN——同属卡片管理，PIN 走引导页
Webhook 与 WebSocket 实时通知——其他卡片与交易事件；当前不含绑卡事件

​📄 正文

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

​两条绑卡路径

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

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

​四方角色

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

​Apple Pay 接入

​Google Pay 接入

​应用内绑卡流程

​绑卡 API

​Apple Pay 绑卡

​请求字段

​请求示例（已脱敏）

​响应

​Google Pay 绑卡

​请求字段

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

​响应

​错误处理

​测试说明

​下一步

📄 正文

核心概念：令牌化（Tokenization）

两条绑卡路径

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

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

四方角色

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

Apple Pay 接入

Google Pay 接入

应用内绑卡流程

绑卡 API

Apple Pay 绑卡

请求字段

请求示例（已脱敏）

响应

Google Pay 绑卡

请求字段

请求示例（V2，已脱敏）

响应

错误处理

测试说明

下一步