/axiom-payments

name: axiom-payments
description: Use when accepting ANY real-world payment — Apple Pay, Wallet passes, Tap to Pay, Orders in Wallet. NOT in-app purchase / digital content (use axiom-integration). Covers entitlements, certs, signing, App Review payment rules.
license: MIT

Real-World Payments (Apple Pay / Wallet / Tap to Pay)

**You MUST use this skill when accepting ANY real-world payment — physical goods, services, donations, ticketing, loyalty cards, contactless card-present, or post-purchase order tracking. NOT for in-app purchase or digital content.**

When to Use

Use this skill when you encounter:

• Adding Apple Pay to an iOS / iPadOS / macOS / Catalyst / visionOS / watchOS app
• Adding Apple Pay to a website (Apple Pay JS or W3C Payment Request API)
• Building Wallet passes (boarding passes, event tickets, coupons, loyalty cards, store cards)
• Accepting contactless card payments on iPhone (Tap to Pay on iPhone / ProximityReader)
• Surfacing post-purchase order tracking in Wallet (Orders in Wallet, FinanceKitUI add-order helpers)
• Issuer or bank card provisioning into Wallet (issuer extensions)
• Apple Pay merchant ID, processing certificate, or merchant identity certificate setup
• Pass Type ID or Order Type ID certificates and PKCS #7 signing chains
• Tap to Pay managed entitlement (`com.apple.developer.proximity-reader.payment.acceptance`)
• App Review rejections that mention payments, IAP, Apple Pay, Wallet, or Acceptable Use Guidelines
• Domain verification for Apple Pay on the web (`.well-known/apple-developer-merchantid-domain-association.txt`)
• Sandbox testing with Apple Pay sandbox cards or sandbox tester accounts

When NOT to Use

| Issue | Correct Skill | Why NOT axiom-payments | |-------|---------------|------------------------| | In-app purchase, subscriptions for digital content | **axiom-integration** | StoreKit 2 / digital goods boundary; see `axiom-integration (skills/in-app-purchases.md)` | | Generic NFC tag reads (Core NFC, non-Wallet) | **axiom-integration** | Different framework; PassKit NFC is Wallet-specific | | Code signing / provisioning fundamentals | **axiom-security** | Code signing is generic; payment certs are *added* to that flow | | App Store rejection workflow & appeals | **axiom-shipping** | Rejection workflow lives there; payment-specific rejection patterns route from there into here | | HIG cross-cutting design guidance | **axiom-design** | Apple Pay / Wallet HIG specifics live here, but design overview lives in axiom-design | | Consumer banking surface (FinanceKit) | *Out of scope* | This suite uses FinanceKitUI only for Orders. Account aggregation / transaction queries are not covered. | | PKSecureElementPass, transit cards, car keys | *Out of scope* | Issuer-controlled, not relevant to merchant developers |

Quick Reference

| Symptom / Task | Reference | |----------------|-----------| | Should this be Apple Pay or IAP? | See `skills/apple-pay-vs-iap.md` | | Selling physical goods, services, or donations | See `skills/apple-pay-vs-iap.md` | | App was rejected for using IAP for physical goods | See `skills/apple-pay-vs-iap.md` | | Native Apple Pay (iOS / iPadOS / macOS / Catalyst / visionOS / watchOS) | See `skills/apple-pay.md` | | PassKit / PKPaymentRequest API surface | See `skills/apple-pay-ref.md` | | Apple Pay on the web (Apple Pay JS or Payment Request API) | See `skills/apple-pay-web.md` | | Web ApplePaySession / Payment Request API surface | See `skills/apple-pay-web-ref.md` | | Domain verification, merchant identity cert, third-party browser support | See `skills/apple-pay-web.md` | | Tap to Pay on iPhone (ProximityReader) | See `skills/tap-to-pay.md` | | ProximityReader / PaymentCardReader API surface | See `skills/tap-to-pay-ref.md` | | Tap to Pay entitlement stuck in "Submitted" | See `skills/tap-to-pay.md` | | Wallet passes (boarding, event ticket, coupon, loyalty, store card) | See `skills/wallet-passes.md` | | pass.json schema, semantic tags, barcodes, NFC payloads | See `skills/wallet-passes-ref.md` | | Poster generic style, featured actions, new barcode types `OS27` | See `skills/wallet-passes-ref.md` | | Pass Designer app, Pass Builder server package | See `skills/wallet-passes-ref.md` | | Customer engagement on a paired device (CustomerEngagementSession) `OS27` | See `skills/tap-to-pay-ref.md` | | Pass signing, manifest hashing, PKCS #7 | See `skills/wallet-passes.md` | | Pass updates not arriving (web service / APNs) | See `skills/wallet-passes.md` | | Orders in Wallet, signed order packages, fulfillment status | See `skills/wallet-orders.md` | | Issuer / bank card provisioning extensions | See `skills/wallet-extensions-ref.md` | | "No payment sheet appears" / merchant validation 503 / pass won't import | See `skills/payments-diag.md` | | Sandbox testing failures, prod-vs-sandbox cert mismatch | See `skills/payments-diag.md` | | Apple Pay button vs Apple Pay Mark confusion | See `skills/apple-pay.md` | | App Review rejection for Apple Pay / Wallet / Tap to Pay | See `skills/payments-diag.md` |

Decision Tree

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"]