Skip to main content

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

OptionTypeDefaultDescription
buttonOptions.typestring'plain'Button label
buttonOptions.buttonStylestring—Button color
billingOptions.requiredBillingContactFieldsstring[][]Billing fields to capture
shippingOptions.requiredShippingContactFieldsstring[][]Shipping fields to capture
shippingOptions.requireShippingMethodbooleanfalseEnable 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.
OptionTypeDefaultDescription
buttonOptions.typestring'plain'Button label text (see values below). Automatically localized.
buttonOptions.buttonStylestring—'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.
TypeDescription
'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.
FieldDescription
'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.
FieldDescription
'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

NetworkDescription
VISAVisa cards
MASTERCARDMastercard cards
AMEXAmerican Express cards
DISCOVERDiscover cards
JCBJCB cards
MAESTROMaestro cards
CARTES_BANCAIRESCartes Bancaires (France)
DANKORTDankort (Denmark)
ELOElo (Brazil)
EFTPOSeftpos (Australia)
INTERACInterac (Canada)
MIRMir (Russia)
UNIONPAYChina 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