Apple Pay Integration Guide

Getting Started: Requirements

Before you start, ensure you have successfully integrated the verification file from the previous steps. Additionally, ensure you have read through the Account Setup & Requirements section to understand any additional requirements.

1. Construct the request

   To register, you will need to send a POST request to an endpoint with specific parameters. Follow the API documentation, accessible via the navigation menu, for parameters, headers, and other necessary details to register.

2. Register your account

   The API documentation also includes testing and production-ready registration POST request and response examples to help you understand and navigate the registration process seamlessly.

3. Store the response identifier

   The response payload for a merchant registration includes a unique identifier known as the partnerInternalMerchantIdentifier. This identifier should be securely stored in your server environment, where your website or backend data is hosted. It should be encrypted and accessible only to authorized personnel. This identifier is crucial for all Apple Pay sessions associated with your domain as it ensures transactional security and identification.

Registration Parameters

Essential parameters required for merchant registration via POST request, including examples for testing and production environments.

Designing Apple Pay

Get started integrating Apple Pay on your website, from setup to button styling, using the step-by-step tutorial guidance below and navigation guide steps. Resources for additional styles and customisations can also be found in the next steps. 

1. Necessary Scripts

   Integration starts by incorporating two scripts into your HTML head section: jQuery and the Apple Pay SDK. These allow seamless interactions with the Apple Pay servers.

2. Button Implementation

   The 'apple-pay-button' element will need to be added to your website, configured to fit your needs, to ensure proper functionality.

3. Button Styling

   The Apple Pay button can be customized using CSS in the style tag in your HTML. Adjust its appearance to align with your site's design for a consistent user experience.

Including Necessary Scripts

This SDK allows you to create the Apple Pay button and manage essential interactions with the Apple Pay servers. Firstly, incorporate jQuery, which is a widespread JavaScript library that facilitates various tasks like HTML document traversal, event handling, and animation. Add it to the head section of your HTML:

Button Implementation

The Apple Pay button is a key element for the user to initiate a payment with Apple Pay. Here, we provide a detailed guide on how to successfully integrate the 'apple-pay-button' into your website.

Get started by adding the code below to your website. This includes all basic attributes like 'buttonstyle', 'type', and 'locale', which allow you to customize the button's appearance and localize it to match your user's language settings.

Styling the Apple Pay Button with CSS

Apple Pay offers several attributes for customizing the button's appearance and behavior, such as 'buttonstyle', 'type', and 'locale'. Here's an example of how to use these attributes:

Defining CSS Styles: The <style> HTML element helps define CSS styles in your document. Within this tag, create the CSS properties for the Apple Pay button:

Applying the Styles: Each CSS property affects a different aspect of the Apple Pay button's appearance:

Payments Overview

This tutorial will involve creating a new project folder in your preferred code editor - we recommend Visual Studio Code. You'll include the index file you crafted in the previous step, as well as two additional files: payment.php and session.php.

1. Checking Apple Availability

   Begin your Apple Pay integration by ensuring the necessary Apple Pay JavaScript API is available and enabled on your user's device. This step is vital in providing a seamless experience for your customers, and ensuring your setup proceeds without hitches.

2. Creating a Payment Request

   Associate an 'onClick' function with the Apple Pay button to initiate a new Apple Pay session. This session establishes a secure communication link with Apple's servers, validates your website and kickstarts the payment request process.

3. Complete Merchant Validation

   Merchant validation is a crucial step in the Apple Pay setup process. It confirms the legitimacy of your website and ensures a secure environment for transactions. During this phase, your website must make a server-to-server request to Apple's validation URL, receive a session object in response, and return it to the Apple Pay session. This two-way handshake builds a foundation of trust for all subsequent transactions.

4. Authorizing Payments

   Once your Apple Pay session is established, you can execute a payment request. This triggers the Apple Pay payment sheet on the user's device, allowing them to authorize the payment securely. Once authorized, it's over to you and your backend server to process and finalize the transaction.

Checking for Apple Pay Availability

As we move forward, our initial task is to ascertain if the user's device supports Apple Pay. The 'canMakePayments' method, which we'll use in the forthcoming code snippets, is instrumental in achieving this.

The 'canMakePayments' function verifies if the device is compatible with Apple Pay. However, it does not confirm the existence of any provisioned cards in the Wallet. Available from Safari Desktop 10.0+ and Safari Mobile 10.0+, this method can be invoked at any time.

Now, let's inspect the code required to perform these checks:

Creating a Payment Request

The essence of an Apple Pay transaction is the Payment Request, a data structure that contains all the necessary information for the purchase. This includes merchant details, supported payment networks, the total amount to be charged, and currency. It's crucial to note that Total Processing does not currently support recurring payments.

Line items, including the total, are also part of the Payment Request. Ensure your total amount is greater than or equal to zero with a non-empty label. The label should match your business name as customers would see it on their bank or credit card statement.

When setting up the Payment Request, the "amount" field is required. It must follow the regular expression -?[0-9]+(\.[0-9][0-9])? You can define the currency for the entire transaction, including line items, by setting the "currencyCode" property.

Here's an example of a Payment Request. This simple request sets up a payment for £0.01 in the UK, with the merchant supporting 3DS and accepting Visa, Mastercard, and Amex.

Creating a Session

An Apple Pay Session, in the context of Apple Pay's JavaScript API, is the primary object that your website interacts with when processing an Apple Pay transaction.

When a user clicks the Apple Pay button on your website, you create an instance of an Apple Pay Session. This object manages the interaction between your website and the user's Apple device, facilitating the display of payment sheets, collection of user authorizations, and finally the processing of the transaction.

1. Starting an Apple Pay session is the entry point for Apple Pay on the web. You will first need to create an Apple Pay button with an assigned ID like this:

   Attention needed

   When creating sessions, Please ensure you always use the merchantidentifier that is associated to the domain you're creating a session on. It is best practice to comment your merchantidentifiers as 'Test' or 'production' and include the domain names for each.

   
   
   1 <apple-pay-button

   2 id="apple-pay-button"

   3 buttonstyle="black"

   4 type="plain"

   5 locale="en">

   6 </apple-pay-button>

   Copy

2. Upon the readiness of your document, you'll need to add a click event listener to the button ID, which will start the Apple Pay session. This happens in your main script file.

   
   
   1 $(document).ready(function () {

   2 console.log("ready");

   3 $("#apple-pay-button").click(function () {

   4 console.log("starting Apple Pay session");

   5 var session = new ApplePaySession(3, JSON.parse(paymentRequest));

   6 session.begin();

   7 console.log(session);

   8 });

   Copy

3. After starting the Apple Pay session, you'll need to create a session on the server-side with validation URL. Here's an example of how to do this in PHP:

   
   
   1 ...

   2 // Make sure your postData information is correct. Replace this with your information.

   3 $postData = [

   4 "merchantIdentifier" => $merchantIdentifier,

   5 "displayName" => "Insert Here",

   6 "initiativeContext" => 'Insert Here',

   7 "initiative" => "web"

   8 ];

   9 ...

   10 $response = curl_exec($ch);

   11 curl_close($ch);

   12 echo $response;

   13 exit;

   14 ...

   Copy

Merchant Validation

Merchant validation is a key step to ensure a secure Apple Pay transaction. This process involves Apple providing a validation URL, to which your server-side code must send a POST request. The purpose of this request is to verify your merchant session, which involves proving to Apple that you, as a merchant, are permitted to use Apple Pay and that you're the entity you say you are. This is done in the background, unbeknownst to the user.

Let's examine the code for the onvalidatemerchant function. This function undertakes the merchant validation process. Upon receiving the validationURL from Apple, it sends a POST request to your PHP session script. The script in turn sends a POST request to the validation URL and returns the response. This response (a session object), when received by your JavaScript, is then passed back to Apple to complete the validation process.

Payment Authorization

After the merchant validation, the next significant event in the Apple Pay lifecycle is the payment authorization. The user is prompted to authenticate using Touch ID, Face ID, or their device passcode. Upon successful user authentication, Apple Pay creates a payment token. This token contains the necessary payment information encrypted within it.

The onpaymentauthorized event handler is triggered when a payment is authorized. Within this handler, the payment token is sent to your server-side code for further processing. Here's how you handle payment authorization in your JavaScript code:

Completion

Completion is the final step in the payment session. After your server processes the payment with the payment token it received during the authorization step, it needs to send a response back to the Apple Pay JavaScript running on your website. This response should indicate whether the payment processing was successful or not. Depending on this response, Apple Pay completes the payment and provides an appropriate message to the user.

In your JavaScript code, you can see that we call the completePayment method on the session object with the payment authorization result. The authorization result includes a status and an optional list of errors. Let's review this important step in the code:

Cancellation

In an event where a user decides to cancel the payment process, it's essential to handle such cases in a manner that maintains a positive user experience. This is why the Apple Pay Session API provides an event handler for cancellation events, allowing developers to define custom behavior or fallbacks when a user cancels the payment process.

In your JavaScript code, you will notice the oncancel event handler for the Apple Pay session. This handler is called when the user decides to cancel the payment session. Here's the cancellation handler in your code: