Apple Pay Web on Core via eProtect Integration Method

Document created by gjsissons on Feb 2, 2017Last modified by gjsissons on Feb 2, 2017
Version 6Show Document
  • View in full screen mode


This document is being actively revised - please check back soon!




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 however, 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.


Although there are multiple integration approaches for a Vantiv merchant wishing to support Apple Pay on the Web, these instructions are focused toward Apple Pay on the Web using Vantiv's eCommerce platform with Vantiv's eProtect service. This is the easiest integration method for most merchants, and is recommended for new integrations.




Supporting Apple Pay on the Web is reasonably straightforward for most merchants. 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 from iOS10 devices with a secure element connecting from the Safari browser. It can also be used with Safari from macOS 10.12 as long as 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
  • If you are already integrated with Vantiv, you will want to make sure that you are supporting a version of LitleXML that supports Apple Pay in-app and Apple Pay on the Web payments. Depending on the version of LitleXML you are integrated with, the following minimum versions are supported:
    • LitleXML 8.30
    • LitleXML 9.10
    • LitleXML 10.5
  • While Vantiv has a sandbox that developers can use to get started and code payment transactions against our eCommerce environment, you will need to work with a Vantiv integration consultant. If you don't already have an assigned consultant, please Contact us so that we can assign a consultant to work with you. You can also send an e-mail at anytime to to get connected with an integration consultant. The consultant will be able to provide you with test credentials for Vantiv's various test environments and provide credentials for Vantiv's eProtect service (if you don't already have them) that you will need in later steps below. Vantiv has different test environments including a sandbox, pre-live and post-live environment. You can learn more about these environments in Certification and Testing Environments.
  • Before starting and integration with Vantiv, it is a good idea to review our Onboarding FAQ.
  • 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


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:


  • Website Registration and Verification for Apple Pay - Support - Apple Developer


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)
  • Create a payment processing certificate or obtain a Certificate Signing Request (CSR) from Vantiv if Vantiv is decrypting the PKPaymentToken on your behalf
  • Register your SSL protected merchant domain with Apple
  • Configure a connection certificate for your merchant ID so that you can connect to Apple's servers.


The Apple documentation explains these steps in detail here.


Integration Approaches


Implementing Apple Pay on the Web follows a similar process regardless of the Vantiv platform you are integrating with.


In all cases you will be implementing the Apple Pay JS Framework for use in your web application. You can follow the Apple documentation for detailed instructions about implementing Apple Pay on the Web.


Differences in integration methods become more significant once your application needs to process the PKPaymentToken received from Apple Pay.


This guide describes the first integration approach (using eProtect) listed below, but a brief overview of differences by platform and integration method are covered below as well.


  • Apple Pay on the Web with Vantiv's Core platform using eProtect - If you are processing with the Vantiv Core platform, using eProtect is the easiest way to get up and running. eProtect will handle all the decryption and vaulting of the Apple Pay payment data for you. The remainder of the steps below assume that you are following this integration method.
  • Apple Pay Web for Enterprise Platform - If you are processing through our IBM RAFT or 610 platforms (known as Vantiv core), you may also decrypt the PKPaymentToken, and formulate the ISO message for Apple Pay.  We have sample Java code that can help you get started. You can learn more about this Apple Pay on the Web Integration Method here. Again, the procedures for process payments are identical for on-the-web and in-app payment scenarios.

Implementing Apple Pay on the Web


The Apple Pay JS documentation provides all the details needed to integrate Apple Pay on the Web into your eCommerce website. At a high level, an Apple Pay on the Web integration adds these steps:


  • At the point of checkout, your web application will use the JavaScript ApplePaySession.canMakePayments() or ApplePaySession.canMakePaymentsWithActiveCard() method to detect whether the client device can make a payment with Apple Pay.
  • Apple Pay will present a payment sheet to be displayed when the user clicks on the Apple Pay button
  • Apple Pay will perform merchant validation behind the scenes
  • On successful validation, Apple Pay will provide your application with a PKPaymentToken that can be used with Vantiv
  • Your code will pass the PKPaymentToken to eProtect in return for a low-value token, and use the low-value token to authorize a payment
  • After successfully processing a payment, your application will call the Apple Pay completePayment() method to close the session with Apple Pay


A short description of each step is provided below to provide more clarity. Please note the Apple Pay JS documentation provides additional examples of interfaces and various callbacks and exceptions that your code will be required to handle.


Detecting availability of Apple Pay on 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 (with an active card loaded in the Apple wallet).


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


if (window.ApplePaySession) {  
     var merchantIdentifier = '';  
     var promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantIdentifier);  
     promise.then(function (canMakePayments) {  
     if (canMakePayments)  


Present an Apple Pay payment sheet


Once we've determined that the client can pay via Apple Pay, we 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).


// 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);  


Merchant Validation


Next, the Apple Pay JavaScript 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) {  


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 complete an authorization.


Once the payment has been authorized by Vantiv, 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;  
               status = ApplePaySession.STATUS_FAILURE;  


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.


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


Note that the Apple Pay on the Web integration will normally be implemented in addition to existing payment methods, so everything in the existing eProtect integration 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 different set of arguments in the case of an Apple Pay on the web transaction following the onpaymentauthorized() callback. Below we get more specific and explain in detail how the Apple Pay on the Web transaction is handled with eProtect.


What happens when the user clicks the Apple Pay button


When the cardholder clicks the Apple Pay button, communication is exchanged with Apple Pay 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 PKPayment token instead of card data.


The eProtect server returns a Registration ID (low-value token) and your server constructs the authorization message using that ID. See the Vantiv eProtect Integration Guide for JavaScript and HTML page examples.


The high-level steps are detailed below:


  1. When the consumer selects the Apple Pay option from your website, your site makes use of the Apple Pay JS Framework to request payment data from Apple Pay.
  2. When Apple Pay receives the call from your website and after the consumer approves the Payment Sheet (using Touch ID), Apple creates a PKPaymentToken using your public key. Included in the PKPaymentToken is a network (Visa, MasterCard, American Express, or Discover) payment token and a cryptogram.
  3. The Apple Pay JS API passes the Apple PKPaymentToken (defined in Apple documentation; please refer to to your website via the Apple Pay JS  onpaymentauthorized() callback
  4. Your native iOS application sends the PKPaymentToken to our secure server via an HTTPS POST (see Creating a POST Request for an Apple Pay Transaction on page 36) and eProtect returns a Registration ID.
  5. Your website forwards the transaction data along with the Registration ID to your order processing server, as it would with any eProtect transaction.
  6. Your server constructs/submits a standard authorization message call to the IBM or RAFT platform using the Registration ID in the PAN field.
  7. Using the private key, Vantiv decrypts the PKPaymentToken associated with the Registration ID and submits the transaction with the appropriate information to the card networks for approval.
  8. Vantiv sends the Approval/Decline message back to your system. This message is the standard format for an Authorization response and includes the Vantiv specific token which can be used for subsequent transactions.
  9. You return the Approval/Decline message to your website and call the completePayment() method for the Apple Pay on the Web session with the authorization status to appropriately close the Apple Pay on the web session.


A diagram of these steps is provided below:





Passing the PKPaymentToken to eProtect


As is the case with a regular eProtect integration involving card information, you will need to create a POST request via the eProtect JavaScript API to pass payment information to and request a payPageRegistrationId (low-value token).


In the case of an Apple Pay on the web integration, you will pass different information to eProtect. Specifically:

  • The fields passed will not need to include the ccNum, cvv2Num or bin fields since these are not needed for an Apple Pay transaction.
  • You will need to pass the PKPaymentToken received via the Apple Pay JS onpaymentauthorized callback  to Vantiv eProtect.


Construct your HTTPS POST using the components listed below. See the Sample Apple Pay POST Request and Sample Apple Pay POST Response below.






The following is an example POST to request a Registration ID for Apple Pay:



curl --verbose -H "Content-Type: application/x-www-form-urlencoded" -H "Host:MerchantApp"

-H "User-Agent:Litle/1.0 CFNetwork/459 Darwin/10.0.0.d3"












































Sample code is provided below. Note that the litleRequest structure includes an applepay field that contains the PKPaymentToken.


 function sendTokenToLitle(token) {  
    setLitleResponseFields({"response":"", "message":""});  
        var litleRequest = {  
             "paypageId" : document.getElementById("request$paypageId").value,  
             "reportGroup" : document.getElementById("request$reportGroup").value,  
             "orderId" : document.getElementById("request$orderId").value,  
             "id" : document.getElementById("request$merchantTxnId").value,  
             "applepay" : token,  
             "url" : ""  
        var formFields = {  
            "accountNum" :document.getElementById('ccNum'),  
            "cvv2" :document.getElementById('cvv2Num'),  
            "bin" :document.getElementById('response$bin')  
    new LitlePayPage().sendToLitle(litleRequest, formFields, submitAfterLitle, onErrorAfterLitle, timeoutOnLitle, 15000);  
    return false;  


You can use the same callback functions that you already use for eProtect or create Apple Pay specific versions of those Callbacks.  (submitAfterLitle, onErrorAfterLitle and timeoutOnLitle).


Note that Apple Pay specific callback routines might be preferable since your application will need to call Vantiv with slightly different XML to authorize an Apple Pay transaction. On completion of the authorization, you'll also need to call the Apple Pay JS completePayment() method to advise Apple of the status of the transaction (Authorized, Declined etc.)


Just as you would in the case of a normal eProtect integration, your web browser will receive a payPageRegistrationId (low value token) as part of the response object when submitAfterLitle is called. The payPageRegistrationId is placed in a hidden browser form field and passed to the server via a POST method and used in the final step to authorize the payment transaction.


Step by step instructions and complete code examples are included in the Vantiv eProtect Integration Guide documentation.


Populating the ISO 8583 fields


Details are provided below about how to populate ISO 8583 fields with information extracted from the PKPaymentToken. For additional information, please consult the Vantiv ISO 8583 specification.


When populating the ISO 8583 fields for processing with Vantiv, the ECI indicator (eciIndicator) is mandatory and should always be populated. Populate the fields as shown below to enable Vantiv to interpret this as an Apple Pay / eCommerce transaction.


Payment Data Key ValueISO8583Field Note
applicationPrimaryAccountNumberField 2 – Primary Account Number
applicationExpirationDateField 14 – Date, ExpirationVantiv only supports YYMM, the merchant will need to truncate DD before submitting
currencyCodeField 49 – Currency Code, Transaction
transactionAmountField 4 – Amount, Transaction
CardholderNameN/AISO8583 does not have a corresponding field, nor is it needed to process the transaction
deviceManufacturerIdentifierN/AISO8583 does not have a corresponding field, nor is it needed to process the transaction
paymentDataTypeN/AISO8583 does not have a corresponding field, nor is it needed to process the transaction
paymentDataField 126See  detailed notes below about this field


Populating paymentData (Field 126 - eCommerce / MOTO indicator)


Vantiv has provided a network agnostic solution for the ApplePay cryptogram so that merchants do not have to identify what network the transaction belongs to


  • Attribute - LLL ans..999
  • This field must be present within all electronic commerce transactions. This field can also be used to distinguish various types of transactions for bill payment.
  • Syntax: <EC><I><DATA>
  • The field is made up of 4 Components
    • First two bytes = Length Indicator
    • Next two bytes <EC> = Secure Code transaction identifier (see table below)
    • Next one byte <I> = 6 (see second table below)
    • Next 20-40 bytes <DATA> = paymentData provided by Apple converted to hexadecimal. MasterCard and Visa result in 20 bytes hexadecimal and American Express results in 40 bytes hexadecimal.