Apple Pay Buttons in CSS

Understanding Apple Pay Button Fundamentals

Apple Pay on the web provides a secure, streamlined checkout experience for users on Safari browsers across Mac, iPhone, and iPad. Unlike traditional payment buttons that rely on custom graphics or JavaScript rendering, Apple Pay buttons are rendered directly by the browser using native CSS properties. This approach ensures consistent appearance, automatic updates with OS changes, and proper integration with the Safari payment sheet.

The foundation of Apple Pay button implementation rests on the -webkit-appearance CSS property, which tells Safari to render a native Apple Pay button instead of standard HTML elements. When a user views an Apple Pay button in a supported browser on a compatible device, Safari automatically displays the familiar Apple Pay branding with the appropriate style and language settings.

Understanding the distinction between button styles, button types, and display properties is essential. The style determines the visual appearance (black, white, or white outline), while the type defines the button's purpose and text label (buy, pay, set up, or donate). The display properties control sizing, corner radius, and other visual adjustments. Together, these properties give developers flexibility while maintaining Apple's strict design guidelines.

Browser and Device Requirements

Safari remains the only browser that natively supports Apple Pay button rendering. This includes Safari on macOS (version 10.12 and later) and Safari on iOS (version 10 and later). Chrome, Firefox, Edge, and other browsers do not recognize the -webkit-appearance property for Apple Pay, which means they cannot render the native button. However, this limitation is by design--Apple Pay is an Apple ecosystem feature, and users on non-Safari browsers are expected to use alternative payment methods.

Device compatibility extends beyond browser support. Users must have a compatible Apple device with Touch ID, Face ID, or an Apple Watch paired with a Mac for authentication. Older iPads and MacBooks without biometric authentication require an iPhone or Apple Watch to complete the payment. The Safari payment sheet handles these requirements automatically, checking device capabilities before presenting payment options.

For developers, implementing feature detection to show or hide Apple Pay buttons based on browser support is crucial. Apple's documentation recommends using the @supports CSS at-rule to conditionally display the Apple Pay button only in supporting browsers. Additionally, JavaScript-based detection can determine whether the user has Apple Pay available, allowing for more granular control over when to offer Apple Pay as a payment option. Our e-commerce development services help businesses implement seamless payment integrations like Apple Pay that improve checkout conversion rates.

Apple Pay is supported across Safari browsers on Apple devices, and implementing proper feature detection ensures users only see the payment option when it's actually available on their system. For developers working on modern web applications, understanding browser-specific CSS properties and their limitations is essential for creating robust payment experiences.

CSS Styling Properties Deep Dive

The primary CSS property for Apple Pay buttons is -webkit-appearance: -apple-pay-button, which triggers the native button rendering. This property must be set on a block-level element (typically a <div> or <button>) to display the Apple Pay interface. The element can be styled further using additional Apple-specific properties and standard CSS.

Button Styles

The -apple-pay-button-style property accepts three values that control the button's visual appearance:

• black: Solid black button with white Apple Pay logo and text, providing maximum contrast on light backgrounds
• white: White button with black Apple Pay logo, ideal for dark backgrounds or when a lighter aesthetic is preferred
• white-outline: White button with a visible border, suitable for contexts where the white button might not stand out sufficiently against the page background

Button Types

Button types determine the text label displayed alongside the Apple Pay logo:

• buy: "Buy with Apple Pay"--for direct purchase transactions
• pay: Shorter label suitable for payments on existing purchases or subscriptions
• set up: Indicates setting up Apple Pay for future use
• donate: Restricted to charitable donation scenarios and requires additional verification through Apple's developer program

Sizing and Layout Control

While Apple controls the internal rendering of the Apple Pay button, developers can influence its size and positioning through CSS. The -apple-pay-button-size property (values: mini, small, medium, large, or auto) provides predefined size options that adjust both the button's dimensions and text scaling. Setting explicit width and height values gives developers precise control, though values below Apple's minimum recommendations may result in cropped or unreadable buttons.

For responsive layouts, wrapping the Apple Pay button in a container with flexbox or grid properties allows for dynamic positioning. The button itself respects standard box model properties, enabling margins for spacing, padding, and alignment within parent containers. Testing across device sizes ensures the button remains visible and clickable, particularly on mobile screens where space constraints are more pronounced.

Developers working with CSS Grid or flexbox layouts will find these positioning techniques essential for creating responsive payment interfaces that work seamlessly across all device sizes.

HTML Structure and Accessibility

Apple's official documentation recommends a simple <div> element with the CSS properties applied directly. However, this approach creates accessibility challenges since the div lacks semantic meaning and screen readers cannot announce it as a button. The default implementation also provides no keyboard interactivity, which can frustrate users who navigate with keyboards or assistive technologies.

Improved Accessible Implementation

A more robust approach wraps the Apple Pay button div in a semantic <button> element, preserving the native rendering while gaining accessibility benefits. The button element automatically provides keyboard focus, Enter and Space key activation, and proper ARIA announcements. Adding appropriate aria-label attributes further improves screen reader experience by announcing the button's purpose clearly.

<button type="button" 
 class="apple-pay-button" 
 onclick="onApplePayClick()" 
 aria-label="Pay with Apple Pay">
 <span class="visually-hidden">Apple Pay</span>
</button>

The visually hidden text technique provides fallback content for older browsers while remaining invisible in modern browsers that support the CSS. This ensures that screen readers announce meaningful text while the native Apple Pay button remains visible to sighted users. Focus styles should be implemented on the container button element to indicate keyboard focus visually, since the native Apple Pay rendering may not provide visible focus indicators.

Implementing proper accessibility features like ARIA labels and semantic HTML ensures your payment buttons work for all users, including those relying on screen readers or keyboard navigation.

Browser Compatibility and Feature Detection

The @supports CSS rule allows developers to apply styles only when the browser recognizes specific properties. By wrapping Apple Pay button styles in a @supports block, developers can ensure the styles only apply in Safari, with alternative content displayed in other browsers.

Using @supports for Conditional Display

@supports (-webkit-appearance: -apple-pay-button) {
 .apple-pay-button {
 display: block;
 -webkit-appearance: -apple-pay-button;
 -apple-pay-button-type: buy;
 -apple-pay-button-style: black;
 width: 200px;
 height: 44px;
 }
}

@supports not (-webkit-appearance: -apple-pay-button) {
 .apple-pay-button {
 display: none;
 }
 .alternative-payment-button {
 display: block;
 }
}

JavaScript feature detection provides additional control over when to show or hide Apple Pay options. The window.ApplePaySession object exists only when Apple Pay is available, allowing for server-side and client-side checks to determine whether to offer Apple Pay as a payment method. Combining CSS @supports with JavaScript checks ensures the most appropriate user experience across all scenarios.

It is important to note that relying solely on CSS @supports without JavaScript verification of actual Apple Pay availability can lead to issues. While @supports correctly identifies Safari browsers, it doesn't confirm the user has Apple Pay configured or is on a compatible device. A user on Safari on a Windows machine or an iPad without payment methods set up would see the button but be unable to use it, leading to confusion and potential support requests.

The combination of CSS feature detection and JavaScript capability checks provides the most robust approach to handling browser compatibility for advanced CSS features like Apple Pay buttons.

Localization and Internationalization

Apple Pay buttons automatically adapt their displayed text based on the user's language and regional settings. The button text (Buy with, Pay with, Set up, or Donate with) changes to match the Safari browser's language preference, providing a localized experience without developer intervention. This automatic localization covers all languages and regions where Apple Pay is available.

Explicit Language Control

For developers who need explicit control over the displayed language, the -webkit-locale CSS property can override the browser's automatic detection. Setting this property to a specific language code forces the button to display text in that language, which may be useful for localized checkout flows where the surrounding text is in a different language than the user's browser settings.

.apple-pay-button-localized {
 -webkit-appearance: -apple-pay-button;
 -webkit-locale: "en-GB";
 -apple-pay-button-type: pay;
 -apple-pay-button-style: black;
}

The localization system respects regional variations in payment terminology and formatting. For example, the same language code may produce different text in different regions, and date and currency formatting follows regional conventions. Testing the implementation with various language settings ensures the button integrates seamlessly with the overall localized experience of the checkout flow.

Integration with Payment Processing

The Apple Pay button is purely a UI component that triggers the Safari payment sheet. When a user clicks the button, the website must create an ApplePaySession with payment request details, handle the payment authorization events, and process the payment token returned by Apple. The button itself does not process payments--it initiates a flow that involves the website, Safari, and Apple's payment infrastructure.

Basic Payment Session Setup

const paymentRequest = {
 countryCode: 'US',
 currencyCode: 'USD',
 supportedNetworks: ['visa', 'masterCard', 'amex', 'discover'],
 merchantCapabilities: ['supports3DS'],
 total: {
 label: 'Merchant Name',
 amount: '99.99'
 }
};

if (ApplePaySession.canMakePayments()) {
 const session = new ApplePaySession(1, paymentRequest);
 
 session.onvalidatemerchant = function(event) {
 fetch('/validate-merchant', {
 method: 'POST',
 body: JSON.stringify({ validationURL: event.validationURL })
 })
 .then(response => response.json())
 .then(merchantSession => session.completeMerchantValidation(merchantSession));
 };
 
 session.onpaymentauthorized = function(event) {
 const paymentToken = event.payment.token;
 fetch('/process-payment', {
 method: 'POST',
 body: JSON.stringify({ token: paymentToken })
 })
 .then(response => response.json())
 .then(result => {
 session.completePayment(
 result.success ? ApplePaySession.STATUS_SUCCESS : ApplePaySession.STATUS_FAILURE
 );
 });
 };
 
 session.begin();
}

The payment flow requires server-side integration to validate the merchant with Apple and process the payment token after authorization. The merchant validation step establishes trust between your website and Apple, while the payment processing step sends the encrypted token to your payment processor for completion. Both steps typically involve API calls to your backend, which then communicates with Apple's servers.

Our payment integration expertise helps businesses implement Apple Pay alongside other modern payment methods to create seamless checkout experiences that reduce cart abandonment and increase conversion rates.

For businesses looking to implement comprehensive payment solutions, Apple Pay integration represents just one component of a modern, user-friendly checkout experience.

Sources

1. Apple Developer Documentation: Styling the Apple Pay Button Using CSS - Official CSS styling properties and button appearance options
2. Apple Developer Documentation: Displaying Apple Pay Buttons Using CSS - HTML structure and CSS implementation requirements
3. Apple Developer Documentation: Localizing Apple Pay Buttons Using CSS - Language and regional customization options
4. CSS-Tricks: Apple Pay Buttons in CSS - Developer perspective on implementation challenges and solutions