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.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'],
},
},
};
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. |
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'],
},
}
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,
},
}
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,
},
}
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',
},
},
};
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 |
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
- 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
