---
name: proximity-reader
description: >
  Comprehensive iOS development skill for Apple's ProximityReader framework.
  Covers Tap to Pay on iPhone (payment card reading), loyalty card (VAS) integration,
  Store and Forward mode, the Verifier API (mobile document / ID reading), and
  merchant discovery UI. Use this skill whenever the user mentions ProximityReader,
  Tap to Pay on iPhone, contactless payments on iPhone, NFC payment reading,
  loyalty card reading from Wallet, VAS requests, mobile driver's license verification,
  ID verification on iPhone, MobileDocumentReader, PaymentCardReader,
  PaymentCardReaderSession, or any related topic. Also trigger when the user wants
  to build a point-of-sale (POS) app, accept contactless payments without hardware,
  or read digital wallet passes on iPhone.
---

# ProximityReader iOS Development Skill

Build contactless payment, loyalty, and ID verification features using Apple's ProximityReader framework on iPhone — no additional hardware required.

## When to Use This Skill

- Integrating **Tap to Pay on iPhone** (contactless payment acceptance)
- Reading **loyalty cards / VAS passes** from Apple Wallet
- Implementing **Store and Forward** for offline payment scenarios
- Building **ID verification** with the Verifier API (mobile driver's licenses, national IDs)
- Showing **merchant education UI** via `ProximityReaderDiscovery`
- Debugging `PaymentCardReaderError` or `MobileDocumentReaderError`

## Framework Overview

**ProximityReader** (iOS 15.4+, iPadOS 15.4+, Mac Catalyst 15.4+) enables an iPhone to act as a contactless reader for:

| Domain | Key Classes | Min iOS |
|--------|-------------|---------|
| Payments | `PaymentCardReader`, `PaymentCardReaderSession` | 15.4 |
| Loyalty (VAS) | `VASRequest`, `VASReadResult` | 15.4 |
| Store & Forward | `StoreAndForwardPaymentCardReaderSession`, `PaymentCardReaderStore` | 17.0+ |
| ID Verification | `MobileDocumentReader`, `MobileDocumentReaderSession` | 17.0+ |
| Merchant Discovery | `ProximityReaderDiscovery` | 18.0+ |

## Prerequisites & Entitlements

Before writing any code, ensure:

1. **Entitlement**: Request the Tap to Pay on iPhone entitlement from Apple via your developer account. Without it, the framework won't function.
2. **Payment Service Provider (PSP)**: You must coordinate with a Level 3 certified PSP (e.g. Stripe, Adyen, Square, Windcave). The PSP provides the **reader token** (JWT) required to initialize the reader.
3. **Device**: iPhone XS or later. No additional NFC hardware needed.
4. **Xcode**: Add the `com.apple.developer.proximity-reader.payment.acceptance` entitlement to your app's entitlements file.

For the Verifier API (ID reading), a separate entitlement and server-side reader token generation is required. Read `references/verifier-api.md` for details.

## Architecture at a Glance

```
┌─────────────────────────────────────────────────┐
│                   Your App                       │
├──────────┬──────────┬───────────┬───────────────┤
│ Payment  │ Loyalty  │ Store &   │  ID           │
│ Flow     │ (VAS)    │ Forward   │  Verification │
├──────────┴──────────┴───────────┴───────────────┤
│              ProximityReader Framework           │
├─────────────────────────────────────────────────┤
│         Secure Element / NFC Hardware            │
└─────────────────────────────────────────────────┘
```

## Quick Reference: Common Patterns

### 1. Payment Card Reading (Tap to Pay)

```swift
import ProximityReader

// 1. Create and configure the reader
let reader = PaymentCardReader()

// 2. Obtain token from your PSP
let token = PaymentCardReader.Token(rawValue: pspProvidedJWT)

// 3. Link the merchant account (first use only)
if try await !reader.isAccountLinked(using: token) {
    try await reader.linkAccount(using: token)
}

// 4. Create a session and prepare
let session = try await PaymentCardReaderSession(reader: reader, token: token)
try await session.prepare()

// 5. Read a payment card
let request = PaymentCardTransactionRequest(
    amount: Decimal(29.99),
    currencyCode: "USD",
    type: .purchase
)

let result: PaymentCardReadResult = try await session.readPaymentCard(request)
// Send result.paymentCardData to your PSP for processing
```

### 2. Loyalty Card (VAS) Reading

```swift
// Can be combined with payment or standalone
let vasRequest = VASRequest(
    merchantIdentifier: "pass.com.example.loyalty",
    localizedDescription: "Example Loyalty Program"
)

// Read loyalty card alongside payment
let result = try await session.readPaymentCard(
    request,
    vasRequest: vasRequest
)

// Access loyalty data
if let vasResult = result.vasReadResult {
    // Process loyalty identifiers
}
```

### 3. Store and Forward (Offline)

```swift
let sfSession = try await StoreAndForwardPaymentCardReaderSession(
    reader: reader,
    token: token
)
try await sfSession.prepare()

// Transactions are stored locally
let result = try await sfSession.readPaymentCard(request)

// Later, when online: retrieve and send batches
let store = PaymentCardReaderStore()
let batches: [StoreAndForwardBatch] = try await store.allBatches()

for batch in batches {
    // Send batch.data to PSP
    // On success, delete the batch
    try await store.delete(using: batch.deletionToken)
}
```

### 4. Mobile Document / ID Reading (Verifier API)

Read `references/verifier-api.md` for the full setup including server-side reader token generation.

```swift
import ProximityReader

let docReader = MobileDocumentReader()
let readerToken = try await fetchReaderToken() // From your server

let session = try await MobileDocumentReaderSession(
    reader: docReader,
    readerToken: readerToken
)
try await session.prepare()

// Request a driver's license display
let displayRequest = MobileDriversLicenseDisplayRequest(
    retainedElements: [.givenName, .familyName, .portrait, .dateOfBirth, .ageOver21]
)
try await session.readDocument(displayRequest)

// Or request validated data
let dataRequest = MobileDriversLicenseDataRequest(
    retainedElements: [.givenName, .familyName, .dateOfBirth]
)
let documentResult = try await session.readDocument(dataRequest)
```

### 5. Merchant Discovery UI

```swift
// iOS 18+: Show Apple-provided merchant education
let discovery = ProximityReaderDiscovery()
try await discovery.present()
```

## Error Handling

Always wrap ProximityReader calls in do-catch. The two main error types are:

```swift
do {
    try await session.readPaymentCard(request)
} catch let error as PaymentCardReaderError {
    switch error {
    case .notAllowed:
        // Missing entitlement or not authorized
    case .unsupported:
        // Device doesn't support Tap to Pay
    case .networkError:
        // Connectivity issue
    case .invalidReaderToken:
        // Token from PSP is invalid or expired
    case .readerBusy:
        // Another read session is active
    case .backgrounded:
        // App moved to background during read — must call prepare() again
    default:
        break
    }
} catch let error as PaymentCardReaderSession.ReadError {
    switch error {
    case .cancelled:
        // Customer cancelled the tap
    case .invalidAmount:
        // Amount was negative or zero
    case .notReady:
        // prepare() was not called
    default:
        break
    }
}
```

For the Verifier API:
```swift
catch let error as MobileDocumentReaderError {
    // Handle session preparation and document request errors
}
```

## Critical Implementation Notes

- **Always call `prepare()` after the app returns to the foreground.** The reader session is invalidated when backgrounded. Safe to call multiple times.
- **Call `prepare()` after each transaction** to reset internal state for the next transaction.
- **The reader token (JWT) comes from your PSP**, not from Apple directly. Each PSP has their own token generation flow.
- **PIN entry** is supported on iOS 16.4+ for contactless cards that require it.
- **Testing**: Use `ProximityReaderStub` for simulator testing. Real NFC reads require a physical device.
- **Thread safety**: ProximityReader uses Swift concurrency (async/await). All calls should be made from the main actor or appropriate actor context.
- **Store and Forward**: Batches persist on device. Always delete after successful processing to avoid data accumulation.

## Deeper Reference Docs

For more detailed implementation guides, read these reference files:

| Reference | When to Read |
|-----------|-------------|
| `references/api-reference.md` | Full class/struct/enum listing with all properties and methods |
| `references/verifier-api.md` | Complete Verifier API setup including server-side token generation |
| `references/integration-patterns.md` | PSP integration patterns (Stripe, Adyen, Square), SwiftUI patterns, MVVM architecture |
| `references/troubleshooting.md` | Common errors, debugging tips, device compatibility |

## Code Generation Guidelines

When generating ProximityReader code:

1. Always `import ProximityReader`
2. Use Swift concurrency (async/await) — the entire API is async
3. Wrap all reader operations in do-catch with specific error handling
4. Include `prepare()` calls after foregrounding and after each transaction
5. Never hardcode PSP tokens — always fetch from server/PSP SDK
6. For SwiftUI: use `.task {}` modifier or `@MainActor` view models
7. Always check device capability before attempting to use the reader
8. Follow Apple HIG: the tap payment sheet is system-provided — don't recreate it