@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/passkit-wallet/SKILL.md

@@ -1,490 +1,356 @@
 ---
 name: passkit-wallet
-description: "Integrate Apple Pay payments and Wallet passes using PassKit. Use when adding Apple Pay buttons, creating payment requests, handling payment authorization, adding passes to Wallet, configuring merchant capabilities, managing shipping/contact fields, or working with PKPaymentRequest, PKPaymentAuthorizationController, PKPaymentButton, AddPassToWalletButton, PKPass, PKAddPassesViewController, PKPassLibrary, Wallet pass distribution, or Apple Pay checkout flows for physical goods, real-world services, donations, and eligible recurring payments."
+description: "Apple Pay and Wallet passes with PassKit: Apple Pay buttons, payment requests, authorization flow, merchant capabilities, shipping and contact fields, adding and distributing passes (PKPaymentRequest, PKPaymentButton, PKPaymentAuthorizationController, PKPass, AddPassToWalletButton, PKPassLibrary, PKAddPassesViewController). Use when building Apple Pay checkout for physical goods, real-world services, donations or eligible recurring payments, or adding and updating Wallet passes. Not for digital goods or subscriptions (storekit) or FinanceKit."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# PassKit
+# PassKit: Apple Pay and Wallet
 
-Accept Apple Pay payments for physical goods, real-world services, donations,
-and eligible recurring payments, and add passes to the user's Wallet. Covers
-payment buttons, payment requests, authorization, Wallet passes, and merchant
-configuration. Targets Swift 6.3 / iOS 26+.
+PassKit covers two things: taking Apple Pay payments and putting passes
+(tickets, cards, coupons) into Wallet. Apple Pay is meant for tangible
+products, in-person or real-world services, donations and eligible recurring
+charges.
+Examples assume Swift 6.3 and iOS 26.
 
-For advanced Apple Pay flows, one `PKPaymentRequest` can set only one optional
-advanced request type: recurring, automatic reload, deferred, Apple Pay Later
-availability, or multi-token contexts. Use separate payment requests when a
-checkout needs more than one of those modes.
-
-## Contents
-
-- [Setup](#setup)
-- [Displaying the Apple Pay Button](#displaying-the-apple-pay-button)
-- [Creating a Payment Request](#creating-a-payment-request)
-- [Presenting the Payment Sheet](#presenting-the-payment-sheet)
-- [Handling Payment Authorization](#handling-payment-authorization)
-- [Wallet Passes](#wallet-passes)
-- [Checking Pass Library](#checking-pass-library)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+One rule shapes advanced checkouts: a single `PKPaymentRequest` may carry at
+most one optional advanced type. The candidates are a recurring request, an
+automatic-reload request, a deferred request, the Apple Pay Later setting, and
+multi-token contexts. When a flow
+needs two of them, build two requests.
 
 ## Setup
 
-### Project Configuration
-
-1. Enable the **Apple Pay** capability in Xcode
-2. Create a Merchant ID in the Apple Developer portal (format: `merchant.com.example.app`)
-3. Generate and install a Payment Processing Certificate for your merchant ID
-4. Add the merchant ID to your entitlements
+1. Add the **Apple Pay** capability to the target.
+2. Register a Merchant ID in the developer portal, in the form
+   `merchant.com.yourcompany.store`.
+3. Create the Payment Processing Certificate for that Merchant ID and hand it
+   to your processor or server.
+4. Make sure the Merchant ID is listed in the app's entitlements.
 
-### Availability Check
+### Can this device pay?
 
-Always verify the device can make payments before showing Apple Pay UI. If you
-check for an active card with `canMakePayments(usingNetworks:capabilities:)`,
-Apple's HIG expects Apple Pay to be a primary, prominent payment option wherever
-you use that check.
+Check before any Apple Pay UI appears, in two steps:
 
 ```swift
 import PassKit
 
-func canMakePayments() -> Bool {
-    // Check device supports Apple Pay at all
-    guard PKPaymentAuthorizationController.canMakePayments() else {
-        return false
+enum Checkout {
+    static let merchantID = "merchant.com.yourcompany.store"
+    static let country = "US"
+    static let currency = "USD"
+    static let networks: [PKPaymentNetwork] = [.visa, .masterCard, .amex, .discover]
+
+    static var deviceSupportsApplePay: Bool {
+        PKPaymentAuthorizationController.canMakePayments()
+    }
+
+    static var walletHasUsableCard: Bool {
+        PKPaymentAuthorizationController.canMakePayments(
+            usingNetworks: networks,
+            capabilities: .threeDSecure
+        )
     }
-    // Check user has cards for the networks you support
-    return PKPaymentAuthorizationController.canMakePayments(
-        usingNetworks: [.visa, .masterCard, .amex, .discover],
-        capabilities: .threeDSecure
-    )
 }
 ```
 
-## Displaying the Apple Pay Button
+The first call asks whether the hardware and region support Apple Pay; the
+second whether the user has a card on one of your networks. Keeping merchant
+ID, country, currency and networks in one type also avoids scattering the
+Merchant ID string through the codebase.
+
+The Human Interface Guidelines attach a condition to the second call: an app
+that asks whether the user holds an active card must then present Apple Pay
+as a primary, prominent way to pay.
 
-### SwiftUI
+## The Apple Pay button
 
-Use the built-in `PayWithApplePayButton` view in SwiftUI. Use Apple-provided
-button APIs for any control labeled Apple Pay; custom buttons must not include
-the Apple Pay logo or "Apple Pay" text.
+Anything labelled Apple Pay must be Apple's own button. A custom control may
+not show the Apple Pay mark or the words "Apple Pay".
 
 ```swift
-import SwiftUI
-import PassKit
+struct BasketFooter: View {
+    let startPayment: () -> Void
 
-struct CheckoutView: View {
     var body: some View {
-        PayWithApplePayButton(.buy) {
-            startPayment()
-        }
-        .payWithApplePayButtonStyle(.black)
-        .frame(height: 48)
-        .padding()
+        PayWithApplePayButton(.checkout, action: startPayment)
+            .payWithApplePayButtonStyle(.black)
+            .frame(height: 50)
     }
 }
 ```
 
-### UIKit
-
-Use `PKPaymentButton` for UIKit-based interfaces.
+UIKit uses `PKPaymentButton`:
 
 ```swift
-let button = PKPaymentButton(
-    paymentButtonType: .buy,
-    paymentButtonStyle: .black
-)
-button.cornerRadius = 12
-button.addTarget(self, action: #selector(startPayment), for: .touchUpInside)
+let payButton = PKPaymentButton(paymentButtonType: .checkout, paymentButtonStyle: .black)
+payButton.cornerRadius = 10
+payButton.addTarget(self, action: #selector(payTapped), for: .primaryActionTriggered)
 ```
 
-**Button types:** `.plain`, `.buy`, `.setUp`, `.inStore`, `.donate`,
-`.checkout`, `.continue`, `.book`, `.subscribe`, `.reload`, `.addMoney`,
-`.topUp`, `.order`, `.rent`, `.support`, `.contribute`, `.tip`
+Pick the `PKPaymentButtonType` whose wording fits the action:
 
-## Creating a Payment Request
+| Purpose | Types |
+|---------|-------|
+| Generic or purchase | `.plain`, `.buy`, `.checkout`, `.continue`, `.order` |
+| Setup and in-store | `.setUp`, `.inStore` |
+| Giving | `.donate`, `.contribute`, `.support`, `.tip` |
+| Bookings and plans | `.book`, `.rent`, `.subscribe` |
+| Balances | `.reload`, `.addMoney`, `.topUp` |
 
-Build a `PKPaymentRequest` with your merchant details and the items being purchased.
-PassKit amount APIs take `NSDecimalNumber`, not `Double`.
+## Building the request
 
 ```swift
-func createPaymentRequest() -> PKPaymentRequest {
-    let request = PKPaymentRequest()
-    request.merchantIdentifier = "merchant.com.example.app"
-    request.countryCode = "US"
-    request.currencyCode = "USD"
-    request.supportedNetworks = [.visa, .masterCard, .amex, .discover]
-    request.merchantCapabilities = .threeDSecure
-
-    request.paymentSummaryItems = [
-        PKPaymentSummaryItem(
-            label: "Widget",
-            amount: NSDecimalNumber(string: "9.99")
-        ),
-        PKPaymentSummaryItem(
-            label: "Shipping",
-            amount: NSDecimalNumber(string: "4.99")
-        ),
-        PKPaymentSummaryItem(
-            label: "My Store",
-            amount: NSDecimalNumber(string: "14.98")
-        ) // Total
-    ]
-
-    return request
+func makeRequest(for basket: Basket) -> PKPaymentRequest {
+    let order = PKPaymentRequest()
+    order.merchantIdentifier = Checkout.merchantID
+    order.countryCode = Checkout.country
+    order.currencyCode = Checkout.currency
+    order.supportedNetworks = Checkout.networks
+    order.merchantCapabilities = .threeDSecure
+
+    let goods = PKPaymentSummaryItem(label: "Ceramic Mugs (2)", amount: NSDecimalNumber(string: "36.00"))
+    let tax = PKPaymentSummaryItem(label: "Sales Tax", amount: NSDecimalNumber(string: "2.97"))
+    let total = PKPaymentSummaryItem(label: "Clayworks Studio", amount: goods.amount.adding(tax.amount))
+    order.paymentSummaryItems = [goods, tax, total]
+    return order
 }
 ```
 
-The **last item** in `paymentSummaryItems` is treated as the total and its label
-appears in the Pay line on the payment sheet.
+- Money is `NSDecimalNumber`, built from a string or integer parts. A `Double`
+  literal such as `36.1` is already imprecise before it reaches PassKit.
+- The last summary item is the total. Its label, your business name, is what
+  appears on the Pay line. Leave it out and the sheet shows your last line
+  item there instead.
 
-### Requesting Shipping and Contact Info
+### Shipping and contact details
 
-Request only the contact fields needed to price, fulfill, or legally process the
-order.
-Collect required product choices, optional notes, per-item shipping destinations,
-and pickup locations before the Apple Pay button when the payment sheet cannot
-collect them accurately.
+Ask only for what you need to price, fulfil or legally process the order.
+Anything the sheet cannot collect well (product options, notes, gifts shipped
+to several addresses, a pickup store) belongs on your own screen before the
+Apple Pay button.
 
 ```swift
-request.requiredShippingContactFields = [.postalAddress, .emailAddress, .name]
-request.requiredBillingContactFields = [.postalAddress]
-
-let standard = PKShippingMethod(
-    label: "Standard",
-    amount: NSDecimalNumber(string: "4.99")
-)
-standard.identifier = "standard"
-standard.detail = "5-7 business days"
-
-let express = PKShippingMethod(
-    label: "Express",
-    amount: NSDecimalNumber(string: "9.99")
-)
-express.identifier = "express"
-express.detail = "1-2 business days"
-
-request.shippingMethods = [standard, express]
-
-request.shippingType = .shipping // .delivery, .storePickup, .servicePickup
+order.requiredShippingContactFields = [.postalAddress, .name, .phoneNumber]
+order.requiredBillingContactFields = [.postalAddress]
+
+func delivery(_ id: String, _ title: String, _ price: String, _ eta: String) -> PKShippingMethod {
+    let method = PKShippingMethod(label: title, amount: NSDecimalNumber(string: price))
+    method.identifier = id
+    method.detail = eta
+    return method
+}
+
+order.shippingMethods = [
+    delivery("ground", "Ground", "4.50", "Arrives in 3 to 5 days"),
+    delivery("overnight", "Overnight", "12.00", "Arrives tomorrow"),
+]
+order.shippingType = .shipping
 ```
 
-### Supported Networks
+`shippingType` can be `.shipping`, `.delivery`, `.storePickup` or
+`.servicePickup`.
 
-| Network | Constant |
-|---|---|
-| Visa | `.visa` |
-| Mastercard | `.masterCard` |
-| American Express | `.amex` |
-| Discover | `.discover` |
-| China UnionPay | `.chinaUnionPay` |
-| JCB | `.JCB` |
-| Maestro | `.maestro` |
-| Electron | `.electron` |
-| Interac | `.interac` |
+### Networks
 
-Query available networks at runtime with `PKPaymentRequest.availableNetworks()`.
+`PKPaymentNetwork` constants include `.visa`, `.masterCard`, `.amex`,
+`.discover`, `.chinaUnionPay`, `.JCB`, `.maestro`, `.electron` and `.interac`.
+`PKPaymentRequest.availableNetworks()` reports what the device supports at
+run time.
 
-## Presenting the Payment Sheet
+## Presenting the sheet and authorizing
 
-Use `PKPaymentAuthorizationController` (works in both SwiftUI and UIKit, no view controller needed). The controller's delegate is weak, so retain the controller for the life of the sheet.
+`PKPaymentAuthorizationController` works from SwiftUI and UIKit alike and
+needs no view controller. Because the delegate property is weak, store the
+controller in a property until the sheet has gone. The SDK marks every
+delegate callback as main-actor, so the methods below are plain members of
+the `@MainActor` coordinator. Marking them `nonisolated` would force the
+non-`Sendable` `reply` handlers and shipping methods across actors, which
+Swift 6 rejects.
 
 ```swift
-final class CheckoutCoordinator: NSObject {
-    private var paymentController: PKPaymentAuthorizationController?
-
-    @MainActor
-    func startPayment() {
-        let controller = PKPaymentAuthorizationController(
-            paymentRequest: createPaymentRequest()
-        )
-        paymentController = controller
-        controller.delegate = self
-        controller.present { [weak self] presented in
-            if !presented {
-                self?.paymentController = nil
-            }
+@MainActor
+final class PaymentCoordinator: NSObject, PKPaymentAuthorizationControllerDelegate {
+    private var controller: PKPaymentAuthorizationController?
+    private var basket = Basket()
+
+    func pay() {
+        let sheet = PKPaymentAuthorizationController(paymentRequest: makeRequest(for: basket))
+        sheet.delegate = self
+        controller = sheet
+        Task {
+            if await !sheet.present() { controller = nil }
         }
     }
-}
-```
-
-## Handling Payment Authorization
-
-Implement `PKPaymentAuthorizationControllerDelegate` to process the payment token.
 
-```swift
-extension CheckoutCoordinator: PKPaymentAuthorizationControllerDelegate {
     func paymentAuthorizationController(
-        _ controller: PKPaymentAuthorizationController,
+        _ sheet: PKPaymentAuthorizationController,
         didAuthorizePayment payment: PKPayment,
-        handler completion: @escaping (PKPaymentAuthorizationResult) -> Void
+        handler reply: @escaping (PKPaymentAuthorizationResult) -> Void
     ) {
-        // Send payment.token.paymentData to your payment processor
+        let token = payment.token.paymentData
         Task {
-            do {
-                try await paymentService.process(payment.token)
-                completion(PKPaymentAuthorizationResult(status: .success, errors: nil))
-            } catch {
-                completion(PKPaymentAuthorizationResult(status: .failure, errors: [error]))
-            }
+            let failure = await OrderAPI.charge(token)
+            let status: PKPaymentAuthorizationStatus = failure == nil ? .success : .failure
+            reply(PKPaymentAuthorizationResult(status: status, errors: failure.map { [$0] }))
         }
     }
 
-    func paymentAuthorizationControllerDidFinish(
-        _ controller: PKPaymentAuthorizationController
-    ) {
-        controller.dismiss { [weak self] in
-            self?.paymentController = nil
+    func paymentAuthorizationControllerDidFinish(_ sheet: PKPaymentAuthorizationController) {
+        sheet.dismiss { [weak self] in
+            Task { @MainActor in self?.controller = nil }
         }
     }
-}
-```
-
-### Handling Shipping Changes
 
-```swift
-func paymentAuthorizationController(
-    _ controller: PKPaymentAuthorizationController,
-    didSelectShippingMethod shippingMethod: PKShippingMethod,
-    handler completion: @escaping (PKPaymentRequestShippingMethodUpdate) -> Void
-) {
-    let updatedItems = recalculateItems(with: shippingMethod)
-    let update = PKPaymentRequestShippingMethodUpdate(paymentSummaryItems: updatedItems)
-    completion(update)
+    func paymentAuthorizationController(
+        _ sheet: PKPaymentAuthorizationController,
+        didSelectShippingMethod method: PKShippingMethod,
+        handler reply: @escaping (PKPaymentRequestShippingMethodUpdate) -> Void
+    ) {
+        basket.shipping = method
+        let items = makeRequest(for: basket).paymentSummaryItems
+        reply(PKPaymentRequestShippingMethodUpdate(paymentSummaryItems: items))
+    }
 }
 ```
 
-## Wallet Passes
-
-### Adding a Pass to Wallet
+- The payment token goes to your server or processor as opaque data. Never
+  decode it in the app.
+- Report declines and network failures through the result's status and
+  errors so the sheet can show them.
+- Dismiss only in `paymentAuthorizationControllerDidFinish(_:)`. Dismissing
+  from `didAuthorizePayment` leaves a blank sheet.
+- Every shipping-method change recalculates the summary items, total included.
 
-Load signed `.pkpass` data, verify the device can add passes, then present
-`PKAddPassesViewController` when you want the user to review the pass before
-adding it. `PKPass(data:)` expects signed pass data and can throw invalid-data
-or invalid-signature errors. Name `invalid-data` and `invalid-signature`
-failures explicitly instead of hiding them behind a bare `try?` in review
-guidance.
+Recurring, deferred, coupon and multi-merchant requests, plus a full SwiftUI
+checkout screen, are in the [Wallet and advanced payments reference](references/wallet-passes.md).
 
-```swift
-func addPassToWallet(data: Data) {
-    guard PKAddPassesViewController.canAddPasses() else {
-        return
-    }
-
-    do {
-        let pass = try PKPass(data: data)
-        guard let addController = PKAddPassesViewController(pass: pass) else {
-            return
-        }
-        addController.delegate = self
-        present(addController, animated: true)
-    } catch {
-        // Signed pass data is invalid or the signature cannot be validated.
-        showRecoverablePassError(error)
-    }
-}
-```
+## Wallet passes
 
-### SwiftUI Wallet Button
+### Adding a pass
 
-Use `AddPassToWalletButton` as the SwiftUI equivalent to `PKAddPassButton`.
+Passes arrive as signed `.pkpass` data, usually from your server.
+`PKPass(data:)` throws when the data is not a valid pass or when its signature
+does not verify. Name those two failures in your error handling and show the
+user something recoverable; a bare `try?` hides both.
 
 ```swift
-import PassKit
-import SwiftUI
-
-struct AddPassButton: View {
-    let passData: Data
-    @State private var addedToWallet = false
-
-    var body: some View {
-        if PKAddPassesViewController.canAddPasses(),
-           let pass = try? PKPass(data: passData) {
-            AddPassToWalletButton([pass]) { added in
-                addedToWallet = added
-            }
-            .addPassToWalletButtonStyle(.blackOutline)
-            .frame(width: 250, height: 50)
+@MainActor
+func offerPass(_ data: Data, from presenter: UIViewController) throws {
+    guard PKAddPassesViewController.canAddPasses() else { throw WalletError.addingUnavailable }
+    let pass: PKPass
+    do {
+        pass = try PKPass(data: data)
+    } catch let error as PKPassKitError {
+        switch error.code {
+        case .invalidSignature: throw WalletError.badSignature
+        case .invalidDataError: throw WalletError.invalidPass
+        default: throw WalletError.unknown(error)
         }
     }
+    guard let sheet = PKAddPassesViewController(pass: pass) else { throw WalletError.invalidPass }
+    sheet.delegate = presenter as? PKAddPassesViewControllerDelegate
+    presenter.present(sheet, animated: true)
 }
 ```
 
-## Checking Pass Library
-
-Use `PKPassLibrary` to inspect and manage passes the user already has. Check
-`PKPassLibrary.isPassLibraryAvailable()` before pass-library operations, but use
-`PKAddPassesViewController.canAddPasses()` to decide whether the device can add
-passes. `passes()` only returns passes your app can access through its
-entitlements. When replacing an existing pass, check the Boolean result from
-`replacePass(with:)` and handle failure. For signed pass bundle construction,
-update web services, and `replacePass(with:)`, read
-[references/wallet-passes.md](references/wallet-passes.md).
-
-```swift
-let library = PKPassLibrary()
-
-// Check if a specific pass is already in Wallet
-let hasPass = library.containsPass(pass)
-
-// Retrieve passes your app can access
-let passes = library.passes()
-
-// Check if pass library is available
-guard PKPassLibrary.isPassLibraryAvailable() else { return }
-```
-
-## Common Mistakes
-
-### DON'T: Use StoreKit for physical goods
-
-Apple Pay (PassKit) is for **physical goods, real-world services, donations, and
-eligible recurring payments**. StoreKit is for virtual goods, app features, and
-digital-content subscriptions. Using the wrong framework leads to App Review
-rejection.
+`PKAddPassesViewController` shows the pass so the user can confirm it first.
 
-```swift
-// WRONG: Using StoreKit to sell a physical product
-let product = try await Product.products(for: ["com.example.tshirt"])
-
-// CORRECT: Use Apple Pay for physical goods
-let request = PKPaymentRequest()
-request.paymentSummaryItems = [
-    PKPaymentSummaryItem(label: "T-Shirt", amount: NSDecimalNumber(string: "29.99")),
-    PKPaymentSummaryItem(label: "My Store", amount: NSDecimalNumber(string: "29.99"))
-]
-```
+### SwiftUI button
 
-### DON'T: Hardcode merchant ID in multiple places
+`AddPassToWalletButton` is the SwiftUI version of `PKAddPassButton`. Show it
+only when `canAddPasses()` is true and the pass parsed:
 
 ```swift
-// WRONG: Merchant ID scattered across the codebase
-let request1 = PKPaymentRequest()
-request1.merchantIdentifier = "merchant.com.example.app"
-// ...elsewhere:
-let request2 = PKPaymentRequest()
-request2.merchantIdentifier = "merchant.com.example.app" // easy to get out of sync
-
-// CORRECT: Centralize configuration
-enum PaymentConfig {
-    static let merchantIdentifier = "merchant.com.example.app"
-    static let countryCode = "US"
-    static let currencyCode = "USD"
-    static let supportedNetworks: [PKPaymentNetwork] = [.visa, .masterCard, .amex]
+if PKAddPassesViewController.canAddPasses(), let ticket = parsedTicket {
+    AddPassToWalletButton([ticket]) { added in
+        ticketSaved = added
+    }
+    .addPassToWalletButtonStyle(.blackOutline)
+    .frame(width: 260, height: 50)
 }
 ```
 
-### DON'T: Forget the total line item
-
-The last item in `paymentSummaryItems` is the total row. If you only list line
-items, the payment sheet uses the final line item as the Pay line instead of
-your business name.
-
-```swift
-// WRONG: No total item
-request.paymentSummaryItems = [
-    PKPaymentSummaryItem(label: "Widget", amount: NSDecimalNumber(string: "9.99"))
-]
-
-// CORRECT: Last item is the total with your merchant name
-request.paymentSummaryItems = [
-    PKPaymentSummaryItem(label: "Widget", amount: NSDecimalNumber(string: "9.99")),
-    PKPaymentSummaryItem(
-        label: "My Store",
-        amount: NSDecimalNumber(string: "9.99")
-    ) // Total
-]
-```
-
-### DON'T: Use binary floating-point values for money
-
-```swift
-// WRONG: PassKit amounts are NSDecimalNumber values
-PKPaymentSummaryItem(label: "Widget", amount: 9.99)
-
-// CORRECT: Construct decimal amounts explicitly
-PKPaymentSummaryItem(label: "Widget", amount: NSDecimalNumber(string: "9.99"))
-```
-
-### DON'T: Skip the canMakePayments check
-
-```swift
-// WRONG: Show Apple Pay button without checking
-PayWithApplePayButton(.buy) { startPayment() }
-
-// CORRECT: Only show when available
-if PKPaymentAuthorizationController.canMakePayments(
-    usingNetworks: PaymentConfig.supportedNetworks
-) {
-    PayWithApplePayButton(.buy) { startPayment() }
-} else {
-    // Show alternative checkout or setup button
-    Button("Set Up Apple Pay") { /* guide user */ }
-}
-```
+`parsedTicket` is a `PKPass?` produced by the throwing parse above, which has
+already reported any invalid-data or signature error.
 
-### DON'T: Dismiss the controller before completing authorization
+### The pass library
 
-Keep the authorization controller retained while presented, because its delegate
-property is weak. Dismiss only after the sheet finishes.
+`PKPassLibrary` looks at, and manages, passes the user already has.
 
 ```swift
-// WRONG: Dismissing inside didAuthorizePayment
-func paymentAuthorizationController(
-    _ controller: PKPaymentAuthorizationController,
-    didAuthorizePayment payment: PKPayment,
-    handler completion: @escaping (PKPaymentAuthorizationResult) -> Void
-) {
-    controller.dismiss() // Too early -- causes blank sheet
-    completion(.init(status: .success, errors: nil))
-}
-
-// CORRECT: Dismiss only in paymentAuthorizationControllerDidFinish
-func paymentAuthorizationControllerDidFinish(
-    _ controller: PKPaymentAuthorizationController
-) {
-    controller.dismiss { [weak self] in
-        self?.paymentController = nil
+guard PKPassLibrary.isPassLibraryAvailable() else { return }
+let library = PKPassLibrary()
+if library.containsPass(updated) {
+    if !library.replacePass(with: updated) {
+        showRetryableWalletError()
     }
 }
 ```
 
-## Review Checklist
-
-- [ ] Apple Pay capability enabled and merchant ID configured in Developer portal
-- [ ] Payment Processing Certificate generated and installed
-- [ ] `canMakePayments(usingNetworks:)` checked before showing Apple Pay button
-- [ ] Apple Pay is prominent wherever active-card availability is checked
-- [ ] Product choices, optional details, and complex shipping choices collected before payment sheet
-- [ ] Last item in `paymentSummaryItems` is the total with merchant display name
-- [ ] Payment summary and token-context amounts use `NSDecimalNumber`
-- [ ] Payment token sent to server for processing (never decoded client-side)
-- [ ] `PKPaymentAuthorizationController` retained while presented and cleared after finish
-- [ ] `paymentAuthorizationControllerDidFinish` dismisses the controller
-- [ ] Shipping method changes recalculate totals via delegate callback
-- [ ] StoreKit used for virtual goods/digital content; Apple Pay used for physical goods, services, donations, and eligible recurring payments
-- [ ] Wallet passes loaded from signed `.pkpass` bundles
-- [ ] `PKPass(data:)` invalid-data and invalid-signature failures surfaced
-- [ ] `PKPassLibrary.isPassLibraryAvailable()` used for pass operations, not add-pass capability
-- [ ] `PKAddPassesViewController.canAddPasses()` checked before add-pass UI
-- [ ] `PKPassLibrary.replacePass(with:)` Boolean result checked when replacing a pass
-- [ ] Apple Pay button uses system-provided `PKPaymentButton` or `PayWithApplePayButton`
-- [ ] Add-to-Wallet UI uses system-provided `PKAddPassButton`, `AddPassToWalletButton`, or `PKAddPassesViewController`
-- [ ] Error states handled in authorization result (network failures, declined cards)
+- `isPassLibraryAvailable()` gates library operations. Whether a pass can be
+  added is a different question, answered by `canAddPasses()`. Do not use one
+  for the other.
+- `passes()` returns only passes your entitlements give you access to.
+- `replacePass(with:)` returns a `Bool`; handle `false`.
+
+Pass bundle contents, the update web service and replacement flow are in the
+[reference](references/wallet-passes.md).
+
+## Common mistakes
+
+- **StoreKit for physical goods, or PassKit for digital ones.** Tangible
+  products, services delivered outside the app, donations and qualifying
+  recurring charges use Apple Pay. In-app currency, unlocked features and
+  subscriptions to digital content use StoreKit. Mixing them up gets the app rejected.
+- **Merchant ID copied everywhere.** Keep it, with country, currency and
+  networks, in one configuration type.
+- **No total line.** The Pay line then shows the last item rather than your
+  business name.
+- **`Double` amounts.** `amount: 9.99` is binary floating point; construct
+  `NSDecimalNumber` explicitly.
+- **Skipping `canMakePayments`.** Show the button only when it can work, and
+  otherwise offer another checkout or a "Set Up Apple Pay" button.
+- **Dismissing too early.** Keep the controller retained and dismiss only in
+  `paymentAuthorizationControllerDidFinish(_:)`.
+
+## Review checklist
+
+- [ ] Apple Pay capability and Merchant ID configured
+- [ ] Payment Processing Certificate created and installed
+- [ ] `canMakePayments(usingNetworks:capabilities:)` checked before the button shows
+- [ ] Apple Pay is prominent wherever the active-card check is used
+- [ ] Product choices, extra details and complex shipping collected before the sheet
+- [ ] Last summary item is the total, labelled with the merchant name
+- [ ] Summary and token-context amounts are `NSDecimalNumber`
+- [ ] Payment token goes to the server and is never decoded on device
+- [ ] Controller retained while presented and released after finish
+- [ ] `paymentAuthorizationControllerDidFinish` dismisses the sheet
+- [ ] Shipping-method changes recalculate the totals
+- [ ] StoreKit and Apple Pay responsibilities kept apart
+- [ ] Every pass is a signed `.pkpass` bundle
+- [ ] The user hears about a pass that fails to parse, whether the data or the signature is bad
+- [ ] `isPassLibraryAvailable()` used for library work, not for add capability
+- [ ] `canAddPasses()` checked before any add-pass UI
+- [ ] `replacePass(with:)` result checked
+- [ ] System buttons only: `PKPaymentButton` or `PayWithApplePayButton`
+- [ ] Adding to Wallet uses `PKAddPassButton`, `AddPassToWalletButton` or `PKAddPassesViewController`
+- [ ] Authorization results carry errors for declines and network failures
 
 ## References
 
-- Extended patterns (recurring/deferred payments, coupon codes, multi-merchant, pass bundles, pass updates): [references/wallet-passes.md](references/wallet-passes.md)
-- [PassKit framework](https://sosumi.ai/documentation/passkit)
-- [PKPaymentRequest](https://sosumi.ai/documentation/passkit/pkpaymentrequest)
-- [PKPaymentAuthorizationController](https://sosumi.ai/documentation/passkit/pkpaymentauthorizationcontroller)
-- [PKPaymentButton](https://sosumi.ai/documentation/passkit/pkpaymentbutton)
-- [PayWithApplePayButton](https://sosumi.ai/documentation/passkit/paywithapplepaybutton)
-- [AddPassToWalletButton](https://sosumi.ai/documentation/passkit/addpasstowalletbutton)
-- [PKPass](https://sosumi.ai/documentation/passkit/pkpass)
-- [PKAddPassesViewController](https://sosumi.ai/documentation/passkit/pkaddpassesviewcontroller)
-- [PKPassLibrary](https://sosumi.ai/documentation/passkit/pkpasslibrary)
-- [PKPaymentNetwork](https://sosumi.ai/documentation/passkit/pkpaymentnetwork)
-- [Apple Pay HIG](https://sosumi.ai/design/human-interface-guidelines/apple-pay)
+- [Wallet and advanced payments](references/wallet-passes.md): recurring,
+  coupon, multi-merchant and deferred requests; pass bundles; pass updates;
+  SwiftUI checkout
+- Apple documentation:
+  [PassKit](https://developer.apple.com/documentation/passkit),
+  [payment request](https://developer.apple.com/documentation/passkit/pkpaymentrequest),
+  [authorization controller](https://developer.apple.com/documentation/passkit/pkpaymentauthorizationcontroller),
+  [UIKit pay button](https://developer.apple.com/documentation/passkit/pkpaymentbutton),
+  [SwiftUI pay button](https://developer.apple.com/documentation/passkit/paywithapplepaybutton),
+  [SwiftUI add-pass button](https://developer.apple.com/documentation/passkit/addpasstowalletbutton),
+  [pass](https://developer.apple.com/documentation/passkit/pkpass),
+  [add-passes controller](https://developer.apple.com/documentation/passkit/pkaddpassesviewcontroller),
+  [pass library](https://developer.apple.com/documentation/passkit/pkpasslibrary),
+  [payment networks](https://developer.apple.com/documentation/passkit/pkpaymentnetwork)
+- [HIG page for Apple Pay](https://developer.apple.com/design/human-interface-guidelines/apple-pay)