passkit

PassKit 用于在 iOS 应用中接受 Apple Pay 支付（面向实体商品与服务），并将卡券添加到用户的 Wallet。内容覆盖支付按钮、支付请求、授权、Wallet 卡券与商户配置，目标平台为 Swift 6.3 / iOS 26+。

一、用途 PassKit 主要解决两类需求：一是通过 Apple Pay 完成实体商品或服务的支付；二是向用户的 Wallet 添加卡券（pass）。文档明确指出：Apple Pay（PassKit）用于实体商品和服务，StoreKit 用于数字内容、订阅和应用内购买，使用错误的框架会导致 App Review 被拒。

二、主要能力

1. 展示 Apple Pay 按钮：SwiftUI 使用内置的 PayWithApplePayButton 视图，UIKit 使用 PKPaymentButton。按钮类型包括 .buy、.setUp、.inStore、.donate、.checkout、.book、.subscribe、.reload、.addMoney、.topUp、.order、.rent、.support、.contribute、.tip。
2. 创建支付请求：使用 PKPaymentRequest 配置商户标识、国家代码、货币代码、支持的卡组织网络、商户能力（如 .threeDSecure）以及 paymentSummaryItems。paymentSummaryItems 的最后一项被视为总计，其标签会作为商户名称显示在支付表单上。
3. 请求配送与联系信息：可设置 requiredShippingContactFields、requiredBillingContactFields、shippingMethods（含 identifier 与 detail）以及 shippingType（.shipping、.delivery、.storePickup、.servicePickup）。
4. 展示支付表单：使用 PKPaymentAuthorizationController，在 SwiftUI 和 UIKit 中均可使用，无需视图控制器。
5. 处理支付授权：实现 PKPaymentAuthorizationControllerDelegate，将 payment.token.paymentData 发送给支付处理方，并返回 PKPaymentAuthorizationResult。
6. 处理配送方式变更：通过 didSelectShippingMethod 回调重新计算金额并返回 PKPaymentRequestShippingMethodUpdate。
7. Wallet 卡券：加载 .pkpass 文件并通过 PKAddPassesViewController 展示；也可使用 PKPassLibrary.addPasses 添加卡券，处理 .shouldReviewPasses、.didAddPasses、.didCancelAddPasses 等状态。
8. 查询卡券库：使用 PKPassLibrary 的 containsPass、passes 方法，并在操作前检查 PKPassLibrary.isPassLibraryAvailable()。

三、使用方式

1. 项目配置：在 Xcode 中启用 Apple Pay 能力；在 Apple Developer 门户创建 Merchant ID（格式：merchant.com.example.app）；为该 Merchant ID 生成并安装 Payment Processing Certificate；将 Merchant ID 添加到 entitlements。
2. 可用性检查：在展示 Apple Pay UI 前，先用 PKPaymentAuthorizationController.canMakePayments() 检查设备是否支持，再用 canMakePayments(usingNetworks:capabilities:) 检查用户是否有受支持卡组织的卡片。
3. 支持的卡组织网络包括：.visa、.masterCard、.amex、.discover、.chinaUnionPay、.JCB、.maestro、.electron、.interac，可在运行时通过 PKPaymentRequest.availableNetworks() 查询。
4. 支付流程：创建 PKPaymentRequest → 用 PKPaymentAuthorizationController 展示 → 在 delegate 中处理授权 → 将支付令牌发送到服务器处理（切勿在客户端解码）→ 在 paymentAuthorizationControllerDidFinish 中关闭控制器。

四、适用场景 适用于销售实体商品或服务的 iOS 应用，以及需要向用户 Wallet 添加卡券的应用。

五、限制与常见错误

1. 不要用 StoreKit 销售实体商品，也不要用 Apple Pay 销售数字内容。
2. 不要在多处硬编码 Merchant ID，应集中配置。
3. 不要遗漏 paymentSummaryItems 中的总计行，否则支付表单不显示商户名称或总计。
4. 不要跳过 canMakePayments 检查。
5. 不要在 didAuthorizePayment 中提前关闭控制器，应在 paymentAuthorizationControllerDidFinish 中关闭。
6. 支付令牌必须发送到服务器处理，不能在客户端解码。
7. Wallet 卡券应从已签名的 .pkpass 包加载，并在操作前检查 PKPassLibrary.isPassLibraryAvailable()。
8. 应在授权结果中处理错误状态（网络失败、卡片被拒等）。

六、审查清单 文档提供了一份审查清单，涵盖：Apple Pay 能力与 Merchant ID 配置、Payment Processing Certificate 安装、canMakePayments 检查、总计行、令牌服务器处理、控制器关闭时机、配送方式变更重算、StoreKit 与 Apple Pay 的正确使用、Wallet 卡券加载、卡券库可用性检查、系统提供的支付按钮、错误状态处理。

七、参考 扩展模式（定期支付、优惠码、多商户）见 references/wallet-passes.md。相关框架与类包括：PassKit framework、PKPaymentRequest、PKPaymentAuthorizationController、PKPaymentButton、PKPass、PKAddPassesViewController、PKPassLibrary、PKPaymentNetwork。