Apple Pay on the Web

Human Interface Guidelines

With the release of macOS Sierra and iOS 10, Apple Pay is now available in Safari for iPhone, iPad, and Mac. Apple Pay offers customers a secure, easy way to pay on the web. Use these guidelines to learn how to design your website for Apple Pay.

How Apple Pay on the Web Works

Websites that accept Apple Pay incorporate it into the purchasing flow. During checkout, a payment sheet shows the credit or debit card linked to Apple Pay, purchase amount (including tax and fees), shipping options, and contact information. Users make any necessary adjustments, authorize payment, and complete the purchase using securely stored credentials on an iPhone, an iPad, or a MacBook Pro with Touch ID. On other Macs, the purchase is confirmed with the user's nearby iPhone or Apple Watch that has Apple Pay enabled.

Any website offering Apple Pay must include a privacy statement and adhere to the Apple Pay on the Web Acceptable Use Guidelines. For developer guidance, see Apple Pay Programming Guide and Apple Pay JS.

iOS and watchOS apps can also accept Apple Pay. For app-specific design guidance, see the iOS Human Interface Guidelines for Apple Pay and watchOS Human Interface Guidelines for Apple Pay. 1

Buttons

Several button styles are available for use by websites that accept Apple Pay.

Apple Pay or Buy with Apple Pay button. Use one of these buttons on your website wherever users initiate payment, like a product detail page or shopping cart page. If Apple Pay has been set up, clicking this button should display a payment sheet, where users can complete the checkout process. If Apple Pay hasn't been set up, clicking this button should initiate the process of adding a card—it's best to display a Set up Apple Pay button in this scenario for clarity.

Set up Apple Pay button. Consider showing this button on a checkout page when the device supports Apple Pay, but Apple Pay hasn’t been set up yet. Clicking the button should initiate the process of adding a card. After the user adds a card, they'll return to the checkout process to complete their transaction. Although other Apple Pay buttons exhibit the same behavior when Apple Pay hasn’t been set up, the Set up Apple Pay button provides the most clarity. This button can also be displayed on a non-checkout page like a user profile screen, or in conjunction with advertising an Apple Pay-related promotion or benefit like a banner that reads "Use Apple Pay and save $5!"

Donate with Apple Pay button. Approved nonprofits can use this button to facilitate donations. On devices running older systems that don't support the Donate with Apple Pay button, display the Apple Pay button instead.

Styles

You have several options for displaying Apple Pay buttons.

Black. Use on white or light-colored backgrounds that provide sufficient contrast. Don’t use on black or dark backgrounds.

White with outline rule. Use on white or light-colored backgrounds that don’t provide sufficient contrast. Don’t place on dark or saturated backgrounds.

White. Use on dark or colored backgrounds that provide sufficient contrast.

Size and Position

Maintain the minimum width. The minimum width for all Apple Pay buttons is 32pt (32px @1x, 64px @2x).

Maintain minimum clear space. The minimum amount of clear space required around an Apple Pay button is 1/10 of the button's height. Other content, such as graphics and text, should not infringe on this space.

Display the Apple Pay button prominently. Make Apple Pay buttons the same size or larger than other payment buttons. Ideally, scrolling shouldn't be required to see the Apple Pay button.

Position Apple Pay buttons consistently in regard to Add to Cart buttons. Place the Apple Pay button to the right of or above an Add to Cart button.

Apple Pay Mark

Use the Apple Pay mark graphic to communicate that Apple Pay is an available payment option when showing other payment options in a similar manner. Download the Apple Pay mark graphic and its usage guidelines here.

Referring to Apple Pay in Text

You can use plain text to promote Apple Pay and indicate that Apple Pay is a payment option.

Capitalize Apple Pay in text as it appears on the Apple Trademark list. Use two words with an uppercase A, an uppercase P, and lowercase for all other letters. Display Apple Pay entirely in uppercase only when doing so is necessary for conforming to an established, typographic interface style, such as in an app that capitalizes all text. See Apple Trademark List.

Never use the Apple logo to represent the name Apple in text. In the United States, use the registered trademark symbol (®) the first time Apple Pay appears in body text. Don't include a registered trademark symbol when Apple Pay appears as a selection option during checkout.

Coordinate the font face and size with your website. Don't mimic Apple typography. Instead, use text attributes that are consistent with the rest of your website.

Don't translate Apple Pay. Always use Apple trademarks in English, even when they appear within non-English text.

Example text
Correct usage Purchase with Apple Pay
Correct usage Purchase with Apple Pay®
Incorrect usage Purchase with ApplePay
Incorrect usage Purchase with  Pay
Incorrect usage Purchase with APPLE PAY

Presenting Apple Pay as a Payment Option

Offer Apple Pay on all devices that support it. Show the Apple Pay button on all capable devices. If the device doesn’t support Apple Pay, don’t present Apple Pay as a payment option.

Use only the Apple-provided API and CSS to display Apple Pay buttons. Unlike a button graphic, the buttons produced by the API always have the correct appearance. On devices running older systems that support Apple Pay on the web but don't include the API, use the recommended CSS to display the buttons, as described in ApplePaySession.

Don’t disable or hide an Apple Pay button. If an Apple Pay button can’t be used yet, such as when a product size or color hasn’t been selected, gracefully point out the problem after the user clicks the Apple Pay button.

Use the Apple Pay mark only to communicate that Apple Pay is accepted. The mark doesn’t facilitate payment. Never use it as a payment button or position it as a button.

Inform search engines that Apple Pay is accepted. If your website uses semantic markup to provide product details to search engines, list Apple Pay as a payment option.

For developer guidance, including how to determine whether Apple Pay on the web is available, see the reference documentation for ApplePaySession.

Streamline the Checkout Process

People appreciate using Apple Pay to make purchases quickly and easily. Provide a payment sheet that lets them promptly authorize payment and complete the transaction.

Make Apple Pay the default payment option when possible. If Apple Pay is supported and set up, assume the person wants to use it. Consider presenting Apple Pay as the first or only payment option, displaying it larger than other options, or using a line to visually separate it from other choices.

Accelerate single-item purchases with Apple Pay buttons on product detail pages. In addition to offering a shopping cart, consider putting Apple Pay buttons on product detail pages so users can quickly purchase an individual item. Purchases initiated in this way should be for an individual item only, and should exclude any items that already reside in the user's shopping cart. If the user's shopping cart contains an item purchased directly from a product detail page, remove the item from the cart after the purchase is complete.

Accelerate multi-item purchases with express checkout. Consider providing an express checkout feature that immediately displays the payment sheet, allowing users to quickly purchase multiple items using a single shipping speed and destination.

Ensure a smooth checkout process. Collect necessary information, like color and size options, before people reach the Apple Pay button. When additional information is needed at checkout time—perhaps because the user forgot to choose an option—gracefully point out the problem and help the user correct it. Use highlighting or warning text to identify missing information, and automatically navigate to the problematic field so the user can quickly correct it and complete their purchase.

Collect optional information before checkout begins. There’s no way to input data on the payment sheet, so collect any optional information such as promo codes, redemption codes, gift messages, and delivery instructions ahead of time or even after the purchase is complete.

Gather multiple shipping speeds and destinations before showing the payment sheet. The payment sheet lets people select a single shipping speed and destination for an entire order. If your customers can choose different shipping speeds and destinations for individual items in an order, collect those details before Apple Pay checkout begins, instead of on the payment sheet.

Prefer information from Apple Pay. Assume that Apple Pay information is complete and up to date. Even if your website has existing contact, shipping, and payment information, consider fetching the latest from Apple Pay during checkout to reduce potential corrections.

Display an order confirmation or thank-you page. After checkout, use an order confirmation page to thank the user for the purchase, provide details about when the order will ship, and indicate how to check its status. Listing Apple Pay on the confirmation page isn’t necessary, but if you do list it, show it after the last four digits of the account used to process the transaction or as a separate note. For example: "1234 (Apple Pay)" or "Paid with Apple Pay."

Don't require account creation prior to purchase. If you want people to register for an account, ask them to do so on the order confirmation page. Prepopulate as many registration fields as possible using information provided by the payment sheet during checkout.

Customize the Payment Sheet

You can customize the contents of the payment sheet according to the information needed to complete the transaction.

Only present and request essential information. People may get confused or have privacy concerns if the payment sheet includes extraneous information. For example, it makes sense to see a contact email address but not a shipping address if the purchase is a gift card that will be delivered electronically. Showing or asking for a shipping address in this scenario may give the false impression that something will be physically delivered.

Let people choose the shipping method in the payment sheet. To the extent space permits, show a clear description, a cost, and, optionally, an estimated delivery date for each available option.

Use line items to explain additional charges, discounts, and pending costs. A line item includes a label and cost. Don’t use line items to show an itemized list of products that make up the purchase.

List add-on donations as separate line items. If your app lets people add approved nonprofit donations to purchases, listing the donations separately provides maximum clarity. For related guidance, see Accepting Donations.

Keep line items short. Make line items specific and easily understandable at a glance. Whenever possible, fit line items on a single line.

Provide a business name after the word PAY on the same line as the total. Use the same business name people will see when they look for the charge on their bank or credit card statement. This provides reassurance that payment is going to the right place. For example: PAY [COMPANY_NAME].

Provide the end merchant name when applicable. If your website acts as an intermediary and isn’t the end merchant for a payment, clearly indicate this in the following format: PAY [END_MERCHANT_NAME] (VIA [YOUR_WEBSITE_NAME]).

Clearly disclose when additional costs may be incurred after payment authorization. On some websites, the total cost may be unknown at checkout time. For example, the price of a car ride based on distance or time might change after checkout. Or, a customer might want to add a tip after a product has been delivered. In situations like these, provide a clear explanation in the payment sheet and a subtotal marked as "AMOUNT PENDING." If you are preauthorizing a specific amount, also make sure the payment sheet accurately reflects this information.

Handle payment errors gracefully. If an error occurs during checkout, help people resolve it quickly so they can complete their transaction. See Data Validation.

Provide your website icon for the payment sheet. Many websites provide an icon that can be displayed with bookmarks, in URL fields, or on a device’s Home screen. On websites that support Apple Pay, this icon is also displayed on the payment sheet of the connected device that’s used to authorize payment. It provides visual reassurance that payment is going to the right place. Provide your website icon in the following sizes for use on the payment sheet:

Scale factor Icon size
@2x 120px x 120px
@3x 180px x 180px

For information about implementing website icons, see Specifying a Webpage Icon for Web Clip in Safari Web Content Guide.

In-Store Pickup

If applicable, you can allow people to purchase items for pickup in a physical store.

Gather pickup details before displaying the payment sheet. There’s no way to let people choose a pickup location, date, or time on the payment sheet, so collect this information before presenting the Apple Pay button.

Show in-store pickup information in the shipping area of the payment sheet Change the SHIPPING label to PICKUP and display the store name, address, and phone number. Provide this information in the order confirmation or thank-you page too.

Supporting Subscriptions

Your website can use Apple Pay to request authorization for a recurring fee. This may be a fixed amount such as a monthly movie ticket subscription, or a variable amount such as a weekly produce order. The initial authorization can also include discounts and additional fees.

Clarify subscription details before showing the payment sheet. Before asking users to authorize a recurring payment, make sure they fully understand the billing frequency and any other terms of service.

Include line items that reiterate billing frequency, discounts, and additional upfront fees. Use these line items to remind users what they're authorizing.

Clarify the current payment amount in the total line. Make sure users know what they're being billed at the time of authorization.

Only show the payment sheet when a subscription change results in additional fees. When the user changes a subscription, authorization isn't necessary if the cost decreases or remains the same.

Accepting Donations

Approved nonprofits can use Apple Pay to accept donations.

Use a line item to denote a donation. Display a line item on the payment sheet that reminds users they're authorizing a donation, for example, DONATION $50.00.

Streamline checkout by offering predefined donation amounts. You can reduce steps in the donation process by offering one-click recommended donations, like $25, $50, $100. Be sure to include an Other Amount option too, so users can customize the donation if they prefer.

Error Handling

Provide approachable, actionable guidance when problems occur during checkout, so users can resolve problems quickly and complete their transaction.

Data Validation

Your website can respond to user input when the payment sheet appears, when the user changes certain field values on the payment sheet, and after the user authenticates the transaction. Use these opportunities to check for data entry problems and to provide clear and consistent messaging.

Payment sheet error messaging

Custom detail view error messaging

When data is invalid, red system-provided error messaging calls attention to relevant fields on the payment sheet. The user can click a field to view additional details and resolve the problem. Provide customized error messages for the detail view that appears when the user clicks a problematic field.

For developer guidance, see Apple Pay JS.

Note For privacy reasons, your app has limited access to data until the user attempts to authorize a transaction. Prior to authorization, only the card type and a redacted shipping address are accessible. It’s critical to report errors to the user when authorization fails, but to the extent possible, your app should also attempt to validate available information and report problems before authorization.

Avoid forcing compliance with your business logic. Design a data validation process that’s intelligent enough to ignore irrelevant data and infer missing data whenever possible. For example, if your app requires a five-digit zip code but the user enters a Zip+4 code, ignore the additional digits rather than asking for a correction. Accept state names in multiple formats (a user should be able to enter California or CA without producing an error). Handle phone numbers in multiple formats (with and without dashes, with and without a country code).

Provide accurate status reporting to the system. When a problem occurs, it’s essential that your app accurately indicate the type of problem so the system can show an appropriate error message on the payment sheet. This is done by accompanying your custom error message with an appropriate status code. For developer guidance, see Apple Pay Status Codes.

Succinctly and specifically describe the problem when data is invalid or incorrectly formatted. Reference the relevant field and indicate exactly what’s expected. For example, if the user enters an invalid zip code, instead of showing “Address is invalid”, show a specific message like “Zip code doesn’t match city”. If the shipping address is unserviceable, indicate why—“Shipping not available for this state”. Use noun phrases with sentence-style capitalization and no ending punctuation. Keep messages short to avoid truncation—strive for 128 characters or less.

Inform the user when a required field is empty. Call attention to a blank required field with a short descriptive message like “Zip code is required”.

Payment Processing

Handle timeouts gracefully. A transaction times out and the user is notified if you are unable to complete payment processing within 30 seconds. If a timeout is encountered, you should cancel the in-progress payment, redisplay the checkout page, explain the problem, and allow the user to retry the payment process.