passkit

What this skill does

# PassKit

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+.

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)

## 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

### Availability Check

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.

```swift
import PassKit

func canMakePayments() -> Bool {
    // Check device supports Apple Pay at all
    guard PKPaymentAuthorizationController.canMakePayments() else {
        return false
    }
    // Check user has cards for the networks you support
    return PKPaymentAuthorizationController.canMakePayments(
        usingNetworks: [.visa, .masterCard, .amex, .discover],
        capabilities: .threeDSecure
    )
}
```

## Displaying the Apple Pay Button

### SwiftUI

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.

```swift
import SwiftUI
import PassKit

struct CheckoutView: View {
    var body: some View {
        PayWithApplePayButton(.buy) {
            startPayment()
        }
        .payWithApplePayButtonStyle(.black)
        .frame(height: 48)
        .padding()
    }
}
```

### UIKit

Use `PKPaymentButton` for UIKit-based interfaces.

```swift
let button = PKPaymentButton(
    paymentButtonType: .buy,
    paymentButtonStyle: .black
)
button.cornerRadius = 12
button.addTarget(self, action: #selector(startPayment), for: .touchUpInside)
```

**Button types:** `.plain`, `.buy`, `.setUp`, `.inStore`, `.donate`,
`.checkout`, `.continue`, `.book`, `.subscribe`, `.reload`, `.addMoney`,
`.topUp`, `.order`, `.rent`, `.support`, `.contribute`, `.tip`

## Creating a Payment Request

Build a `PKPaymentRequest` with your merchant details and the items being purchased.
PassKit amount APIs take `NSDecimalNumber`, not `Double`.

```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
}
```

The **last item** in `paymentSummaryItems` is treated as the total and its label
appears in the Pay line on the payment sheet.

### Requesting Shipping and Contact Info

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.

```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
```

### Supported Networks

| Network | Constant |
|---|---|
| Visa | `.visa` |
| Mastercard | `.masterCard` |
| American Express | `.amex` |
| Discover | `.discover` |
| China UnionPay | `.chinaUnionPay` |
| JCB | `.JCB` |
| Maestro | `.maestro` |
| Electron | `.electron` |
| Interac | `.interac` |

Query available networks at runtime with `PKPaymentRequest.availableNetworks()`.

## Presenting the Payment Sheet

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.

```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
            }
        }
    }
}
```

## Handling Payment Authorization

Implement `PKPaymentAuthorizationControllerDelegate` to process the payment token.

```swift
extension CheckoutCoordinator: PKPaymentAuthorizationControllerDelegate {
    func paymentAuthorizationController(
        _ controller: PKPaymentAuthorizationController,
        didAuthorizePayment payment: PKPayment,
        handler completion: @escaping (PKPaymentAuthorizationResult) -> Void
    ) {
        // Send payment.token.paymentData to your payment processor
        Task {
            do {
                try await paymentService.process(payment.token)
                completion(PKPaymentAuthorizationResult(status: .success, errors: nil))
            } catch {
                completion(PKPaymentAuthorizationResult(status: .failure, errors: [error]))
            }
        }
    }

    func paymentAuthorizationControllerDidFinish(
        _ controller: PKPaymentAuthorizationController
    ) {
        controller.dismiss { [weak self] in
            self?.paymentController = 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)
}
```

## Wallet Passes

### Adding a Pass to Wallet

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 inv