Apple Pay on the Web on Core Integration Process

Document created by gjsissons on Sep 6, 2016Last modified by awind@vantiv on Feb 7, 2017
Version 11Show Document
  • View in full screen mode




From a payments integration perspective, Apple Pay on the Web is similar to Apple Pay In-App. Apple Pay on the Web however allows you to reach a larger audience, since consumers are not required to download an iOS App to use Apple Pay. Rather, consumers with appropriate Apple devices running the Safari browser can pay using Apple Pay from any web-site supporting Apple Pay on the Web extensions.


For a video presentation of Apple Pay on the Web, please check out this video from the Apple Developer Conference. You can also download the presentation for reference.

Getting started


Before you can use Apple Pay on the Web, you'll need to first register your e-commerce website with Apple.


Follow the guidelines provided by Apple 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 Overview


Vantiv provides a single integration approach when implementing Apple Pay on our core payment platforms. With this method, the merchant will need to take responsibility for decrypting the Apple PKPaymentToken themselves using their private key. Once the token has been decrypted, merchants can process with Vantiv using the d-pan as they would any other payment card.


This guide assumes that the reader has some familiarity with Vantiv's Core platform. It explains the necessary steps to support Apple Pay as a method of payment, and explains how to pass payment transactions to Vantiv using ISO 8583.


  • If you are new to Vantiv, be aware that Vantiv has multiple ways of supporting Apple Pay. Before starting a project, please contact us and speak to an integration consultant. We can help you choose the integration method most appropriate for your business.
  • This guide also assumes that the developer is already familiar with Apple iOS application development.


Apple Pay on the Web Operation


The operation of Apple Pay on the web is similar to the flow for Apple Pay for in-app. You will need to modify your existing website to include the use of the Apple Pay JS Framework following Apple's instructions. The Apple Pay JS Framework will return encrypted Apple Pay payment data to your application in the form of a PKPaymentToken. With this integration method, you will be responsible for decrypting this token yourself and extracting the contents.


These steps are detailed in the Vantiv ISO 8583 Specification - Network Tokenization (ApplePay) documentation.


Also, for details on decrypting the PKPaymentToken please refer to the Decrypting the PKPaymentToken section below.


The basic steps that occur when a consumer initiates an Apple Pay purchase using your website are:

  1. When the consumer selects the Apple Pay option from your webpage, your client 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, or American Express) payment token and a cryptogram. The network payment token is sometimes referred to as the network token or the d-pan.
  3. Apple Pay returns the Apple PKPaymentToken to JavaScript code running in the context of your Safari browser
  4. The Safari browser posts the PKPaymentToken to your server
  5. Your server decrypts and parses the PKPaymentToken and map the Payment Data elements to specific ISO8583 fields
  6. Vantiv then submits the authorization to the card networks and receives an approval/decline
  7. Approval/Decline sent to your server
  8. You return the response to the webpage and handle appropriately


The high-level process flow is represented in the diagram below:






Before you can proceed with building and testing integration, please make sure you have access to the following resources below:

  • Ensure that you have reviewed the Apple Pay API overview on the Apple Pay Developer Website.
  • 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.


Decrypting the PKPaymentToken


Apple Pay packages both the EMVCo token and transaction cryptogram into a single 3D Secure (3DS) encrypted data element. Only the 3DS package is returned (versus the individual data elements) meaning that the 3DS package needs to be decrypted and parsed by the merchant before the transaction can be processed.


You can find details in the Apple Payment Token Format Reference here: Payment Token Format Reference


The structure of the PKPaymentToken is shown below:



Having received the PKPaymentToken from Apple, the developer or merchant will need to initiate an In-App Authorization Request to the RAFT front-end following these steps:


  • Decrypt and parse the PkPaymentToken
  • Map the Payment Data elements to specific ISO8583 fields
  • Populate other ISO8583 fields with specific values that enable Vantiv to interpret the transaction as being an Apple Pay / eCommerce transaction


These steps are detailed in the Vantiv ISO 8583 Specification - Network Tokenization (ApplePay) documentation and are summarized below.
You can find sample Java code here that shows how to decrypt the PKPaymentToken.


Payment Data Keys


After being decrypted, the payment data contains the following keys and values:

applicationPrimaryAccountNumberstringDevice-specific account number of the card that funds this transaction.
applicationExpirationDatedate as a stringCard expiration date in the format YYMMDD.
currencyCodestringISO 4217 numeric currency code, as a string to preserve leading zeros.
transactionAmountnumberTransaction amount.
cardholderNamestringOptional. Cardholder name.
deviceManufacturerIdentifierstringHex-encoded device manufacturer identifier.
paymentDataTypestring"3DSecure"  (EMV for future use)
paymentDatapayment data dictionaryDetailed payment data.


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
paymentDataField 126See  detailed notes below about this field

Note: CardholderName, deviceManufacturerIdentifier, and paymentData Type do not have a corresponding field in the ISO 8583 spec. It is not needed to process the transaction.



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 either a 20 or 40 byte hexadecimal.



2 - Byte Electronic Commerce/MOTO Indicator <EC>


05Verified by Visa authenticated, or, MasterCard Secure Code with AAV data
07Electronic commerce, but neither Verified by Visa, nor MasterCard Secure Code
20Token Initiated (AMEX only)


The 6 value is used in Apple Pay for the variable data following the electronic commerce indicator. This data is only included for specific electronic commerce transactions that require it; otherwise, only the <EC> value is sent in.


For Apple Pay implementations, the 3-D Secure Data field should be used with the data for each network brand being placed in a hexadecimal format as received from the application directly in the data field including the length.

Value <I>Description <Data>

3-D Secure Data (variable)


Syntax: XXDDD…DDD where:


XX = Length of data to follow (1 byte hex)

DDD…DDD = Variable Data


Variable Data Formats:

MasterCard -> AAV

Visa -> CAVV + XID (optional)

American Express -> AEVV + XID (optional)

Discover -> CAVV


Note: All data is expected to be in a standard hexadecimal format and not Base 64 encoded.



Populating Point of Service Entry Mode (Field 22)


  • Field 22 – Point of Service Entry Mode
    • 81 - Used for all one-time authorizations and first transactions in series
    • 10 - Used for subsequent recurring or merchant initiated transactions