Passkit

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
• Displaying the Apple Pay Button
• Creating a Payment Request
• Presenting the Payment Sheet
• Handling Payment Authorization
• Wallet Passes
• Checking Pass Library
• Common Mistakes
• Review Checklist
• 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.

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.

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.

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.

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.

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

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.

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.

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

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 invalid-signature errors. Name invalid-data and invalid-signature failures explicitly instead of hiding them behind a bare try? in review guidance.

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

SwiftUI Wallet Button

Use AddPassToWalletButton as the SwiftUI equivalent to PKAddPassButton.

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

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.

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.

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

DON'T: Hardcode merchant ID in multiple places

// 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]
}

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.

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

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

// 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 */ }
}

DON'T: Dismiss the controller before completing authorization

Keep the authorization controller retained while presented, because its delegate property is weak. Dismiss only after the sheet finishes.

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

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)

References

• Extended patterns (recurring/deferred payments, coupon codes, multi-merchant, pass bundles, pass updates): references/wallet-passes.md
• PassKit framework
• PKPaymentRequest
• PKPaymentAuthorizationController
• PKPaymentButton
• PayWithApplePayButton
• AddPassToWalletButton
• PKPass
• PKAddPassesViewController
• PKPassLibrary
• PKPaymentNetwork
• Apple Pay HIG

PassKit Extended Patterns

Overflow reference for the passkit skill. Contains advanced patterns that exceed the main skill file's scope.

A single PKPaymentRequest can set only one optional advanced payment request type, such as recurringPaymentRequest, automaticReloadPaymentRequest, deferredPaymentRequest, Apple Pay Later availability, or multiTokenContexts.

Contents

• Recurring Payment Requests
• Coupon Code Support
• Multi-Merchant Payments
• Deferred Payments
• Building Pass Bundles
• Updating Passes with Push Notifications
• SwiftUI Payment Flow

Recurring Payment Requests

Set up subscription-style recurring payments with PKRecurringPaymentRequest.

import PassKit

func createSubscriptionRequest() -> PKPaymentRequest {
    let request = PKPaymentRequest()
    request.merchantIdentifier = "merchant.com.example.app"
    request.countryCode = "US"
    request.currencyCode = "USD"
    request.supportedNetworks = [.visa, .masterCard, .amex]
    request.merchantCapabilities = .threeDSecure

    let monthlyItem = PKRecurringPaymentSummaryItem(
        label: "Monthly Subscription",
        amount: NSDecimalNumber(string: "9.99")
    )
    monthlyItem.intervalUnit = .month
    monthlyItem.intervalCount = 1

    request.paymentSummaryItems = [
        monthlyItem,
        PKPaymentSummaryItem(
            label: "My Service",
            amount: NSDecimalNumber(string: "9.99")
        )
    ]

    let recurringRequest = PKRecurringPaymentRequest(
        paymentDescription: "Monthly Premium",
        regularBilling: monthlyItem,
        managementURL: URL(string: "https://example.com/manage")!
    )
    recurringRequest.billingAgreement = "You will be charged $9.99/month."
    request.recurringPaymentRequest = recurringRequest

    return request
}

Coupon Code Support

Enable coupon codes on the payment sheet and handle validation. PKPaymentRequestCouponCodeUpdate requires a [PKShippingMethod]; pass current or updated methods, or [] when unchanged.

func createRequestWithCoupons() -> PKPaymentRequest {
    let request = createPaymentRequest()
    request.supportsCouponCode = true
    request.couponCode = "" // pre-fill if known
    return request
}

// Handle coupon code entry in the delegate
extension PaymentCoordinator: PKPaymentAuthorizationControllerDelegate {
    func paymentAuthorizationController(
        _ controller: PKPaymentAuthorizationController,
        didChangeCouponCode couponCode: String,
        handler completion: @escaping (PKPaymentRequestCouponCodeUpdate) -> Void
    ) {
        Task {
            do {
                let discount = try await validateCoupon(couponCode)
                let updatedItems = applyDiscount(discount)
                completion(PKPaymentRequestCouponCodeUpdate(
                    errors: nil,
                    paymentSummaryItems: updatedItems,
                    shippingMethods: currentShippingMethods
                ))
            } catch {
                let couponError = PKPaymentRequest.paymentCouponCodeInvalidError(
                    localizedDescription: "Invalid coupon code."
                )
                completion(PKPaymentRequestCouponCodeUpdate(
                    errors: [couponError],
                    paymentSummaryItems: originalItems,
                    shippingMethods: currentShippingMethods
                ))
            }
        }
    }
}

Multi-Merchant Payments

Request separate payment tokens for multiple merchants in one transaction using PKPaymentTokenContext.

func createMultiMerchantRequest() -> PKPaymentRequest {
    let request = PKPaymentRequest()
    request.merchantIdentifier = "merchant.com.example.platform"
    request.countryCode = "US"
    request.currencyCode = "USD"
    request.supportedNetworks = [.visa, .masterCard, .amex]
    request.merchantCapabilities = .threeDSecure

    request.paymentSummaryItems = [
        PKPaymentSummaryItem(
            label: "Hotel Stay",
            amount: NSDecimalNumber(string: "299.00")
        ),
        PKPaymentSummaryItem(
            label: "Car Rental",
            amount: NSDecimalNumber(string: "89.00")
        ),
        PKPaymentSummaryItem(
            label: "Travel Platform",
            amount: NSDecimalNumber(string: "388.00")
        )
    ]

    let hotelContext = PKPaymentTokenContext(
        merchantIdentifier: "merchant.com.example.hotel",
        externalIdentifier: "hotel-booking-123",
        merchantName: "Example Hotel",
        merchantDomain: "hotel.example.com",
        amount: NSDecimalNumber(string: "299.00")
    )

    let carContext = PKPaymentTokenContext(
        merchantIdentifier: "merchant.com.example.carrental",
        externalIdentifier: "car-rental-456",
        merchantName: "Example Car Rental",
        merchantDomain: "carrental.example.com",
        amount: NSDecimalNumber(string: "89.00")
    )

    request.multiTokenContexts = [hotelContext, carContext]
    return request
}

Deferred Payments

Set up payments that charge later, such as hotel bookings or pre-orders.

func createDeferredPaymentRequest() -> PKPaymentRequest {
    let request = createPaymentRequest()

    let deferredDate = Calendar.current.date(
        byAdding: .day, value: 14, to: Date()
    )!

    let deferredBilling = PKDeferredPaymentSummaryItem(
        label: "Hotel Stay (charged at check-in)",
        amount: NSDecimalNumber(string: "299.00")
    )
    deferredBilling.deferredDate = deferredDate

    let deferredRequest = PKDeferredPaymentRequest(
        paymentDescription: "Hotel Booking - Check-in",
        deferredBilling: deferredBilling,
        managementURL: URL(string: "https://example.com/bookings")!
    )
    deferredRequest.freeCancellationDate = deferredDate
    deferredRequest.freeCancellationDateTimeZone = .current

    request.deferredPaymentRequest = deferredRequest
    return request
}

Building Pass Bundles

A distributable pass is a signed .pkpass bundle. Keep the app-side PassKit code separate from server-side pass generation, but check these fields when a pass fails to add:

• passTypeIdentifier matches the Pass Type ID certificate.
• teamIdentifier matches the Apple Developer team that owns the certificate.
• serialNumber is unique for that pass type; updating a pass uses the same

passTypeIdentifier and serialNumber.

• manifest.json includes SHA-1 hashes for every source file, and signature

is a PKCS #7 detached signature over the manifest.

• .pkpasses bundles contain up to 10 .pkpass files and use the

application/vnd.apple.pkpasses MIME type.

Updating Passes with Push Notifications

Passes in Wallet can receive push notifications to trigger an update. The flow:

1. The pass JSON includes a webServiceURL and authenticationToken 2. When the pass is added to Wallet, the device registers with your server 3. To update, send a production APNs pass-update push with an empty JSON payload 4. The device calls your webServiceURL to fetch the updated .pkpass bundle

The pass-update web service authenticates registration, unregister, and pass download requests with authenticationToken; use the device library identifier when returning the serial numbers of updated passes. You can update any pass contents except the authentication token and serial number.

Server Endpoints (your web service must implement)

Checking for Updates In-App

import PassKit

let library = PKPassLibrary()

// Replace an existing pass with updated data
func updatePass(newPassData: Data) {
    guard let updatedPass = try? PKPass(data: newPassData) else { return }
    if library.containsPass(updatedPass) {
        let replaced = library.replacePass(with: updatedPass)
        if !replaced {
            // Fall back to add-pass UI or report a recoverable update failure.
        }
    }
}

SwiftUI Payment Flow

A complete SwiftUI payment view with availability check, button, and processing.

import SwiftUI
import PassKit

struct PaymentView: View {
    @State private var paymentStatus: PaymentStatus = .idle
    @State private var coordinator: PaymentCoordinator?

    private var canPay: Bool {
        PKPaymentAuthorizationController.canMakePayments(
            usingNetworks: [.visa, .masterCard, .amex],
            capabilities: .threeDSecure
        )
    }

    var body: some View {
        VStack {
            OrderSummaryView()

            if canPay {
                PayWithApplePayButton(.buy) {
                    processPayment()
                }
                .payWithApplePayButtonStyle(.black)
                .frame(height: 48)
            } else {
                Button("Checkout with Card") {
                    // Fallback payment flow
                }
                .buttonStyle(.borderedProminent)
            }

            if case .error(let message) = paymentStatus {
                Text(message)
                    .foregroundStyle(.red)
                    .font(.caption)
            }
        }
        .padding()
    }

    @MainActor
    private func processPayment() {
        coordinator = PaymentCoordinator { result in
            paymentStatus = result
        }
        coordinator?.startPayment()
    }
}

enum PaymentStatus {
    case idle
    case processing
    case success
    case error(String)
}