Apple Pay on the Web and Mercury Pay

Document created by gjsissons on Nov 8, 2016Last modified by alec-paulson on Jan 17, 2017
Version 10Show Document
  • View in full screen mode

High-level Overview

 

From a payments integration perspective, Apple Pay on the Web is similar to Apple Pay In-App.

 

Apple Pay on the Web allows you to potentially reach a larger audience, since consumers are not required to download an iOS App to pay with Apple Pay. Rather, consumers with appropriate Apple devices can pay directly from their Safari browser with a single touch.

 

For an overview of Apple Pay on the Web, please check out this video from the 2016 Apple Worldwide Developer Conference.

 

You can download a presentation here that explains in detail how Apple Pay on the Web works.

 

[top]

 

Apple Pay on the Web and MercuryPay

 

Support for Apple Pay on the Web on MercuryPay is also referred to as Vantiv’s OmniChannel for Integrated Payments solution. It is intended to help developers currently using Vantiv’s MercuryPay platform support Apple Pay on the Web with their eCommerce website.

 

It is referred to as an OmniChannel solution because it supports Vantiv's OmniToken technology, and supports transacting eCommerce and mobile payments against the same MercuryPay account.

 

It combines an Apple Pay on the Web integration, creating an OmniToken in Vantiv's vault via Vantiv’s eProtect service, and all of the back-end processing and settlement features that MercuryPay developers are already familiar with.

 

Below is a diagram of how these pieces fit together.

 

apple-pay-on-web-mercury.PNG

 

  • The developer implements or augments their eCommerce website to support Apple Pay on the Web and eProtect. When the consumer pays for something online from an Apple Pay capable device via the Safari browser, Apple Pay is presented as a method of payment. When the consumer approves the Apple Pay transaction, the mobile website interacts with the Apple Pay JS API and retrieves a PKPaymentToken from Apple. The PKPaymentToken is then posted to the Vantiv eProtect service along with other information about the payment transaction.
  • Vantiv eProtect converts the token from the Safari browser into an eProtect token known as the payPageRegistrationId (also referred to the as "low-value token"). The MercuryPay documentation refers to the eProtect payPageRegistrationId simply as the RegistrationId. This RegistrationId is valid for 24 hours. Format: 19 digits, MOD 10+1.
    • Note that the payPageRegistrationId can have different formats depending on how your eProtect account is configured. payPageRegistrationIds returns by the Litle token vault will be in the form of a cryptogram. Low-value tokens that represent OmniTokens will adhere to the 19 digit MOD 10+1 format. Your integration consultant will need to make sure your eProtect account is configured appropriately for use with OmniTokens.
  • The low-value token (RegistrationId) is then passed to the merchant server and the transaction is processed using a MercuryPay tokenized transaction request, which contains one additional field called TokenType. In this case the value is set to "RegistrationID" to indicate that the value being passed is a low-value eProtect token. The RecordNo field contains the actual RegistrationID (payPageRegistrationId) returned from the eProtect service. Here is an example:

 

<TokenType>RegistrationID</TokenType>
<RecordNo>64628041602383188943</RecordNo>

 

The RegistrationID is used to flag MercuryPay to servers that this is a low-value token and that an OmniToken should to be returned in the transaction response.

 

  1. The transaction request is submitted to the back-end networks by MercuryPay for authorization processing as usual.
  2. The transaction response includes the new OmniToken, which is returned in the RecordNo field to the eCommerce application.
  3. The OmniToken can be stored in a local database and used for subsequent MercuryPay transactions such as Void or Adjust.

 

For more information on the Apple Pay PKPaymentToken, please refer to: https://developer.apple.com/library/ios/documentation/PassKit/Reference/PaymentTokenJSON/PaymentTokenJSON.html 

 

For more information about using Apple Pay with eProtect, please see Vantiv eCommerce Apple Pay Solution. When referring to the Apple Pay Solution documentation, keep in mind that it was written with Vantiv's eCommerce (Litle) platform in mind, so readers will need to ignore these parts as they will be integrating with MercuryPay using the MercuryPay REST or SOAP APIs.

 

[top]

 

Prerequisites

 

This integration method assumes that you will process Apple Pay on the Web payments on Vantiv's MercuryPay platform

 

Supporting Apple Pay on the Web is reasonably straightforward for most merchants if they have already added support for Apple Pay In-App. The integration involves adding the Apple Pay JS framework to your existing eCommerce website. While there is development and testing work involved, the amount of effort is much less then building an iOS app.

 

  • Apple Pay on the Web will only work with iOS 10 devices with a secure element connecting from the Safari browser. It can also be used with Safari from macOS 10.12 Sierra as long as the computer has Bluetooth LE support and you have a Bluetooth connected iPhone or Apple Watch that can authorize a payment.
  • Ensure that you have reviewed the Apple Pay documentation specific to Apple Pay on the Web. Relevant links are provided here for convenience
  • Apple provides test cards that you can load into an Apple Pay Wallet for testing.  Please see this page for reference: - Apple Pay Sandbox Testing - Support - Apple Developer
  • Ensure that you have test credentials to use the MercuryPay SOAP or REST API (your integration consultant can help you obtain these)
  • Ensure that you have reviewed the Vantiv eProtect documentation
  • Ensure that you additionally have test credentials to work with the Vantiv eProtect service (your integration consultant can help you obtain these as well. Your eProtect account will need to be configured to return a low-value token in the required 19 character format)
  • You will additionally need a Certificate Signing Request (CSR) from Vantiv as explained below as well as public/private keys provided by Apple.

 

[top]

 

Getting Started

 

Before you can use Apple Pay on the Web, you'll need to obtain Apple Pay credentials and register your eCommerce website with Apple.

 

These steps are required regardless of your integration method and regardless of the payment provider you are dealing with.

 

Follow the guidelines provided by Apple here:

 

 

You will need to have an Apple Developer Program account before you can proceed with these steps. You can learn about the program here.

 

The steps involved are:

  • Register a Merchant ID (if you are already using Apple Pay In-App payments you can use your existing Merchant ID)
  • If you have not added Apple Pay In-App support then Vantiv will provide you with a Certificate Signing Request (CSR), which you must submit to Apple. Apple will return the certificate, containing your public/private encryption keys, to you. Provide this information to your Implementation Consultant.
    • Apple uses the public key to create the PKPaymentToken.
    • Vantiv stores the decrypted Network Token extracted from the PKPaymentToken passed in your POST to eProtect in the Vantiv's token vault.
  • Register your SSL protected merchant domain with Apple
  • Download the Merchant Identity Certificte for your merchant ID so that you can connect to Apple's servers.

 

The Apple documentation explains these steps in detail here.

 

Detecting availability of Apple Pay from the Browser

 

Your application will use a JavaScript fragment like the one below to expose Apple Pay on the Web as a payment method only if the Apple Pay JS API is present and the Safari client is able to make payments (meaning there is an active card loaded in the Apple wallet). Otherwise your application will need to be prepared to fall back to another method of payment, usually a credit card payment.

 

Sample HTML and CSS to expose the Apple Pay buttons is provided in the ApplePaySession Class documentation.

 

if (window.ApplePaySession) {
 var merchantIdentifier = 'merchant.com.canine-clothing';
 var promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantIdentifier);
 promise.then(function (canMakePayments) {
 if (canMakePayments)
 showApplePayButtons();
 });
}

 

[top]

 

Present an Apple Pay payment sheet

 

Once we've determined that the client can pay via Apple Pay, construct an Apple Pay payment sheet as shown. Details are provided in the Apple Pay JS API ApplePaySession Class reference. Note that session.begin() can only be called in a response to a user action (for example within an onclick() event handler).

 

// Presenting the payment sheet
var paymentRequest = {
 currencyCode: 'USD',
 countryCode: 'US',
 total: {
 label: ‘Canine Clothing',
 amount: '19.99'
 },
 supportedNetworks: ['amex', 'discover', 'masterCard', 'visa' ],
 merchantCapabilities: [ 'supports3DS' ],
 requiredShippingAddressFields: [ 'postalAddress' ]
};
var session = new ApplePaySession(1, paymentRequest);
session.begin(); 

 

[top]

 

Merchant Validation

 

Next, the Apple Pay JS API calls your session's onvalidatemerchant() callback function to validate that the request is coming from a valid merchant.  The steps involved are explained in detail in the Apple Pay JS API ApplePaySession Class reference (see the section titled Merchant Validation). Additional required steps are not shown here for brevity.

 

session.onvalidatemerchant = function (event) {
 var promise = performValidation(event.validationURL);
 promise.then(function (merchantSession) {
 session.completeMerchantValidation(merchantSession);
 });
} 

 

[top]

 

Payment authorization

 

onpaymentauthorized is automatically called when the user has authorized an Apple Pay payment, typically via a touchID on the Apple device. Details are provided in the Apple Pay JS API Reference. The event object passed contains the Apple Pay PKPaymentToken token.

 

This where the integration with Vantiv takes place. You will need to construct a function below (sendPaymentToken() or whatever you decide to call it) that sends the PKPaymentToken to Vantiv's eProtect service, retrieves a low-value token in response (a payPageRegistrationID) and uses that low-value token to perform an authorization with MercuryPay using the REST or SOAP API.

 

Once the payment has been authorized by Vantiv MercuryPay, your website can call the completePayment() instance method for the Apple Pay session to complete the payment and dismiss the Apple Pay sheet. A simplified example is shown below

 

session.onpaymentauthorized = function (event) {
 var promise = sendPaymentToken(event.payment.token);
 promise.then(function (success) {
 var status;
 if (success)
 status = ApplePaySession.STATUS_SUCCESS;
 else
 status = ApplePaySession.STATUS_FAILURE;
 session.completePayment(status);
 showConfirmation();
 });
}

 

The steps above show the high level process from an Apple Pay on the Web perspective.

 

In the sections that follow we delve into the specifics of how the application processes the payment with eProtect once the token is received via the onpaymentauthorized() callback.

 

[top]

 

How Apple Pay on the Web works with eProtect

 

In this scenario, the Vantiv eProtect Customer Browser JavaScript API controls the fields on your checkout page that hold sensitive card data. In an eProtect implementation that does not involve Apple Pay on the web, eProtect fields will include details like:

 

  • A credit card number
  • An expiry date
  • CVV details

 

Apple Pay on the Web will normally be implemented in addition to existing payment methods, so everything in the existing eProtect integration that accepts credit cards is still valid. The only difference is that your application may additionally expose Apple Pay as a more convenient payment method if the client device is able to support it.

 

If you are using eProtect presently on your eCommerce website, a JavaScript SendtoLitle() method similar to the example below is used to pass information to Vantiv's eProtect service in return for a low value token.

 

The litleRequest object is a JSON structure that contains your merchant credentials. formFields is a JSON structure that points to the fields on the presented checkout form that contain sensitive data.

 

new LitlePayPage().sendToLitle(litleRequest, formFields, submitAfterLitle, onErrorAfterLitle, onTimeoutAfterLitle, timeout)      

 

Your application will still need to call sendToLitle() in this fashion when the client device does not support Apple Pay or the user does not select Apple Pay as the payment method. In addition to your existing eProtect integration, you will need to provide an alternate path in your code, that calls sendToLitle() with a subtly different set of arguments in the case of an Apple Pay on the Web transaction following the onpaymentauthorized() callback. (specifically you will be sending the PKPaymentToken to eProtect rather than PAN data).

 

[top]

 

What happens when the user clicks the Apple Pay button

 

When the cardholder clicks the Apple Pay button, communication is exchanged with Apple via the Apple Pay JS API to obtain the PKPaymentToken. Specifically, the token will be passed to your application in the ApplePay JS onpaymentauthorized() call back that you supply associated with your Apple Pay session as explained above.

 

From this point forward, handling the transaction is similar to any other eProtect transaction except that you will pass the eProtect server a PKPaymentToken instead of card data.

 

function sendToLitle(payment) {
    var litleRequest = {
        "paypageId": "<REPLACE_ME>",
        "reportGroup": "reportGroup",
        "orderId": "orderId",
        "id": "id",
        "applepay": payment.token.paymentData,
        "url": "https://request-prelive.np-securepaypage-litle.com"
    };
    console.log(litleRequest);
    var formFields = {
        "paypageRegistrationId": document.createElement("input")
    };
    var response = new LitlePayPage().sendToLitle(litleRequest, formFields, submitAfterLitle, onErrorAfterLitle, timeoutOnLitle, 15000);
    return false;
}

 

The eProtect server returns a payPageRegistrationID (low-value token) and the browser posts the payPageRegistrationId to the eCommerce server.

 

Your server then constructs a MercuryPay authorization request using the RegistrationID as the payment source. See the Vantiv eProtect Integration Guide for JavaScript and HTML page examples.

 

[top]

 

 

Choosing the OmniToken Format

 

The key to enabling Vantiv’s In-App Apple Pay integration with MercuryPay is the generation and use of an OmniToken.

 

OmniTokens offer a shorter “format-preserved” reference to the cardholder’s credit card number with the actual card data being stored in Vantiv’s secure vault.

 

The advantages to this method of tokenization is that it allows for easy access to programs and features that were never possible before—including eProtect for eCommerce and Apple Pay In-App.

 

For MercuryPay integrations, the OmniToken is used in place of a MToken (RecordNo). One additional tag, <TokenType> is used in the transaction request.

 

OmniTokens generated over the eProtect platform come in several different formats. When using them for MercuryPay, the MOD10+1 formats are preferable as they can be used to distinguish whether it is a token or credit card number. We recommend using either of the two formats below:

 

  • Format T: Informative A1. Duplicates the length of the original PAN and preserves the first-six and last-four of the PAN. For example, if the original PAN is 14 characters long, the OmniToken will be 14 characters.
  • Format D: Minimum 16A 1. Length is 16 if the original PAN is 16 characters or less, but can be up to 19 characters if the original PAN is that length. For example, if the original PAN is 15 digits long, the OmniToken will be 15 characters; if the original PAN is 19 characters, the OmniToken will be 19 characters.

 

Processing the In-App Apple Pay payment with Mercury Pay

 

Once your application has the low-value token, the procedure for processing the payment with Vantiv's Mercury Pay is the same whether you are using Apple Pay In-App or Apple Pay on the Web.

 

Please skip to Processing Apple Pay Transactions through MercuryPay for details on how to construct a payment authorization on Mercury Pay using the low-value token.

 

[top]

Attachments

    Outcomes