iOS 应用需要接入 Apple Pay…

适用于在 iOS 26+/Swift 6.3 应用中使用 Apple Pay 售卖实体商品、线下服务、捐赠或符合条件的订阅，并向 Wallet 发放、审核、替换和管理 .pkpass 票券。

适用场景

解决思路

1. 在 Xcode 中启用 Apple Pay capability。
2. 在 Apple Developer portal 创建 Merchant ID，格式如 merchant.com.example.app。
3. 为 Merchant ID 生成并安装 Payment Processing Certificate。
4. 将 merchant ID 添加到 entitlements。
5. 展示 Apple Pay UI 前，始终验证设备可支付：先 guard PKPaymentAuthorizationController.canMakePayments()，再用 PKPaymentAuthorizationController.canMakePayments(usingNetworks: [.visa, .masterCard, .amex, .discover], capabilities: .threeDSecure) 检查用户是否有支持网络的卡片。
6. 若使用 canMakePayments(usingNetworks:capabilities:) 检查活跃卡，按 Apple HIG 应在该处把 Apple Pay 作为主要、醒目的支付选项。
7. 高级 Apple Pay 流程中，一个 PKPaymentRequest 只能设置一种可选高级请求类型：recurring、automatic reload、deferred、Apple Pay Later availability 或 multi-token contexts；若结账需要多于一种模式，使用单独的 payment request。
8. SwiftUI 中使用内置 PayWithApplePayButton 视图；任何标为 Apple Pay 的控件都使用 Apple 提供的按钮 API，自定义按钮不得包含 Apple Pay logo 或 Apple Pay 文本。示例：PayWithApplePayButton(.buy) { startPayment() }，配 .payWithApplePayButtonStyle(.black) 和 .frame(height: 48)。
9. UIKit 中使用 PKPaymentButton，例如 PKPaymentButton(paymentButtonType: .buy, paymentButtonStyle: .black)，设置 cornerRadius 并 addTarget。
10. Apple Pay 按钮类型可用 .plain、.buy、.setUp、.inStore、.donate、.checkout、.continue、.book、.subscribe、.reload、.addMoney、.topUp、.order、.rent、.support、.contribute、.tip。
11. 构建 PKPaymentRequest，设置 merchantIdentifier、countryCode、currencyCode、supportedNetworks、merchantCapabilities，并用 NSDecimalNumber（不是 Double）填写金额。
12. 设置 paymentSummaryItems，最后一项作为总额，其 label 显示在支付表的 Pay 行，通常用商户显示名。示例：PKPaymentSummaryItem(label: Widget, amount: NSDecimalNumber(string: 9.99))、Shipping 4.99、My Store 14.98。
13. 只请求定价、履约或合法处理订单所需的联系字段；复杂所需产品选择、可选备注、逐项配送地址和取货地点应在 Apple Pay 按钮前收集，因为支付表无法准确收集。
14. 配置 requiredShippingContactFields 和 requiredBillingContactFields，例如 requiredShippingContactFields = [.postalAddress, .emailAddress, .name]、requiredBillingContactFields = [.postalAddress]。
15. 创建 PKShippingMethod，设置 label、amount、identifier、detail；放入 request.shippingMethods；设置 request.shippingType 为 .shipping、.delivery、.storePickup 或 .servicePickup。
16. 支持网络常量：.visa、.masterCard、.amex、.discover、.chinaUnionPay、.JCB、.maestro、.electron、.interac。运行时用 PKPaymentRequest.availableNetworks() 查询可用网络。
17. 用 PKPaymentAuthorizationController 呈现支付表，SwiftUI 和 UIKit 均可用且无需 view controller；其 delegate 是 weak，必须在 sheet 生命周期内 retain controller。
18. 在 startPayment 中创建 PKPaymentAuthorizationController(paymentRequest:)，赋给属性、设置 delegate、调用 present；若 presented 为 false，清空 controller。
19. 实现 PKPaymentAuthorizationControllerDelegate，在 didAuthorizePayment 中处理 token：将 payment.token.paymentData 发送到支付处理器，绝不在客户端解码 token；用 paymentService.process(payment.token)，成功返回 PKPaymentAuthorizationResult(status: .success, errors: nil)，失败返回 .failure 并带 errors。
20. 实现 paymentAuthorizationControllerDidFinish，调用 controller.dismiss 并在完成后清空 retained controller。
21. 实现 didSelectShippingMethod，在配送方式变化时重新计算 items，用 PKPaymentRequestShippingMethodUpdate(paymentSummaryItems: updatedItems) 返回更新。
22. 在授权结果中处理错误状态，包括网络失败、卡被拒等。
23. 添加 Wallet 票券时，加载已签名 .pkpass 数据，先验证设备能添加 passes，再在需要让用户审核时用 PKAddPassesViewController 呈现。PKPass(data:) 需要已签名 pass 数据，可能抛出 invalid-data 或 invalid-signature；不要用裸 try? 隐藏，应显式命名失败。
24. 实现 addPassToWallet(data:)：guard PKAddPassesViewController.canAddPasses() else return；do 创建 try PKPass(data: data)；guard let addController = PKAddPassesViewController(pass: pass) else return；设置 delegate 并 present；catch 时调用 showRecoverablePassError(error)。
25. SwiftUI 用 AddPassToWalletButton 作为 PKAddPassButton 等价实现；检查 PKAddPassesViewController.canAddPasses() 且 try? PKPass(data: passData)，然后 AddPassToWalletButton([pass]) { added in addedToWallet = added }，样式 .addPassToWalletButtonStyle(.blackOutline)，尺寸 .frame(width: 250, height: 50)。
26. 用 PKPassLibrary 检查和管理用户已有的 passes；pass-library 操作用 PKPassLibrary.isPassLibraryAvailable() 检查，但决定设备能否添加 pass 用 PKAddPassesViewController.canAddPasses()。
27. passes() 只返回你的 app 通过 entitlements 可访问的 passes；用 library.containsPass(pass) 检查特定 pass 是否已在 Wallet。
28. 替换已有 pass 时，检查 replacePass(with:) 的 Boolean 结果并处理失败。
29. 构建已签名 pass bundle、更新 web services、使用 replacePass(with:) 时，阅读 references/wallet-passes.md。
30. 不要用 StoreKit 处理实体商品；Apple Pay 用于实体商品、现实世界服务、捐赠和符合条件的 recurring payments，StoreKit 用于虚拟商品、app 功能和数字内容订阅；框架用错会导致 App Review 拒绝。
31. 不要在多处硬编码 merchant ID；集中配置，例如 enum PaymentConfig { static let merchantIdentifier = merchant.com.example.app; static let countryCode = US; static let currencyCode = USD; static let supportedNetworks: [PKPaymentNetwork] = [.visa, .masterCard, .amex] }。
32. 核对 Apple Pay capability 已启用，且 merchant ID 已在 Developer portal 配置。
33. 核对 Payment Processing Certificate 已生成并安装。
34. 核对在显示 Apple Pay 按钮前已检查 canMakePayments(usingNetworks:)。
35. 核对只要检查了活跃卡可用性，Apple Pay 就在相应位置保持醒目。
36. 核对产品选择、可选详情和复杂配送选择在 payment sheet 前收集。
37. 核对 paymentSummaryItems 最后一项是带商户显示名的总额。
38. 核对 payment summary 和 token-context amounts 使用 NSDecimalNumber。
39. 核对 payment token 发送到服务器处理，绝不在客户端解码。
40. 核对 PKPaymentAuthorizationController 在呈现期间被 retain，并在完成后清空。
41. 核对 paymentAuthorizationControllerDidFinish 会 dismiss controller。
42. 核对配送方式变化通过 delegate callback 重新计算总额。
43. 核对虚拟商品/数字内容用 StoreKit，实体商品、服务、捐赠和符合条件的 recurring payments 用 Apple Pay。
44. 核对 Wallet passes 从已签名 .pkpass bundles 加载。
45. 核对 PKPass(data:) 的 invalid-data 和 invalid-signature 失败被显现。
46. 核对 PKPassLibrary.isPassLibraryAvailable() 用于 pass 操作，而不是添加 pass 的能力检查。
47. 核对添加 pass UI 前检查 PKAddPassesViewController.canAddPasses()。
48. 核对替换 pass 时检查 PKPassLibrary.replacePass(with:) Boolean 结果。
49. 核对 Apple Pay 按钮使用系统提供的 PKPaymentButton 或 PayWithApplePayButton。
50. 核对 Add-to-Wallet UI 使用系统提供的 PKAddPassButton、AddPassToWalletButton 或 PKAddPassesViewController。
51. 核对授权结果中处理错误状态，包括网络失败和 declined cards。
52. 扩展模式如 recurring/deferred payments、coupon codes、multi-merchant、pass bundles、pass updates，阅读 references/wallet-passes.md。
53. 参考 PassKit framework、PKPaymentRequest、PKPaymentAuthorizationController、PKPaymentButton、PayWithApplePayButton、AddPassToWalletButton、PKPass、PKAddPassesViewController、PKPassLibrary、PKPaymentNetwork、Apple Pay HIG 等文档链接。

适用边界 · 注意事项

• 不适用于 Android、Web 或非 Apple 平台；PassKit 是 Apple 平台框架。
• 不适合售卖 App 内虚拟商品、数字内容或功能解锁；这些应使用 StoreKit，否则可能被 App Review 拒绝。
• 没有启用 Apple Pay capability、配置 Merchant ID、安装 Payment Processing Certificate 或没有 Apple Developer 账号时，不要接入该流程。