# Apple Pay

> Accept Apple Pay payments on iOS using the Bolt React Native SDK for Embeddable Checkout.

Source: https://help.boltapp.com/developers/sdks/react-native/apple-pay

## Overview [#overview]

This guide covers Apple Pay integration for [Bolt Embeddable Checkout](/products/embeddable-checkout).

The Bolt React Native SDK provides an `ApplePay` component that renders a native `PKPaymentButton` on iOS. On Android, the component renders nothing.

Apple Pay supports two modes:

| Mode                    | Description                                                                     | Entitlement Required? |
| ----------------------- | ------------------------------------------------------------------------------- | --------------------- |
| **`webview`** (default) | Uses the Bolt-hosted Apple Pay iframe for merchant validation and tokenization. | No                    |
| **`native`**            | Uses the native PassKit payment sheet directly on device.                       | Yes                   |

## WebView Mode (Default) [#webview-mode-default]

WebView mode is the simplest way to get started: no Apple Pay entitlement or merchant certificate setup is required. Bolt handles merchant validation and tokenization server-side.

```typescript title="TypeScript"
import { ApplePay } from '@boltpay/react-native/payments';

function CheckoutScreen() {
  return (
    <ApplePay
      config={{
        countryCode: 'US',
        currencyCode: 'USD',
        total: { label: 'Your Store', amount: '9.99' },
      }}
      referrer="https://your-store.example.com"
      buttonType="buy"
      buttonStyle="black"
      onComplete={(result) => {
        // result: { token, bin?, expiration?, billingContact?, boltReference? }
      }}
      onError={(error) => console.error(error)}
    />
  );
}
```

<Note>
  The `referrer` prop is **required** in WebView mode. This must be the merchant website URL registered with both Bolt and Apple for merchant validation to succeed.
</Note>

## Native Mode [#native-mode]

If you need the native PassKit payment sheet, set `mode="native"`. This requires your app to have the Apple Pay entitlement configured with your Apple-registered merchant identifier.

<Warning>
  The `merchantId` in native mode is **not** your Bolt publishable key: it is the identifier you register in the [Apple Developer portal](https://developer.apple.com/account/resources/identifiers).
</Warning>

### Xcode Setup [#xcode-setup]

Open your app target in Xcode:

1. Go to **Signing & Capabilities**.
2. Click **+ Capability**.
3. Select **Apple Pay**.
4. Check your merchant ID.

### Expo Setup [#expo-setup]

Add the following to your `app.json`:

```json title="app.json"
{
  "ios": {
    "entitlements": {
      "com.apple.developer.in-app-payments": ["merchant.com.yourapp"]
    }
  }
}
```

Then re-run `expo prebuild` and rebuild your app.

### Usage [#usage]

```typescript title="TypeScript"
<ApplePay
  mode="native"
  config={{
    merchantId: 'merchant.com.yourapp',
    countryCode: 'US',
    currencyCode: 'USD',
    total: { label: 'Your Store', amount: '9.99' },
  }}
  buttonType="buy"
  onComplete={(result) => { /* ... */ }}
/>
```

## Props Reference [#props-reference]

| Prop          | Type                                   | Default     | Description                                                                               |
| ------------- | -------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `config`      | `ApplePayConfig`                       | required    | Country/currency, total amount, and optional merchant ID (`mode='native'` only).          |
| `onComplete`  | `(ApplePayResult) => void`             | required    | Called with token, bin, expiration, and billing contact on success.                       |
| `onError`     | `(Error) => void`                      | :           | Called on payment failure.                                                                |
| `mode`        | `'webview' \| 'native'`                | `'webview'` | `'webview'` uses the Bolt-hosted iframe (no entitlement needed). `'native'` uses PassKit. |
| `buttonType`  | `ApplePayButtonType`                   | `'plain'`   | Button label variant. Auto-localized by Apple.                                            |
| `buttonStyle` | `'black' \| 'white' \| 'whiteOutline'` | `'black'`   | Button color theme.                                                                       |
| `referrer`    | `string`                               | :           | Merchant website URL registered with Bolt and Apple. **Required for WebView mode.**       |
| `style`       | `ViewStyle`                            | :           | Container style overrides (height, margin, etc.).                                         |

### ApplePayButtonType Values [#applepaybuttontype-values]

`'plain'`, `'buy'`, `'checkout'`, `'book'`, `'subscribe'`, `'donate'`, `'order'`, `'setUp'`, `'inStore'`, `'reload'`, `'addMoney'`, `'topUp'`, `'rent'`, `'support'`, `'contribute'`, `'tip'`

### ApplePayResult [#applepayresult]

```typescript title="Signature"
{
  token: string;
  bin?: string;
  expiration?: string;
  billingContact?: object;
  boltReference?: string;
}
```