Getting Started
About Stencil
Transitioning to Stencil
Installing Stencil
Authentication & Tokens
Running Stencil Locally
Advanced Installation Options
Handlebars and Stencil
Handlebars.js Overview
Handlebars Helpers
Stencil Object Model
Stencil Objects

Using Apple Pay

Apple Pay is a digital wallet that links to a shopper’s chosen credit or debit cards. It reduces checkout friction in the same way other digital wallets like PayPal do: Once a shopper has set up Apple Pay, they don’t need to enter or transfer their actual credit or debit-card number, nor do they need to re-enter their billing, shipping or contact details.

Displaying the Apple Pay button to shoppers on your storefront is subject to Apple’s geographic constraints, supported devices and software, industry and conduct restrictions, and policies regarding store checkout flow.

Apple Pay and Stencil Themes

The Apple Pay button is included in most Stencil themes, but its default appearance might not match your store’s theme. This article explains how to do the following:

  • Script the button in themes that don’t already include it
  • Restyle the button within Apple’s guidelines

Themes Incorporating Apple Pay

Most current Stencil themes incorporate Apple Pay by default. These include Cornerstone 1.4.0 (or later) and most Theme Marketplace themes.

Themes Omitting Apple Pay

The following Stencil themes do not include Apple Pay:

  • Cornerstone 1.3.4 or earlier
  • Fortune
  • Geneva
  • Prosper
  • Solo
  • Earlier versions of Marketplace themes that have since added Apple Pay
  • Custom themes derived from any of the above

Apple Pay Button’s Location

By default, the Apple Pay button will appear on a theme’s Cart page. If the store has enabled site-wide HTTPS, the Apple Pay button will also appear in the Quick Cart modal. The Apple Pay button does not appear on the checkout page, because Apple Pay is designed as a low-friction alternative that bypasses the store’s native checkout.

Implementing the Apple Pay Button

Themes Incorporating Apple Pay

To display the Apple Pay button in themes incorporating Apple Pay, a store administrator only needs to enable Apple Pay in the BigCommerce control panel by selecting Store Setup > Payments > Digital Wallets > Apple Pay > Set up.

Themes Omitting Apple Pay

To display the Apple Pay button on the Cart page of themes omitting Apple Pay, you or a store administrator must paste enabling CSS into the footer script, as follows:

  1. Copy the CSS below.
  2. In the BigCommerce control panel, select Storefront Design > Design Options > Scripts tab.
  3. Paste the copied code into the Footer script box and select Save.
Themes Omitting Apple Pay CSS
/* don’t display the button by default */
.apple-pay-checkout-button {
  display: none;

/* display the button if apple pay is supported */
.apple-pay-supported .apple-pay-checkout-button {
  display: inline-block;

/* renders a black background with white logo */
.apple-pay-checkout-button {
  background-size: 100% 60%;
  background-repeat: no-repeat;
  background-position: 50% 50%;
  border-radius: 5px;
  padding: 0px;
  box-sizing: border-box;
  min-width: 175px;
  min-height: 32px;
  max-height: 64px;
  background-image: -webkit-named-image(apple-pay-logo-white);
  background-color: black;
  text-indent: -9000em;
  cursor: pointer;

/* for small screens, you should adjust the width of the button to
   span the width of the containing block */
@media screen and (max-width: 480px) {
  .apple-pay-checkout-button {
    width: 100%;
    height: 60px;

Apple Pay Identity Guidelines

As a condition for enabling Apple Pay, Apple requires merchants to style and display the button according to Apple Pay Identity Guidelines. For BigCommerce’s summary of the relevant guidelines, see the Integrating the Apple Pay Button support article.

Styling the Apple Pay Button

By default, a black version of the Apple Pay button will display in the storefront. However, Apple permits you to change the following three styling elements of the button, to match the style of your storefront:

  • Button background color, which must only be either white or black. A white button can have a black border.
  • Button height
  • Button width

Button Color – No Custom CSS Required

In themes incorporating Apple Pay, you or a store administrator can change the Apple Pay button’s color in Theme Editor. Select Buttons > Apple Pay > Button Color.

The drop-down list offers you the three options shown below:

  • Black (white text) – the default
  • White (black text)
  • White (black text with border)

Button Color – Custom CSS Required

In themes omitting Apple Pay, you must use custom CSS to change the Apple Pay button’s color. Here are CSS snippets to recolor the default black button.

To render the button with a white background and black text, use this CSS:

White background and black text
Apple Pay button
.apple-pay-checkout-button {
  background-image: -webkit-named-image(apple-pay-logo-black);
  background-color: white;

To render the white Apple Pay button with black text and a black border, use this CSS:

Black text and a black border
Apple Pay button
.apple-pay-checkout-button {
  background-image: -webkit-named-image(apple-pay-logo-black);
  background-color: white;
  border: .5px solid black

Button Size – Custom CSS Required

Resizing the button normally requires custom CSS. The following example shows how, by targeting the .apple-pay-checkout-button CSS selector, you can also manipulate the Apple Pay button’s width and height. (This is subject to certain constraints imposed by Apple and BigCommerce, which are listed in the example’s comments.)

Button Size
Apple Pay button
.apple-pay-checkout-button {
  width: 200px; /* apple specified minimum is 175px, there is no maximum */
  height: 60px; /* apple specified minimum is 32px, maximum is 64px */


Is your Apple Pay button configured but not appearing on the storefront?

To troubleshoot issues like this, see the Integrating the Apple Pay Button support article.