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

# Apple Pay options

> Configuration options for Apple Pay payment integration

Apple Pay enables customers to pay using payment methods saved to their Apple Wallet. The SDK provides configuration options for button styling and contact information capture.

## Client session requirements

Apple Pay requires `currencyCode` and `order.countryCode` in the client session.

<Note>
  `order.countryCode` is the merchant's country (ISO 3166-1 alpha-2) — where the transaction is processed, not the buyer's country. This maps to Apple Pay's [`PKPaymentRequest.countryCode`](https://developer.apple.com/documentation/passkit/pkpaymentrequest/countrycode): "the two-letter ISO 3166 code for the country or region of the merchant's principle place of business."
</Note>

## Quick reference

| Option                                          | Type       | Default   | Description                      |
| ----------------------------------------------- | ---------- | --------- | -------------------------------- |
| `buttonOptions.type`                            | `string`   | `'plain'` | Button label                     |
| `buttonOptions.buttonStyle`                     | `string`   | —         | Button color                     |
| `billingOptions.requiredBillingContactFields`   | `string[]` | `[]`      | Billing fields to capture        |
| `shippingOptions.requiredShippingContactFields` | `string[]` | `[]`      | Shipping fields to capture       |
| `shippingOptions.requireShippingMethod`         | `boolean`  | `false`   | Enable shipping method selection |

```javascript theme={"dark"}
checkout.options = {
  applePay: {
    buttonOptions: {
      type: 'buy',
      buttonStyle: 'black',
    },
    billingOptions: {
      requiredBillingContactFields: ['postalAddress'],
    },
  },
};
```

***

## Button options

Customize the appearance of the Apple Pay button through the `buttonOptions` configuration.

| Option                      | Type     | Default   | Description                                                                                                                                                               |
| --------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `buttonOptions.type`        | `string` | `'plain'` | Button label text (see [values](#button-type) below). Automatically localized.                                                                                            |
| `buttonOptions.buttonStyle` | `string` | —         | `'black'` for black with white text, `'white'` for white with black text, `'white-outline'` for white with black outline. If not set, Apple Pay uses its default styling. |

### Button type

Set `buttonOptions.type` to control the label displayed on the Apple Pay button. Text is automatically localized.

| Type           | Description                   |
| -------------- | ----------------------------- |
| `'plain'`      | Apple Pay logo only (default) |
| `'buy'`        | "Buy with Apple Pay"          |
| `'book'`       | "Book with Apple Pay"         |
| `'check-out'`  | "Check Out with Apple Pay"    |
| `'donate'`     | "Donate with Apple Pay"       |
| `'order'`      | "Order with Apple Pay"        |
| `'pay'`        | "Pay with Apple Pay"          |
| `'set-up'`     | "Set Up with Apple Pay"       |
| `'subscribe'`  | "Subscribe with Apple Pay"    |
| `'add-money'`  | "Add Money with Apple Pay"    |
| `'continue'`   | "Continue with Apple Pay"     |
| `'contribute'` | "Contribute with Apple Pay"   |
| `'reload'`     | "Reload with Apple Pay"       |
| `'rent'`       | "Rent with Apple Pay"         |
| `'support'`    | "Support with Apple Pay"      |
| `'tip'`        | "Tip with Apple Pay"          |
| `'top-up'`     | "Top Up with Apple Pay"       |

### Examples

```javascript theme={"dark"}
// Standard black button for purchasing
applePay: {
  buttonOptions: {
    type: 'buy',
    buttonStyle: 'black',
  },
}

// White button for dark backgrounds
applePay: {
  buttonOptions: {
    type: 'pay',
    buttonStyle: 'white',
  },
}

// Donation button with outline
applePay: {
  buttonOptions: {
    type: 'donate',
    buttonStyle: 'white-outline',
  },
}
```

<Tip>
  The SDK renders buttons according to [Apple's Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/apple-pay).
</Tip>

***

## Billing options

Capture billing information from the customer's Apple Wallet.

```javascript theme={"dark"}
applePay: {
  billingOptions: {
    requiredBillingContactFields: ['postalAddress'],
  },
}
```

### Required billing contact fields

Set `requiredBillingContactFields` to specify which billing details to capture from the customer's Apple Wallet.

| Field             | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| `'postalAddress'` | Billing address (street, city, state, postal code, country) |

***

## Shipping options

Capture shipping information from the customer's Apple Wallet and enable shipping method selection.

```javascript theme={"dark"}
applePay: {
  shippingOptions: {
    requiredShippingContactFields: ['postalAddress', 'name', 'email', 'phone'],
    requireShippingMethod: true,
  },
}
```

### Required shipping contact fields

Set `requiredShippingContactFields` to specify which shipping details to capture from the customer's Apple Wallet.

| Field             | Description                     |
| ----------------- | ------------------------------- |
| `'postalAddress'` | Shipping address                |
| `'name'`          | Recipient's name                |
| `'phoneticName'`  | Phonetic representation of name |
| `'phone'`         | Phone number                    |
| `'email'`         | Email address                   |

### Shipping method selection

Set `requireShippingMethod` to `true` to display available shipping methods in the Apple Pay sheet. This requires a shipping module to be configured in your Primer dashboard.

```javascript theme={"dark"}
applePay: {
  shippingOptions: {
    requiredShippingContactFields: ['postalAddress'],
    requireShippingMethod: true,
  },
}
```

When enabled, customers can select from your configured shipping methods directly within the Apple Pay sheet.

***

## Domain configuration

If your checkout is hosted on a different domain than your registered Apple Pay domain, set `merchantDomain`:

```javascript theme={"dark"}
checkout.options = {
  merchantDomain: 'merchant.example.com',
  applePay: {
    buttonOptions: {
      type: 'buy',
      buttonStyle: 'black',
    },
  },
};
```

See [merchantDomain](/sdk/primer-checkout-web/sdk-options-reference#merchantdomain) in the SDK Options Reference.

***

## Complete example

```html theme={"dark"}
<primer-checkout client-token="your-client-token"></primer-checkout>

<script type="module">
  import { loadPrimer } from '@primer-io/primer-js';

  loadPrimer();

  const checkout = document.querySelector('primer-checkout');
  checkout.options = {
    applePay: {
      buttonOptions: {
        type: 'buy',
        buttonStyle: 'black',
      },
      billingOptions: {
        requiredBillingContactFields: ['postalAddress'],
      },
      shippingOptions: {
        requiredShippingContactFields: ['postalAddress', 'name', 'email', 'phone'],
      },
    },
  };
</script>
```

***

## Supported card networks

| Network           | Description               |
| ----------------- | ------------------------- |
| VISA              | Visa cards                |
| MASTERCARD        | Mastercard cards          |
| AMEX              | American Express cards    |
| DISCOVER          | Discover cards            |
| JCB               | JCB cards                 |
| MAESTRO           | Maestro cards             |
| CARTES\_BANCAIRES | Cartes Bancaires (France) |
| DANKORT           | Dankort (Denmark)         |
| ELO               | Elo (Brazil)              |
| EFTPOS            | eftpos (Australia)        |
| INTERAC           | Interac (Canada)          |
| MIR               | Mir (Russia)              |
| UNIONPAY          | China UnionPay            |

The SDK filters networks based on your Primer configuration. If `orderedAllowedCardNetworks` is set in your client session, only those networks are available.

***

## Display items

The Apple Pay sheet displays line items from your order:

* **Line items** — Products from `order.lineItems`
* **Fees** — All fees from `order.fees`
* **Shipping** — Shipping cost when shipping options are enabled

The total amount is calculated from `merchantAmount` if set, otherwise from `totalOrderAmount`.

***

## Testing

### Development

1. Use Safari on macOS or iOS
2. Add a test card to your Apple Wallet
3. Use Primer's TEST environment

### Production

1. Register your domain in the [Apple Developer Portal](https://developer.apple.com/)
2. Configure your merchant identifier
3. Verify your domain

<Note>
  Apple Pay only works on supported devices with Safari or WebKit-based browsers. The button appears only when the device supports Apple Pay and the user has payment methods configured.
</Note>

***

## See also

<CardGroup cols={2}>
  <Card title="SDK options reference" icon="gear" href="/sdk/primer-checkout-web/sdk-options-reference">
    All configuration options
  </Card>

  <Card title="Apple Pay on the web" icon="arrow-up-right-from-square" href="https://developer.apple.com/documentation/applepayontheweb">
    Official Apple documentation
  </Card>

  <Card title="Apple Pay button types" icon="arrow-up-right-from-square" href="https://developer.apple.com/documentation/applepayontheweb/applepaybuttontype">
    Complete button type reference
  </Card>
</CardGroup>