ApplePaySession

Creating a Session

Before you display an Apple Pay button or create an Apple Pay session, you must ensure that the Apple Pay JavaScript API is available and is enabled on the current device.

To check whether the Apple Pay JS API is available, verify that the window.ApplePaySession class exists. Then call either its canMakePayments or canMakePaymentsWithActiveCard methods.

• The canMakePayments method simply verifies that the device is capable of making Apple Pay payments. It does not verify that the user has a provisioned card on the device. This method can be called at any time.

• The canMakePaymentsWithActiveCard method verifies both that the device is capable of making Apple Pay payments, and that the user has at least one provisioned card. This method asynchronously contacts the Apple Pay servers as part of the verification process. You can only call this method if you want to default to Apple Pay during your checkout flow, or if you want to add Apple Pay buttons to your product detail page.

Listing 1 shows how to check the canMakePaymentsWithActiveCard method before displaying an Apple Pay button.

if (window.ApplePaySession) {
   var merchantIdentifier = 'example.com.store';
   var promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantIdentifier);
   promise.then(function (canMakePayments) {
      if (canMakePayments)
         // Display Apple Pay Buttons here…
}); }

When creating a new ApplePaySession object, you must supply two parameters: a version number and payment request object.

• Version number. The version of the API you are using. The version number allows the extension of the API in a backward compatible way. The current API version number is 1.

• Payment Request. A PaymentRequest dictionary that contains all the information needed to display the payment sheet.

Creating an ApplePaySession object throws a JavaScript exception if any of the following occur:

• Any Apple Pay Javascript API is called from an insecure page.

• You pass an invalid payment request. Payment requests are invalid if they contain missing, unknown, or invalid properties, or if they have a negative total.

After the session is created, call its begin method to show the payment sheet. The begin method can only be called when a payment is explicitly requested by the user, for example, inside an onclick event. Otherwise it throws a JavaScript exception.

Listing 2 shows creating a new Apple Pay session and displaying the payment sheet.

var request = {
  countryCode: 'US',
  currencyCode: 'USD',
  supportedNetworks: ['visa', 'masterCard'],
  merchantCapabilities: ['supports3DS'],
  total: { label: 'Your Label', amount: '10.00' },
}
var session = new ApplePaySession(1, request);

Displaying the Apple Pay Button

Use the CSS templates provided below to display an Apple Pay button on your web page. When a user clicks or taps an Apple Pay button, it must always invoke the Apple Pay payment sheet.

Choosing a Button Style

Refer to the Apple Pay Identity Guidelines for information on how to use Apple Pay buttons and the button styles that are available.

Use the code in Listing 2 for a logo only button, or the code in Listing 3 for a "Buy with" button.

/* Template for logo only button (height independent). */
/* HTML */
<div class="apple-pay-button apple-pay-button-white"></div>
/* CSS */
.apple-pay-button {
    display: inline-block;
    background-size: 100% 60%;
    background-repeat: no-repeat;
    background-position: 50% 50%;
    border-radius: 5px;
    padding: 0px;
    box-sizing: border-box;
    min-width: 200px;
    min-height: 32px;
    max-height: 64px;
}

.apple-pay-button-black {
    background-image: -webkit-named-image(apple-pay-logo-white);
    background-color: black;
}

.apple-pay-button-white {
    background-image: -webkit-named-image(apple-pay-logo-black);
    background-color: white;
}

.apple-pay-button-white-with-line {
    background-image: -webkit-named-image(apple-pay-logo-black);
    background-color: white;
    border: .5px solid black;
}

Use the following template for a "Buy with" button.

/* Template for "Buy with" button with height: 32 */
/* HTML */
<div class="apple-pay-button-with-text apple-pay-button-white-with-text">
  <span class="text">Buy With</span>
  <span class="logo"></span>
</div>
/* CSS */
.apple-pay-button-with-text {
    --apple-pay-scale: 1; /* (height / 32) */
    display: inline-flex;
    justify-content: center;
    font-size: 12px;
    border-radius: 5px;
    padding: 0px;
    box-sizing: border-box;
    min-width: 200px;
    min-height: 32px;
    max-height: 64px;
}
.apple-pay-button-black-with-text {
    background-color: black;
    color: white;
}
.apple-pay-button-white-with-text {
    background-color: white;
    color: black;
}
.apple-pay-button-white-with-line-with-text {
    background-color: white;
    color: black;
    border: .5px solid black;
}
.apple-pay-button-with-text.apple-pay-button-black-with-text > .logo {
    background-image: -webkit-named-image(apple-pay-logo-white);
    background-color: black;
}
.apple-pay-button-with-text.apple-pay-button-white-with-text > .logo {
    background-image: -webkit-named-image(apple-pay-logo-black);
    background-color: white;
}
.apple-pay-button-with-text.apple-pay-button-white-with-line-with-text > .logo {
    background-image: -webkit-named-image(apple-pay-logo-black);
    background-color: white;
}
.apple-pay-button-with-text > .text {
    font-family: -apple-system;
    font-size: calc(1em * var(--apple-pay-scale));
    font-weight: 300;
    align-self: center;
    margin-right: calc(2px * var(--apple-pay-scale));
}
.apple-pay-button-with-text > .logo {
    width: calc(35px * var(--scale));
    height: 100%;
    background-size: 100% 60%;
    background-repeat: no-repeat;
    background-position: 0 50%;
    margin-left: calc(2px * var(--apple-pay-scale));
    border: none;
}

Merchant Validation

As soon as the payment sheet is displayed, the Apple Pay JavaScript API calls your session object’s onvalidatemerchant callback function to verify that the request is coming from a valid merchant. It passes the function an ApplePayValidateMerchantEvent object.

In your onvalidatemerchant function:

1. Call your server, passing it the URL from the event’s validationURL property.

2. Your server then calls the Start Session endpoint at the provided URL.

3. The Start Session endpoint returns a merchant session object. This is an opaque object.

4. Pass the merchant session object to your Apple Pay session’s completeMerchantValidation method.

Start Session Endpoint

POST request to the URL provided by the ApplePayValidateMerchantEvent object’s validationURL property using two-way TLS.

Payload

The POST payload is a JSON dictionary containing the following key-value pairs:

• merchantIdentifier. Your merchant ID. For information on creating your merchant ID, see Configuring Your Environment in Apple Pay Programming Guide.

• domainName. The fully qualified domain name associated with your Apple Pay Merchant Identity Certificate.

• displayName. The canonical name for your store. The system may display this name to the user. Use a 128-character or less, UTF-8 string. Do not localize the name.

A sample Start Session payload is shown below:

{
    "merchantIdentifier":"merchant.com.example.mystore",
    "domainName":"mystore.example.com",
    "displayName":"MyStore"
}

Response

An opaque merchant session object.

Discussion

• Request a new merchant session object for each transaction.

• You can only use a merchant session object a single time.

• The merchant session object expires five minutes after it is created.

• Always use the URL provided by the ApplePayValidateMerchantEvent object’s validationURL property. The URL may vary. The URLs your server must allow access to are listed in the Server Requirements section of Apple Pay JS.

• The request must be sent from your server. Never request the merchant session from the client.

• Initiate the request over two-way TLS using your Apple Pay Merchant Identity Certificate. For more information, see Configuring Your Environment in Apple Pay JS.

The user cannot authorize the payment until you pass a valid merchant session object to the completeMerchantValidation method.