Apple Pay 支付设置

一、开通前须知

Apple Pay 支持用户通过面容 ID / 触控 ID 一键付款，适配 iPhone、iPad、Mac 的 Safari 等支持 Apple Pay 的设备与浏览器。

注意事项：

展示范围有限：仅在 H5 / PC 端，且设备与浏览器支持 Apple Pay 时才会出现；微信内、小程序、安卓、Chrome 等环境会自动隐藏，属正常现象。
必须使用 HTTPS，并完成 Apple 对商户域名的验证。
除 Apple 侧配置外，还需对接一家收单机构完成真实扣款（如银联商务 UMS、Adyen、通用自解密网关等）。
测试与生产的切换完全由「收单网关地址」决定，配合对应环境的证书与商户号使用。

二、Apple 开发者侧准备

请使用有效的 Apple Developer 账号完成以下步骤：https://developer.apple.com/

1. 创建 Merchant ID

登录 Apple Developer → Certificates, Identifiers & Profiles → Identifiers。
创建 Merchant IDs，填写 Identifier，形如：merchant.com.yourshop。
记录该 Merchant ID，后续填入商城后台「商户标识 Merchant ID」。

2. 创建并导出证书

在 Merchant ID 详情中分别创建：

Merchant Identity Certificate（商户身份证书）
- 用于与 Apple 服务器建立商户校验会话
- 导出为 .pem：证书文件 + 对应私钥文件
Payment Processing Certificate（支付处理证书）
- 用于解密 Apple Pay 支付 Token
- 真正参与解密的只有「通用自解密（generic）」通道；Adyen / 银联商务由对方解密
- 但当前版本收银台的展示校验要求三份证书均已上传，因此无论选哪家收单机构，都需要上传该证书的私钥（详见第四节第 3 条）

证书转换可参考 Apple 文档，最终后台需要的文件格式为 .pem。

3. 配置支付处理商户名与域名验证

在 Merchant ID 中配置展示用商户名称（与后台「商户展示名」保持一致或接近）。
添加并验证前台域名（PC 商城域名、H5 域名等均需验证）：
- 下载 Apple 提供的验证文件
- 部署到对应域名的：https://您的域名/.well-known/apple-developer-merchantid-domain-association
- 确保该文件可公网 HTTPS 访问，验证通过后再上线

三、收单机构准备

按实际签约的收单通道准备参数（测试/生产勿混用）：

收单机构	适用场景	需要准备
银联商务（ums）	境内为主	网关地址、商户号（mid 或 mid\|tid）、签名密钥、签名算法（SHA256 / SM3）
Adyen	跨境	Checkout 网关（如 https://checkout-test.adyen.com/v71）、merchantAccount、X-API-Key
通用自解密（generic）	自有/定制收单网关	网关基址、收单商户号、HMAC 密钥，并上传支付处理证书私钥

银联商务网关示例：

测试：https://test-api-open.chinaums.com
生产：https://api-mop.chinaums.com

以各收单机构最新商户文档为准。

关于银联商务：银联商务侧的 Apple Pay 产品形态与报文字段随开通产品不同而有差异，接入前请先与银联商务确认实际开通的产品档位，并完成一轮联调验证后再上线。

关于签名算法：选择 SM3 时需服务端具备 SM3 支持（依赖 BouncyCastle），若环境未提供会有明确提示；不确定时优先使用默认的 SHA256，并与银联商务开通的算法保持一致。

四、商城后台配置

1. 是否开启

选择「开启」。与其他支付方式不同，Apple Pay 在开启时会做必填项强校验：Merchant ID、商户展示名、商户身份证书与私钥、支付处理证书私钥、收单网关、收单商户号、收单密钥任一缺失，保存会直接失败并提示「请先完善Apple Pay必填配置」。请先完成下方全部配置，再打开开关并提交。

2. 填写基础参数

商户标识 Merchant ID：如 merchant.com.yourshop
商户展示名：展示在 Apple Pay 支付面板中的名称
国家/地区：收单商户注册地（如中国 CN）
货币：须与收单商户支持币种一致（境内多为 CNY）
支持卡组织：按收单能力勾选；境内请勾选银联，并可按需勾选 Visa、Mastercard 等

3. 上传证书

商户身份证书：上传 apple_pay_merchant_id.pem
商户身份证书私钥：上传 apple_pay_merchant_id_key.pem
支付处理证书私钥：上传支付处理证书对应的私钥

关于第 3 项需要特别说明：从解密职责上讲，只有收单机构选「通用自解密（generic）」时才会真正用到该私钥，Adyen / 银联商务由对方解密。但当前版本收银台在判断「Apple Pay 是否可展示」时，会统一要求三份证书都已上传，未上传该私钥时，即使后台显示已开启，前台收银台也不会出现 Apple Pay，且不会有任何报错。因此请一并上传，避免出现"后台已开启、前台看不到"的情况。

4. 配置收单通道

选择收单机构（通用自解密 / Adyen / 银联商务）。
填写收单网关地址、收单商户号、收单密钥。
若为银联商务，再选择银联签名类型（默认 SHA256，也可选 SM3，须与商户开通一致）。

收单网关地址同时决定了运行环境：填测试网关即走测试环境，填生产网关即走生产环境，系统不另设沙箱开关。

收单商户号、收单密钥若无需更换，保持掩码原样提交即可。

确认无误后点击「提交」。

回调说明（银联商务异步入账时）：

异步通知地址一般为：https://您的PC域名/api/order/pay/notify/ums
请确保可公网访问，并在服务器防火墙/安全组中放行

五、前台验证建议

使用已登录 Apple ID、已添加可用银行卡、已开通 Apple Pay 的 iPhone 真机 Safari，或支持 Apple Pay 的 Mac Safari。
下单进入收银台，确认出现 Apple Pay 选项。
完成一次小额支付，核对订单变为已支付、资金入账与退款流程。
建议先用 Apple Sandbox 测试账号配合收单机构的测试网关联调，验证通过后再更换为生产证书、生产商户号与生产网关地址（系统无沙箱开关，切换环境即切换这三项）。

常见问题

问：收银台看不到 Apple Pay？

答：1. 确认后台已开启，且 Merchant ID、展示名、商户身份证书与私钥、支付处理证书私钥、收单网关/商户号/密钥全部已配齐——其中支付处理证书私钥未上传时前台不展示且无报错，是最容易被忽略的一项（无论选哪家收单机构都需上传）。
2. 确认当前为 H5/PC，且使用 Safari（或系统支持 Apple Pay 的浏览器），设备已开通 Apple Pay。
3. 微信内、小程序、安卓、多数桌面 Chrome 不会显示，属预期行为。
4. 确认域名验证文件已部署且验证通过，站点为 HTTPS。

问：点击支付提示商户校验失败？

答：1. 核对 Merchant ID 与 Apple 后台一致。
2. 核对商户身份证书与私钥是否匹配、是否过期。
3. 确认当前访问域名已在 Apple 完成 Merchant Domain 验证。
4. 确认证书与「收单网关地址」指向的环境一致，测试证书与生产网关混用会导致校验失败。

问：用户已付款，订单仍显示未支付（银联商务）？

答：银联商务为异步入账。请检查 /api/order/pay/notify/ums 是否可达，并在银联侧查看通知是否成功；也可在订单页等待状态刷新或查询支付状态。

问：是否需要上传支付处理证书私钥？

答：需要。从解密职责上只有「通用自解密（generic）」通道会真正使用它，但当前版本收银台的展示校验会统一要求三份证书齐全，因此选 Adyen 或银联商务时也必须上传，否则前台不展示 Apple Pay。

问：后台保存时提示「请先完善Apple Pay必填配置」？

答：说明开启开关时必填项未齐全。请逐项检查 Merchant ID、商户展示名、商户身份证书与私钥、支付处理证书私钥、收单网关地址、收单商户号、收单密钥。其中收单商户号与密钥若显示为掩码且未修改，视为已存在旧值，无需重填。

问：能否同时开启微信、支付宝与 Apple Pay？