Get started with Apple Pay on the Web

Tom Grant: Welcome! My name is Tom and I'm a member of the Apple Pay E-Commerce team.

Since the launch of Apple Pay, I've worked with various technical teams to help launch merchant and payment gateway Apple Pay e-commerce integrations.

Today, I'm excited to share some of the key knowledge and best practices we've accumulated over the years, and show you how to integrate Apple Pay into your website using the Payment Request API.

Apple Pay was launched in the US in October 2014.

And since then, we have made incredible progress.

Apple Pay is now live in over 75 markets around the world, and millions of brands have it integrated into their apps and websites.

Apple Pay works by using device-specific tokenized card credentials.

Apple Pay transactions are processed just like a regular credit or debit card.

And Apple does not process Apple Pay payments, so you will still need a relationship with a payment service provider.

This might be the same provider that you use to accept payments online today.

To get a better understanding of the payment process, let's look at what happens during a transaction for Apple Pay on the web.

The transaction flow starts when your customer clicks on the Apple Pay button and the payment sheet appears, allowing them to select and confirm their details.

The customer then authenticates the transaction, and the payment data is encrypted and passed to the website.

Your website sends the Apple Pay payment object to the merchant server.

Your server receives the payment object and sends the data to your payment service provider for processing.

The payment service provider decrypts the payment data, then formats and sends an authorization message to the acquirer, who then sends the payment to the payment network.

The payment network de-tokenizes the data and sends the card number to the issuer for authorization.

The payment confirmation is then sent back through the chain, and the customer is notified by a checkmark on the payment sheet.

Now, this journey looks like a lot, but in reality, this all happens in just a few seconds.

Now that we know what is happening behind the scenes during an Apple Pay transaction on the web, let's take a look at the customer experience.

To do so, we're going to head over to the Apple Pay demo site at applepaydemo.apple.com.

This site is a great resource to get to grips with Apple Pay on the web, and allows you to set up and test transactions without your card being charged.

If you're running into challenges when working on your integration, the Apple Pay demo website is a great place to come back and help you figure it out.

This tool supports many different types of Apple Pay configuration, including shipping information, error handling, and more.

But for now, let's keep it simple and stick to the default settings to see what a basic transaction looks like.

It starts when clicking the Apple Pay button.

A modal will appear on screen, which we refer to as the payment sheet.

The customer selects their payment options and authenticates the transaction.

The transaction is sent for processing and the outcome will be displayed at the bottom of the payment sheet.

And with the payment completed, the payment sheet will dismiss.

And as easy as that, we've completed a sample payment.

Now that you've seen what a typical Apple Pay transaction looks like, let's get set up to accept Apple Pay.

We're going to be taking a look at integrating Apple Pay with the Payment Request API.

The Payment Request API provides a cross-browser standard that lets you collect payment, shipping address, and contact information from your customers.

You can then use this information to process their order.

The Payment Request API simplifies the payment journey while also ensuring security, consistency, and accessibility.

If you've integrated Apple Pay already with the Apple Pay JavaScript API, the steps in this video should be familiar to you.

So let's see what we need to do to get Apple Pay integrated.

First, I'll share the steps required to configure your environment in order to accept Apple Pay.

Next, I will show you how to implement Apple Pay, from creating a payment request through to completing a transaction.

And finally, I will take you through some tools you can use to test your Apple Pay implementation.

We've got a lot to cover, and by the end of the session, you'll have an in-depth understanding on how to integrate Apple Pay into your website.

So, let's get started by getting your environment configured.

First off, confirm that your payment service provider supports Apple Pay transactions.

They may also offer Apple Pay through their own SDK, which can be a reliable and easy way to add Apple Pay to your site.

Confirm that your server has a valid SSL certificate and is able to use TLS version 1.2 or newer.

This will be needed to communicate with the Apple Pay servers.

Finally, make sure all pages where Apple Pay is displayed are served over https://.

With these items confirmed, we can begin to create the credentials you will use in your Apple Pay setup.

Now, there are two main ways to create these credentials.

You can create and manage these yourself through the Apple Developer Portal, or register directly with your payment service provider.

To understand the specific configuration required for your website, please reach out to your payment service provider for more information.

In the following steps, I'll show you how to create and manage your credentials through the Apple Developer Portal.

Your organization may already have an Apple Developer account, especially if they have an app on the App Store already.

Ask your account admin to add you under the Users and Access sections on App Store Connect.

If your organization doesn't already have an account, sign up on developer.apple.com.

At the heart of every Apple Pay transaction is the merchant identifier, which identifies you as able to accept Apple Pay payments.

This is unique to each merchant, and we recommend using a reverse domain name-style string.

Next, create a payment processing certificate.

This will be used to securely encrypt and decrypt the payment data passed to you from your customers' devices.

You will likely receive a certificate signing request from your payment service provider to create this, as they will be the party decrypting the transaction.

Then, create a merchant identity certificate.

This certificate is used to verify your identity as a merchant when your customer initiates a payment.

Lastly, register and verify the domains and subdomains where you will display the Apple Pay button on your website.

To do this, you will enter the fully qualified domain you wish to be verified under the Merchant Domain section in the Apple Developer Portal.

A file will be generated which you will download and place at the .well-known path on your server.

You will then click the Verify button, and Apple servers will reach out to that location to verify its presence.

With your environment configured and your merchant ID created, you can now implement Apple Pay into your website.

For a better understanding of what we are building, let's take a look at a more detailed view of an Apple Pay transaction on the web.

It begins when the customer clicks or taps on the Apple Pay button.

The website creates a payment request containing all of the details for the transaction, and reaches out to the merchant server to request a new session.

Once the merchant's identity is verified, the Apple Pay servers generate and return a merchant session object.

This is passed back to the site to complete the validation process.

The customer can then confirm the details on the payment sheet and authenticate the transaction using Face ID, Touch ID, or their passcode.

The payment data is generated on the user's device and securely sent to Apple Pay servers to be encrypted with the merchant-specific payment processing certificate.

The payment data is then returned to your website.

The data is then sent to the payment service provider to be decrypted and processed.

The payment status is returned by the payment service provider.

The website notifies the user whether the transaction was a success, and if so, the payment sheet is dismissed.

This overall process can be grouped into four key stages: presenting Apple Pay, merchant validation, payment authentication, and payment processing.

First up is presenting Apple Pay, which includes showing the Apple Pay button and displaying the payment sheet.

Next up is merchant validation, where certificates are exchanged between Apple and the merchant server using two-way TLS.

Then we have payment authentication, where the payment is confirmed and generated.

And finally, the payment processing stage, which is largely handled between the merchant and the payment service provider.

Together, these steps form the basis of a typical Apple Pay payment on the web.

We will use this flow to structure our approach to implementing Apple Pay.

Let's start by presenting Apple Pay as a payment option on our website.

You should display the Apple Pay button whenever your customer is using a supported device.

To check if your customer's device supports Apple Pay, call ApplePaySession.canMakePayments.

It's important to consider which type of button best fits your checkout journey.

The Apple Pay API provides many button types and a variety of styles to use in your website, so you can choose the button that best fits the flow of your purchase experience.

Use the system-provided buttons to guarantee you are using an Apple-approved font, color, caption, and style.

The button can be imported into your site using either JavaScript or CSS, and the style, type, and localization can easily be set with attributes.

To add the button using the JavaScript SDK, load the button script from the content delivery network.

You can set CSS properties, such as the border radius, to better align the button with your current UI.

Finally, add the Apple Pay button element to the page, setting the attributes for the style, type, and locale.

For this example, we have chosen to use the black button style with the "Check Out with Apple Pay" caption and localized it to German.

To view the available Apple Pay button options, let's go back to the Apple Pay demo site that we took a look at earlier.

Here, you can quickly and easily change the Apple Pay button's attributes and CSS properties, showing the result in real time at the bottom of the page.

This is a quick and easy way to generate Apple Pay buttons and copy and paste the code onto your website.

Here, you can select the type of button.

I have chosen black.

Then you can choose the type to best fit the situation.

And the last attribute would be the language.

Let's localize this to German like in the previous example.

Further down, you have the CSS properties, such as the button width, height, corner radius, and padding.

The configuration for the button is displayed and updated within the code block just below the options.

This can be copied and pasted into your existing code.

There are a number of different payment request types available, allowing you to present additional information about the transaction to the customer.

A typical transaction is for a one-time payment, but Apple Pay also provides payment request options for recurring payments, such as subscriptions; automatic reload payments, such as store card top-ups; and deferred payments, such as for a preorder.

For now, let's look at building a payment request for a one-time payment.

To accept Apple Pay payments using the Payment Request API, you first need to specify it as a payment method using its identifier, in this case apple.com/apple-pay.

Alongside the identifier, we also need to include some associated data.

This includes a version number, and we recommend using the latest version available, as this comes with all of the latest Apple Pay functionality.

Check out developer.apple.com for the latest information.

We also need the merchantIdentifier configured earlier, what capabilities and networks you wish to support, and the country code where the payment will be processed.

It is especially important that this is set correctly to ensure a compatible cryptogram is generated in PSD2 markets.

You can optionally include required contact details for either the customer's billing address, shipping address, or both.

Here, we are requesting the customer's shipping address.

However, trust and privacy are extremely important to think about when requesting customer data.

Only request information necessary to service the transaction to ensure you are getting the best conversion with Apple Pay.

You next need to create a details object for the transaction.

This includes display items, where you can include taxes, charges, and discounts; shipping options to allow the customer to choose how their order is shipped, which is great for offering an express checkout option; and finally the total, containing the currency and amount to be charged, and a label containing the name for the merchant.

The merchant name value should be the name the customer associates with the business, and will be displayed next to the word "pay" in the payment sheet.

The details object is also where you would include any modifiers for the transaction.

Modifiers contain transaction details that apply only under certain conditions.

For example, you may wish to add a surcharge for paying with a credit card.

If you wanted to request a recurring payment, such as for a subscription, this is also where you would include the details of the recurring request.

We can now bring all of these elements together to initiate a new payment request.

Create a new payment request object and pass in the methods, details, and options into the constructor.

As we've explored, one of the great benefits of Apple Pay is that it can be used as an express checkout option to help improve conversion.

You will want to make the experience as seamless as possible.

To do so, you should check that the user has a card available to make the payment before displaying the Apple Pay button.

This can be done by using Payment Request's canMakePayment method.

This method checks that the customer is on an Apple Pay-supported device and browser, and resolves to true only if the customer has a card available to make a payment.

When the customer taps on the Apple Pay button, you should use the show method to display the payment sheet.

Once the payment sheet is displayed, it shows the processing animation and immediately starts the merchant validation process.

So, let's see what that involves.

The merchant validation process is completed for every Apple Pay on the Web transaction and is an important security measure to ensure that the payment is being processed by a legitimate and authorized merchant.

This helps protect users from fraudulent transactions and enhances the overall security of the payment process.

There are three parties in the merchant validation process: the merchant website, the merchant server, and the Apple Pay server.

When the Apple Pay button is pressed, merchant validation is automatically triggered with a call to the onmerchantvalidation handler.

Inside of this handler, a call will need to be made to an endpoint on the merchant server asking for a new session to be created using the static hostname, apple-pay-gateway.apple.com as the validation URL.

To ensure your certificates remain secure, the request to the Apple Pay servers must come from the merchant server and not from the browser directly.

This is so your merchant identity certificates remain secure, are not shared with users and other parties, and they cannot imitate your website.

To request a new session, the merchant server builds a session request payload and posts it to the Apple Pay servers using two-way TLS.

The certificate used for this connection is the merchant identity certificate.

Once the merchant's identity is validated, a new merchant session object is generated and returned to the server.

This object should not be modified in any way, otherwise merchant validation will fail.

The merchant session object is then passed back to the browser.

You then pass the merchant session object to the completion method to complete the merchant validation process.

The system will then enable the payment sheet for customer interaction.

Let's see how to accomplish this process in your code.

As soon as the Apple Pay button is pressed, the onmerchantvalidation handler will be triggered.

Inside of this handler, a call should be made to an endpoint on the server to handle requesting the merchant session.

When received by the browser, the merchant session object is then passed as JSON and used in the complete callback to finish the process.

Successful merchant validation results in the payment sheet updating to notify the customer that the payment is ready to be confirmed.

Unsuccessful merchant validation will cause the payment sheet to dismiss right after the customer has clicked the Apple Pay button.

If you're having trouble with merchant validation, you can use the console in Safari's built-in Web Inspector tool to log errors and objects when working on merchant validation.

If you've never used it before, Web Inspector provides a powerful set of tools to debug and inspect web pages, web extensions, and WKWebViews.

While you run Web Inspector on your Mac, you can use it to debug your code running on any connected device.

To learn more about Web Inspector, check out "Rediscover Safari Developer Features" from WWDC23.

With merchant validation covered, let's now dig into payment authentication.

When the user changes or updates fields on the payment sheet, these selections are shared through event handlers, allowing the website to respond to user input.

Examples of these handlers are the customer-selected payment method, including coupon codes; the chosen shipping option is updated; or there are changes to the location of their shipping address.

When the browser calls one of these handlers, you have 30 seconds to process it and call the updateWith callback function.

Ensure any server calls to check shipping address validity occur in this 30-second window.

If the callback function is not called in this time, a message will appear on the payment sheet stating that the payment could not be completed.

Let's look into the onshippingaddresschange handler in more detail.

Before the user has authenticated the transaction, redacted shipping contact information is shared with the merchant website.

For privacy purposes, this includes only the necessary data for calculating final transaction costs, such as taxes or shipping.

Once you've received this information, you can calculate relevant totals.

If you determine there is a problem with the address or contact information provided by the customer, you can also create your own customized error messages.

Error messaging allows you to highlight the fields that require attention, and provides clear, actionable guidance to make it easier for customers to resolve problems quickly and complete their transaction.

When Apple Pay provides you with the data, you can perform the same validation as you would for any manual input fields that you have today on your website.

When you determine that there's a problem with the user's address or contact information, you can use ApplePayError to create a customized error message.

The details you provide in an ApplePayError include an error code that identifies the area of the payment sheet with the error; contact field, which is the specific field on the payment sheet with the error; and finally the custom message to display on the payment sheet.

The ApplePayError is then passed back into the update with callback from the event.

You can also verify the user's full address and contact information after they have authorized the transaction with Face ID, Touch ID, or their passcode.

If there is an issue with the user's address information, you can allow them to retry the transaction and highlight the issues that need to be fixed.

If there are error objects appended to the errors array, you can prevent the user from checking out until the information is in a format that your validation rules expect.

It is recommended to be as flexible as possible with the address formats to ensure your users can perform a successful transaction.

Also inside of the Apple Pay payload is the payment token, containing the necessary information to process the transaction.

If you are performing the decryption of the payment token, you will do so at this point.

In most cases, the payment service provider will handle the decryption process, and you can send the token to them directly for processing.

This token will also contain the display name of the card used for the transaction, which includes the network and last four digits of the card number.

This will differ from the device-specific token and is what you should use to indicate to the customer what card was used for the transaction, such as in the order confirmation email or on their receipt.

So, that was payment authentication.

Let's finish up by looking at payment processing.

Once the process has been performed by the payment service provider, the result must be passed into the complete method to notify the customer of the outcome.

For a successful transaction, this would be done by passing in success.

This would update the payment sheet with a checkmark, and then dismiss it to complete the Apple Pay payment process.

Sometimes, a payment might fail, in which case you can pass fail into the response handler.

The payment sheet displays an exclamation point and the customer is prompted to try again, or you can dismiss the payment sheet.

And with that, we have now covered the four primary steps required to implement Apple Pay.

But of course, no discussion of implementation is complete without a mention of testing.

So finally, let's take a quick look at testing your solution.

To do so, head over to the Apple Pay sandbox testing site.

There, you'll find sandbox credit card numbers that can be provisioned on devices to test your front-end integration and decryption process.

Keep in mind that sandbox credit cards will not be processed successfully if sent to a production payment processing environment.

Sandbox credit cards are great for testing.

However, we recommend that tests are performed with real cards prior to pushing your implementation to production.

Testing with real cards ensures your full end-to-end flow of the payment process works as you would expect.

And that wraps up testing and my overview of getting started with Apple Pay on the Web.

I've covered a lot, from configuration and implementation, to sandbox testing.

But before I leave you, I have some next steps to help you continue your Apple Pay integration journey.

First, be sure to visit the Apple Pay demo site.

It's the best starting point when building your Apple Pay solution.

Review the Merchant Integration Guide linked to this session.

It provides a ton of details on each step on the path to a well-designed implementation of Apple Pay.

And finally, check out the Apple Pay section of the Human Interface Guidelines.

There, you'll find detailed user interface guidance on how to present Apple Pay and the payment sheet on your website.

Thanks for joining me, and I wish you the best with your Apple Pay integration.