> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taprails.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS Setup

> Configure your iOS project to support NFC reading with the TapRails SDK.

## Requirements

* iOS **13.0** or later
* Device with NFC hardware (iPhone 7 and later)

<Warning>
  **iOS cannot act as a merchant.** Apple restricts Host Card Emulation (HCE) to Apple Pay only. On iOS, TapRails can only operate in **customer mode** (reading NFC tags). The merchant device must be Android.
</Warning>

***

## 1. Install CocoaPods

After installing npm/yarn dependencies, run:

```bash theme={null}
cd ios && pod install && cd ..
```

Re-run this whenever you install new native packages.

***

## 2. Add NFC Usage Description

Open `ios/<YourApp>/Info.plist` and add the NFC usage description key:

```xml ios/<YourApp>/Info.plist theme={null}
<key>NFCReaderUsageDescription</key>
<string>We need NFC access to read contactless payment requests.</string>
```

<Warning>
  This key is **required by Apple** — your app will be rejected from the App Store if it's missing and the app uses NFC APIs. The string is shown to users in the iOS permission dialog.
</Warning>

***

## 3. Enable NFC Capability (if not already enabled)

In Xcode:

1. Open your project's **Signing & Capabilities** tab
2. Click **+ Capability**
3. Add **Near Field Communication Tag Reading**

This adds the `com.apple.developer.nfc.readersession.formats` entitlement to your app's entitlements file automatically.

***

## 4. Verify

Build and run your iOS app:

```bash theme={null}
npm run ios
# or
react-native run-ios
```

<Note>
  NFC entitlements only work on a **physical device** — the iOS Simulator does not support NFC. You must run on a real iPhone to test tap-to-pay.
</Note>

<Check>
  **iOS setup complete!** You can now use `useNFCCustomer` and the customer `PaymentFlowManager` flow on iOS devices.
</Check>