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.
Quick reference Option Type Default Description 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' ], }, }, };
Customize the appearance of the Apple Pay button through the buttonOptions configuration.
Option Type Default Description 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.
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' , }, }
Billing options Capture billing information from the customer’s Apple Wallet.
applePay : { billingOptions : { requiredBillingContactFields : [ 'postalAddress' ], }, }
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 , }, }
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.lineItemsFees — All fees from order.feesShipping — Shipping cost when shipping options are enabled
The total amount is calculated from merchantAmount if set, otherwise from totalOrderAmount.
Testing Development
Use Safari on macOS or iOS
Add a test card to your Apple Wallet
Use Primer’s TEST environment
Production
Register your domain in the Apple Developer Portal
Configure your merchant identifier
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
