Apple Pay

About

Apple Pay is an authentication mechanism that utilizes the built-in fingerprint scanner of Touch ID-enabled Apple devices. Apple Pay allows customers to use saved payment methods, or to enter new payment information.

This documentation contains information condensed from Apple's Apple Pay Presentation and JS documentation.

Implementation

Register Domain

To implement Apple Pay through Reach, the merchant will first need set up a meeting with Reach to register their domain with Reach's Apple MID. That process follows these steps:

• Reach registers the merchant's domain with Apple and receives a text file named: apple-developer-merchantid-domain-association.txt
• The merchant will need to host that text file on the registered domain in a public and non-password-protected folder named .well-known for example:
  • [merchant domain]/.well-known/apple-developer-merchantid-domain-association.txt
• Reach verifies the registration in the Apple console
• Every subdomain that wishes to display an Apple Pay button is required to be registered with Reach's Apple MID.

📘

Secure Server Configuration

Refer to Apple's Setting Up Your Server documentation to configure your server.

In particular:

• All pages with Apple Pay must be served over HTTPS
• The domain must have a valid SSL certificate
• Apple's IP Addresses will need to be allowlisted if your domain server is not publicly accessible
• TLS 1.2 and one of the approved cipher suites will need to be configured

Confirm Availability

Call /getPaymentMethods to confirm that Apple Pay is available for the given MerchantId, Country and Currency. If Apple Pay is available, it will be returned in the TokenMethods object of the /getPaymentMethods response.

Request:
GET https://checkout.rch.how/v2.22/getPaymentMethods?MerchantId={MerchantId}&Country=CA&Currency=CAD

Response:
{
  "PaymentMethods": [
    {
      "Id": "VISA",
      "Name": "Visa",
      "Class": "Card",
      "Local": true
    },
    ...
  ],
  "TokenMethods": [
    {
      "Type": "APPLEPAY",
      "Parameters": {
        "MerchantIdentifier": "com.foo.etc",
        "SupportedNetworks": [ "visa", "masterCard", ... ],
        "MerchantCapabilities": [ "supports3DS" ],
        "PaymentSessionUrl": "https://applepay.rch.how/getSession"
      }
    }
  ]
}

TokenMethods Parameters for Apple Pay

Frontend Overview

When implementing Apple Pay on the front end:

1. Check for Apple Pay availability
2. Display the Apple Pay button if Apple Pay is available
3. Use an Apple Pay session to construct the payment sheet
   a. Specify SupportedNetworks and MerchantCapabilities returned from /getPaymentMethods.
4. Handle any helpful session callbacks
5. Confirm the payment
6. Display a success or failure screen based on the result

📘

For more context on how to code the Apple Pay button and payment sheet please see Apple's Apple Pay Demo as well as Apple's Apple Pay for the Web Presentation.

Callbacks

onvalidatemerchant

Send a GET request to the PaymentSessionUrl returned from /getPaymentMethods with these parameters:

• validationURL
  • This is the URL provided in the onvalidatemerchant event
• displayName
  • A freeform string of the merchant name the merchant would like displayed to the customer

Then pass the MerchantSession Object returned in the response to the completeMerchantValidation() function.

Request:
https://{PaymentSessionUrl}?validationURL=https%3A%2F%2Fapple-pay-gateway-cert.apple.com%2Fpaymentservices%2FstartSession&displayName=SampleMerchantName

Response:
{
  "epochTimestamp": 1560893676087,
  "expiresAt": 1560897276087,
  "merchantSessionIdentifier": "SSH0429B8F0BE2E48FC8B27637888444A03_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24",
  "nonce": "a62c73fe",
  "merchantIdentifier": "DFA8A9C4B4A76BD56F843DEB60FA39029ECCB87DDDAE89E5F9700478D118211D",
  "domainName": "applepay.rch.how",
  "displayName": "SampleMerchantName",
  "signature": "3080....00000000000"
}

onpaymentauthorized

Stash the Apple Pay token with Reach.

curl -d 'token_data={URL Encoded TokenData object}&DeviceFingerprint={device fingerprint}'  https://stash.rch.how/{MerchantId}/{StashId}

{  
  "Type": "APPLEPAY", 
  "Data": [event.payment object]
}

Where the event.payment object is the ApplePayPayment object passed into the onpaymentauthorized callback function. Some data in the token is in plaintext, like the billing contact information, and can be used in Reach payment requests.

{ 
    "token": { 
      "paymentMethod": {
        "displayName": "MasterCard 1524",
        "network": "MasterCard",
        "type": "credit"
      },
      "transactionIdentifier": "...",
      "paymentData": { ... }
    },
    "billingContact": { ... },
    "shippingContact": { ... }
  }

📘

Use stashed data when placing the order

Now /checkout or /openContract may be called with the StashId used earlier to stash the token data. Since the token data includes the payment method, the PaymentMethod parameter is not necessary.

Display a success or failure screen based on the payment result.

Design

Pre-payment

There are some design considerations Apple suggests when displaying the Apple Pay button before the payment sheet has been displayed.

The button is available in both Cocoa Touch and in WebKit that can be used to display the Apple Pay button in a variety of styles. Apple's design guidelines recommend that the merchant uses built-in assets and places the button wherever a customer may wish to purchase an item.

Apple's guidelines also require that the Apple Pay button is:

• not hidden or made difficult to use
• only displays the payment sheet when clicked
• displayed at the same level as all other payment method and not hidden

Apple's marketing guidelines, acceptable use and design guidelines may help when determining how Apple Pay will be presented.

The Apple Pay button may be displayed on the:

• Product page
• Checkout flow
• Cart page

Payment

When displaying the payment sheet, the merchant may design the payment process in multiple ways, including customizing the terminology for each field displayed.

The merchant may present these fields:

• Select an existing card from their Apple Wallet
• Enter new card details
• Billing or Shipping address
• Contact information, including e-mail, phone number, and name
• Shipping methods
• Shipping pickup/cost

The summary items field is a concise and accurate indication of what the customer is being charged, but it is not an itemized list. It may include information like the subtotal, shipping cost, discounts, or free items. It's important to be upfront and clear about what is being charged, if possible, since directly after paying through Apple Pay, a notification will be displayed to the user with the amount charged. The amount in the summary field should match the amount displayed after the purchase has been made to the extent possible.

The merchant may also specify a site icon which will be displayed in the payment sheet. The icon will need to be provided at both 180 and 120-pixel sizes. The easiest way to specify this is to use a link attribute like so in the head of the merchant's page:

<link rel="apple-touch-icon" sizes="120x120" href="[email protected]">
<link rel="apple-touch-icon" sizes="180x180" href="[email protected]">

These icons can also be placed at the root node of the domain registered at Apple.

Post-payment

Once the payment sheet has been completed, the merchant should display a confirmation page indicating success. In the event of a failure, an error page or the order review page with an error should be displayed.

At this time, the merchant can also utilize information collected by Apple Pay to facilitate account creation on the merchant's site. For example, pre-populate the e-mail field with the address that was collected during the Apple Pay checkout process to make creating an account more simple for the user.