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.

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: “the two-letter ISO 3166 code for the country or region of the merchant’s principle place of business.”

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

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

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

The SDK renders buttons according to Apple’s Human Interface Guidelines.

---

Billing options

Capture billing information from the customer’s Apple Wallet.

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.

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.

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:

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

See merchantDomain in the SDK Options Reference.

---

Complete example

<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
2. Configure your merchant identifier
3. Verify your domain

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.

---

See also

SDK options reference

All configuration options

Apple Pay on the web

Official Apple documentation

Apple Pay button types

Complete button type reference