Apple Pay on the Web on Core Integration Process

Document created by gjsissons on Sep 6, 2016Last modified by jeankatter on Apr 5, 2017
Version 13Show Document
  • View in full screen mode

 

Introduction

 

This guide assumes that you are familiar with Vantiv's Core platform and with the Apple iOS application development. It explains the steps to support Apple Pay as a method of payment and how to pass payment transactions to Vantiv using ISO 8583. Vantiv has multiple ways of supporting Apple Pay; therefore, before you start an integration, contact Vantiv or consult an integration consultant. We can help you choose the integration method most appropriate for your business.

 

From a payments integration perspective, Apple Pay on the Web is similar to Apple Pay In-App; however, Apple Pay on the Web lets you reach a larger audience, because 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 website supporting Apple Pay on the Web extensions.

 

Integration Overview

Vantiv provides a single integration approach when implementing Apple Pay on its core payment platforms. With this method, the merchant is responsible for decrypting the Apple PKPaymentToken using their private key. Once merchants decrypt the token, they can process with Vantiv using the DPAN as they would with any other payment card. Before starting, it is recommended that you view this video presentation of Apple Pay on the Web from the Apple Developer Conference.

 

Getting Started

Before you can use Apple Pay on the Web, you must first register your e-Commerce website with Apple. For guidelines about this procedure, refer to the Apple documentation.

 

To register your eCommerce website with Apple:

 

  1. Register a Merchant ID. You can use your existing Merchant ID if you already use Apple Pay In-App payments.
  2. Do one one of the following:
    • Create a payment processing certificate.
    • If Vantiv decrypts the PKPaymentToken for you, obtain a Certificate Signing Request (CSR) from Vantiv.
  3. Register your SSL protected merchant domain with Apple.
  4. Configure a connection certificate for your merchant ID so that you can connect to Apple's servers.

 

Apple Pay on the Web Operation

The operation of Apple Pay on the web is similar to the flow for Apple Pay In-App. You must modify your existing website to include the use of the Apple Pay JS Framework adhering to Apple's instructions. The Apple Pay JS Framework returns encrypted Apple Pay payment data to your application in the form of a PKPaymentToken. With this integration method, you decrypt this token yourself and extract the contents. Refer to the ISO 8583 Apple Pay In-App Transaction Guide for these steps.  For information about decrypting the PKPaymentToken, see Decrypting the PKPaymentToken.

Before you can build and test the integration, ensure that you:

  • Read the Apple Pay API overview on the Apple Pay developer website.
  • Consult your Vantiv integration consultant. If you do not have one, contact Vantiv to have one assigned to you.

 

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

  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. The PKPaymentToken includes 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 DPAN.
  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 maps the Payment Data elements to specific ISO 8583 fields with specific values that enable Vantiv to interpret the transaction as being an Apple Pay/eCommerce transaction.
  6. Vantiv submits the authorization to the card networks and receives an approval or a decline.
  7. Your server receives an aproval or a decline.
  8. You return the response to the website and handle it appropriately.

 

The high-level process flow is shown below:

 

apple_pay_on_web_core_process_flow_gs.PNG

 

Decrypting the PKPaymentToken

 

The structure of the PKPaymentToken is shown below:

 

PKPaymentToken_structure.PNG

For more detailed information, see the ISO 8583 Apple Pay In-App Transaction Guide. Vantiv provides sample Java code that shows how to decrypt the PKPaymentToken.

 

Payment Data Keys

 

After the decryption of the PKPaymentToken, the payment data contains the following keys and values:

KeyValueDescription
applicationPrimaryAccountNumberStringDevice-specific account number of the card that funds this transaction
applicationExpirationDateDate as a stringCard expiration date in the YYMMDD format
currencyCodeStringISO 4217 numeric currency code, as a string to preserve leading zeros
transactionAmountNumberTransaction amount
cardholderNameStringCardholder name (optional)
deviceManufacturerIdentifierStringHex-encoded device manufacturer identifier
paymentDataTypeString3DSecure or EMV  (EMV is for future use.)
paymentDataPayment data dictionaryDetailed payment data

 

Populating the ISO 8583 fields

 

This section describes how to populate ISO 8583 fields with information extracted from the PKPaymentToken. For more information, refer to the Acquirer ISO 8583 Message Format specification.

 

When populating the ISO 8583 fields for processing with Vantiv, the ECI indicator (eciIndicator) is mandatory; you must always populate it. Populate the fields as shown in the table 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 must truncate DD before submitting.
currencyCodeField 49 – Currency Code, Transaction
transactionAmountField 4 – Amount, Transaction
paymentDataField 126See "Populating the paymentData (Field 126 - eCommerce/MOTO Indicator."

Note: CardholderName, deviceManufacturerIdentifier, and paymentData do not have a corresponding field in the ISO 8583 spec. You do not need them to process the transaction.

 

 

Populating the paymentData (Field 126 - eCommerce/MOTO Indicator)

Vantiv provides a network agnostic solution for the ApplePay cryptogram; therefore, merchants do not have to identify the network belonging to the transaction. All electronic commerce transactions must contain this field. You can also use this field to distinguish various types of transactions for bill payment.

 

Attribute: LLL ans..999

Syntax: <EC><I><DATA>

The field is made up of 4 Components

  • First two bytes = Length Indicator
  • Next two bytes <EC>, which is the Secure Code transaction identifier (first table below)
  • Next one byte <I> = 6 (see second table below)
  • Next 20-40 bytes <DATA> , which is 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>

 

ValueDescription
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)

 

Apple Pay uses the value of 6 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.

 

For Apple Pay implementations, you should use the 3-D Secure Data field and supply the length (XX) and then the variable data (DDD…DDD).

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

Value <I>Description <Data>
6

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

 

Populating Point of Service Entry Mode (Field 22)

Use one of the following values to populate this field:

  • 81 - All one-time authorizations and first transactions in series
  • 10 - Subsequent recurring or merchant initiated transactions

 

Attachments

    Outcomes