Download
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.