axiom-payments

现实世界支付（Apple Pay / Wallet / Tap to Pay）

接受任何现实世界支付时，你都必须使用此技能——包括实体商品、服务、捐赠、票务、会员卡、非接触式刷卡支付或购买后的订单跟踪。不适用于 App 内购买或数字内容。

适用场景

遇到以下情况时，请使用此技能：

• 在 iOS / iPadOS / macOS / Catalyst / visionOS / watchOS 应用中添加 Apple Pay
• 在网站中添加 Apple Pay（Apple Pay JS 或 W3C Payment Request API）
• 构建 Wallet 卡券（登机牌、活动门票、优惠券、会员卡、商店卡）
• 在 iPhone 上接受非接触式银行卡支付（Tap to Pay on iPhone / ProximityReader）
• 在 Wallet 中展示购买后的订单跟踪信息（Wallet 中的订单、FinanceKitUI 添加订单辅助工具）
• 将发卡机构或银行的银行卡配置到 Wallet 中（发卡机构扩展）
• 设置 Apple Pay 商户 ID、支付处理证书或商户身份凭证
• 设置 Pass Type ID 或 Order Type ID 证书和 PKCS #7 签名链
• 设置 Tap to Pay 托管权限（com.apple.developer.proximity-reader.payment.acceptance）
• App Review 拒绝理由提及支付、IAP、Apple Pay、Wallet 或《可接受使用准则》
• 为 Apple Pay 网页版验证域名（.well-known/apple-developer-merchantid-domain-association.txt）
• 使用 Apple Pay 沙盒银行卡或沙盒测试员账户进行沙盒测试

不适用场景

问题	正确的技能	为何不使用 axiom-payments
App 内购买、数字内容订阅	axiom-integration	StoreKit 2 / 数字商品边界；参见 axiom-integration (skills/in-app-purchases.md)
通用 NFC 标签读取（Core NFC，非 Wallet）	axiom-integration	使用不同的框架；PassKit NFC 专用于 Wallet
代码签名 / 配置基础知识	axiom-security	代码签名是通用流程；支付证书是在该流程中额外添加的
App Store 拒绝处理流程与申诉	axiom-shipping	拒绝处理流程归该技能负责；支付相关的拒绝模式会从该技能转到此处
跨领域的 HIG 设计指南	axiom-design	Apple Pay / Wallet 的 HIG 细节在此处，但设计概述归 axiom-design 负责
消费者银行功能界面（FinanceKit）	不在范围内	本套件仅将 FinanceKitUI 用于订单。此处不涵盖账户汇总 / 交易查询。
PKSecureElementPass、交通卡、车钥匙	不在范围内	由发卡机构控制，与商户开发者无关

快速参考

症状 / 任务	参考
应该使用 Apple Pay 还是 IAP？	参见 skills/apple-pay-vs-iap.md
销售实物商品、服务或接受捐赠	参见 skills/apple-pay-vs-iap.md
App 因使用 IAP 销售实物商品而被拒	参见 skills/apple-pay-vs-iap.md
原生 Apple Pay（iOS / iPadOS / macOS / Catalyst / visionOS / watchOS）	参见 skills/apple-pay.md
PassKit / PKPaymentRequest API 接口	参见 skills/apple-pay-ref.md
网页上的 Apple Pay（Apple Pay JS 或 Payment Request API）	参见 skills/apple-pay-web.md
Web ApplePaySession / Payment Request API 接口	参见 skills/apple-pay-web-ref.md
域名验证、商户身份凭证、第三方浏览器支持	参见 skills/apple-pay-web.md
iPhone 上的 Tap to Pay（ProximityReader）	参见 skills/tap-to-pay.md
ProximityReader / PaymentCardReader API 接口	参见 skills/tap-to-pay-ref.md
Tap to Pay 权限一直停留在 "Submitted"	参见 skills/tap-to-pay.md
Wallet 通行证（登机牌、活动门票、优惠券、会员卡、商店卡）	参见 skills/wallet-passes.md
pass.json 架构、语义标签、条形码、NFC 载荷	参见 skills/wallet-passes-ref.md
海报通用样式、精选操作、新条形码类型 OS27	参见 skills/wallet-passes-ref.md
Pass Designer App、Pass Builder 服务端包	参见 skills/wallet-passes-ref.md
配对设备上的客户互动（CustomerEngagementSession）OS27	参见 skills/tap-to-pay-ref.md
通行证签名、清单哈希、PKCS #7	参见 skills/wallet-passes.md
通行证更新未送达（Web 服务 / APNs）	参见 skills/wallet-passes.md
Wallet 中的订单、已签名订单包、履约状态	参见 skills/wallet-orders.md
发卡机构 / 银行卡开通扩展	参见 skills/wallet-extensions-ref.md
“未显示支付表单” / 商户验证返回 503 / 通行证无法导入	参见 skills/payments-diag.md
沙盒测试失败、生产环境与沙盒凭证不匹配	参见 skills/payments-diag.md
Apple Pay 按钮与 Apple Pay 标记混淆	参见 skills/apple-pay.md
App Review 因 Apple Pay / Wallet / Tap to Pay 而拒绝	参见 skills/payments-diag.md

决策树

digraph payments {
    "Payments question?" [shape=diamond];
    "Apple Pay or IAP?" [shape=diamond];
    "Where is the surface?" [shape=diamond];
    "What kind of pass?" [shape=diamond];
    "Something not working?" [shape=diamond];

    "skills/apple-pay-vs-iap.md" [shape=box];
    "skills/apple-pay.md" [shape=box];
    "skills/apple-pay-web.md" [shape=box];
    "skills/tap-to-pay.md" [shape=box];
    "skills/wallet-passes.md" [shape=box];
    "skills/wallet-orders.md" [shape=box];
    "skills/wallet-extensions-ref.md" [shape=box];
    "skills/payments-diag.md" [shape=box];
    "axiom-integration\n/in-app-purchases.md" [shape=box];

    "Payments question?" -> "Apple Pay or IAP?";
    "Apple Pay or IAP?" -> "skills/apple-pay-vs-iap.md" [label="boundary unclear"];
    "Apple Pay or IAP?" -> "axiom-integration\n/in-app-purchases.md" [label="digital content /\nsubscription for digital"];
    "Apple Pay or IAP?" -> "Where is the surface?" [label="real-world payment"];

    "Where is the surface?" -> "skills/apple-pay.md" [label="native app"];
    "Where is the surface?" -> "skills/apple-pay-web.md" [label="website"];
    "Where is the surface?" -> "skills/tap-to-pay.md" [label="contactless on iPhone"];
    "Where is the surface?" -> "What kind of pass?" [label="pass / order"];
    "Where is the surface?" -> "skills/wallet-extensions-ref.md" [label="card provisioning\n(issuer / bank)"];

    "What kind of pass?" -> "skills/wallet-passes.md" [label="boarding / ticket /\ncoupon / loyalty"];
    "What kind of pass?" -> "skills/wallet-orders.md" [label="post-purchase\norder tracking"];

    "Payments question?" -> "Something not working?";
    "Something not working?" -> "skills/payments-diag.md" [label="yes"];
}

简化路由：

1. 这是数字商品或数字内容订阅吗？→ 改用 axiom-integration/skills/in-app-purchases.md。
2. 销售实物商品 / 服务 / 接受捐赠，或不确定？→ skills/apple-pay-vs-iap.md
3. 原生 Apple Pay（iOS / iPadOS / macOS / Catalyst / visionOS / watchOS）？→ skills/apple-pay.md + skills/apple-pay-ref.md
4. 网页上的 Apple Pay？→ skills/apple-pay-web.md + skills/apple-pay-web-ref.md
5. iPhone 上的 Tap to Pay（ProximityReader）？→ skills/tap-to-pay.md + skills/tap-to-pay-ref.md
6. Wallet 通行证（门票 / 优惠券 / 会员卡 / 商店卡）？→ skills/wallet-passes.md + skills/wallet-passes-ref.md
7. Wallet 中的订单（购买后跟踪）？→ skills/wallet-orders.md
8. 发卡机构 / 银行卡开通？→ skills/wallet-extensions-ref.md
9. 某项功能无法正常工作（未显示表单 / 商户验证失败 / 通行证无法导入 / Tap to Pay 始终无法启用）？→ skills/payments-diag.md

跨套件路由

Apple Pay 与 IAP 的边界（最常见的跨套件问题）：

• 销售实物商品、服务或接受捐赠 → 留在此处（skills/apple-pay-vs-iap.md）
• 销售数字内容、高级 App 功能或数字内容订阅 → 使用 axiom-integration（skills/in-app-purchases.md）
• App 因使用了错误的支付方式而被拒 → skills/apple-pay-vs-iap.md，然后使用 skills/payments-diag.md

支付与 App 审核拒绝：

• 拒绝原因提及第 3.1 / 3.2 条或 Apple Pay AUG → 留在此处（skills/payments-diag.md）查找根本原因；还要调用 axiom-shipping（skills/app-store-diag.md）处理申诉工作流

支付与证书管理：

• 商户身份凭证、Pass Type ID 凭证、Order Type ID 凭证、支付处理凭证——操作规范 → 留在此处
• 通用 Keychain 导出 / .p12 操作 → 还要调用 axiom-security（skills/keychain-ref.md）
• Tap to Pay 托管授权 → 留在此处（skills/tap-to-pay.md）；通用托管能力的思维模型 → axiom-security（skills/code-signing.md）

支付与 Xcode 功能 / 配置文件：

• Xcode 中的 Apple Pay 功能复选框、商户 ID 选择、配置文件中的 Tap to Pay 授权配置 → 还要调用 axiom-build 了解功能 / 配置文件机制；支付相关指导仍留在此处

支付与 HIG：

• Apple Pay 按钮与 Apple Pay 标识、Wallet Pass 设计规范、Tap to Pay 按钮标签 → 留在此处
• 跨领域设计背景 → 还要调用 axiom-design（skills/hig.md）

支付与 Catalyst / macOS：

• Mac 和 Catalyst 上的 Apple Pay（窗口要求、Web 安全模型、静态商户验证 URL）→ 留在此处（skills/apple-pay.md 的 Catalyst 部分）
• 通用 Catalyst 模式 → axiom-macos

支付与 Apple Watch：

• WKInterfacePaymentButton、watchOS 支付代理流程 → 留在此处（skills/apple-pay-ref.md 的 watchOS 部分）
• 通用 watchOS 模式 → axiom-watchos

反合理化

想法	实际情况
“我们销售实体商品，但会用 IAP——集成更容易。”	必定会被 App Review 拒绝（第 3.1.1 / 3.1.3(e) 条）。实体商品、服务和捐赠应使用 Apple Pay。
“我们的应用提供数字内容，但会用 Apple Pay，因为 IAP 费用更高。”	必定会被 App Review 拒绝。数字内容及其订阅必须使用 IAP。
“我只要在网页上嵌入 PSP 的原始银行卡表单——这样更快。”	这违反了《可接受使用指南》中的对等规则。如果你在网页上接受任何其他付款方式，就必须至少同等醒目地提供 Apple Pay。
“Tap to Pay 只需要像其他功能一样勾选一个 capability。”	Tap to Pay 使用通过单独表单申请的受管 entitlement。Xcode capability 申请流程不适用。申请分两步（开发 → 发布）；遭拒或状态停留在“Submitted”都会导致每轮额外延误 1–4 周。
“我们自己来签署钱包凭证——不过就是 zip + sign。”	PKCS #7 分离式签名、清单哈希、WWDR Intermediate 证书、S/MIME 签名时间以及 PEM/DER 格式问题——大多数签名失败都源于从零实现。请使用服务端库。
“Apple Pay 标识不过是个按钮图形。”	该标识表示“接受 Apple Pay”，绝不能做成可点击元素。按钮由 API 提供，用于发起付款。把标识当作按钮使用违反 HIG，也已知会导致转化率下降。
“生产环境的银行卡会和沙盒银行卡一样正常工作。”	按设计，沙盒交易会在履约前被拒绝。生产环境交易需要生产密钥和已激活的证书。发布前，请使用真实设备和真实银行卡进行测试。
“Apple Pay 商户 ID 每年都会过期。”	商户 ID 永不过期。支付处理证书会在 25 个月后过期。这是两回事。
“我可以从浏览器调用商户验证。”	浏览器绝不能调用 paymentSession。该调用只能在服务端使用商户身份验证证书通过双向 TLS 发起。从浏览器调用会泄露证书。
“FinanceKit 能让我们的应用查看用户的银行交易记录。”	不在本套件范围内。本套件不涉及 FinanceKit 的个人银行服务功能，仅使用 FinanceKitUI 提供添加订单的辅助功能。

不在范围内

本套件有意不涉及以下内容：

• 应用内购买（StoreKit 2） — 请使用 axiom-integration/skills/in-app-purchases.md 和 axiom-integration/skills/storekit-ref.md。边界规则见 skills/apple-pay-vs-iap.md。
• FinanceKit 个人银行服务（账户聚合、交易查询）——不在范围内。我们仅使用 FinanceKitUI 提供添加订单的按钮。
• PKSecureElementPass、交通卡、车钥匙——由发行方控制的 Wallet 功能，不属于商户开发者的范畴。
• 轻触以出示 ID（MobileDocumentReader）——使用 ProximityReader 进行身份验证，而非支付。skills/tap-to-pay-ref.md 中有简要交叉引用；如果身份验证 UX 整体有归属范围，则属于 axiom-integration 范畴。
• 通用 NFC 读取（Core NFC）——属于不同框架。PassKit NFC 专用于 Wallet（会员卡 / 非接触式票券 / 登机凭证）。

示例调用

用户：“我的酒店预订应用应该使用 Apple Pay 还是 IAP？” → 参阅 skills/apple-pay-vs-iap.md

用户：“如何在我的 iOS 应用中设置 Apple Pay？” → 参阅 skills/apple-pay.md

用户：“PKPaymentRequest 的结构是什么？” → 参阅 skills/apple-pay-ref.md

用户：“我的网站上的 Apple Pay 按钮在 Chrome 中不显示。” → 参阅 skills/apple-pay-web.md

用户：“域名验证一直失败。” → 参阅 skills/payments-diag.md

用户：“我想在我的销售点应用中添加 iPhone 上的 Tap to Pay。” → 参阅 skills/tap-to-pay.md

用户：“我的 Tap to Pay 权限已提交两周了。” → 参阅 skills/tap-to-pay.md 和 skills/payments-diag.md

用户：“如何为活动门票制作 Wallet 通行证？” → 参阅 skills/wallet-passes.md

用户：“我的 .pkpass 文件无法导入——Wallet 提示文件无效。” → 参阅 skills/payments-diag.md

用户：“我想让订单跟踪信息在通过 Apple Pay 结账后显示在 Wallet 中。” → 参阅 skills/wallet-orders.md

用户：“App Review 因为我的应用使用 IAP 支付餐厅配送费用而拒绝了它。” → 先参阅 skills/apple-pay-vs-iap.md，再参阅 skills/payments-diag.md

用户：“Apple Pay 与应用内购买有何区别？” → 参阅 skills/apple-pay-vs-iap.md

用户：“正在为我们银行的 iOS 应用实现卡片配置。” → 参阅 skills/wallet-extensions-ref.md

资源

WWDC：2020-10662、2021-10092、2022-10041、2023-10114、2024-10108

Tech Talks：111381（网页上的 Apple Pay）、110336（实现 Apple Pay 订单）

MIG：Apple Pay 商户集成指南（2026 版）——本套指南的运营主干，全文均有引用

文档：/passkit、/applepayontheweb、/proximityreader、/walletpasses、/design/human-interface-guidelines/apple-pay、/design/human-interface-guidelines/wallet、/apple-pay/acceptable-use-guidelines-for-websites

App Review：第 3.1 节（应用内购买）、第 3.1.3(e) 节（应用外的商品和服务）、第 3.2 节（其他商业模式问题）、第 4.9 节（Apple Pay）

技能：axiom-integration（in-app-purchases、storekit-ref）、axiom-shipping（app-store-diag、app-review-guidelines）、axiom-security（keychain-ref、code-signing）、axiom-design（hig、hig-ref）、axiom-macos