Apple Pay on the Web on Core Integration Process

Document created by gjsissons on Sep 6, 2016Last modified by gjsissons on Nov 2, 2016
Version 9Show Document
  • View in full screen mode

 

Introduction

 

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:  https://developer.vantiv.com/external-link.jspa?url=https%3A%2F%2Fdeveloper.apple.com%2Fvideos%2Fplay%2Fwwdc2016%2F703%2…

 

You can download a presentation here: http://devstreaming.apple.com/videos/wwdc/2016/703rx8zlfedjfom6l93/703/703_apple_pay_on_the_web.pdf

 

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:

 

apple_pay_on_web_core_process_flow_gs.PNG

 

Requirements

 

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:

 

PKPaymentToken_structure.PNG

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:

KeyValueDescription
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.
paymentDataTypestringEither "3DSecure" or "EMV".
paymentDatapayment data dictionaryDetailed payment data.

Note: The paymentDataType description indicates that it’ll be either “3DSecure” or “EMV.” Visa, MasterCard and American Express have indicated that “EMV” is for future purposes only and has not been implemented. All In-App transactions are expected to have “3DSecure” as the paymentDataType.

 

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.

 

 

2 - Byte Electronic Commerce/MOTO Indicator <EC>

 

ValueDescription
01Single transaction – default for bill payments
02Recurring transaction
03Installment payment
05Verified by Visa authenticated, or, MasterCard Secure Code with AAV data
06Verified by Visa attempts processing, or, MasterCard Secure Code without AAV data
07Electronic commerce, but neither Verified by Visa, nor MasterCard Secure Code
08The cardholder’s payment card data was transmitted to the merchant using no security method
09Used by non-U.S. merchants to designate Secure Electronic Transaction (SET) purchases. U.S. Issuers should not receive ECI of 9, unless the value was the result of a processing error or a miscoded value
10Recurring transaction (first transaction of a recurring payment series)
20Token Initiated (AMEX only)

 

 

The following are the valid values 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.

Value <I>Description <Data>
1Cardholder Certificate Serial Number
2Merchant Certificate Serial Number
3Visa Transaction ID (XID)Syntax: DDD..DDD where:DDD..DDD = 20 byte XID (optional for Verified by Visa)
4Cardholder Authentication Verification Value (CAVV)Syntax: DDD..DDD where:DDD..DDD = 20 byte CAVV (Required for Verified by Visa)
5Universal Cardholder Authentication Field (UCAF)Syntax: DDD..DDD where:DDD..DDD = 20 byte UCAF (Required for MasterCard Secure Code – not BASE 64 encoded)
63-D Secure Data (variable)Syntax: XXDDD…DDD where:XX = Length of data to follow (1 byte hex)DDD…DDD = Variable DataVariable Data Formats:MasterCard -> AAVVisa -> 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.Note: For Apple Pay In-app 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.

 

 

Populating Point of Service Entry Mode (Field 22)

 

  • Field 22 – Point of Service Entry Mode = 81

 

 

Attachments

    Outcomes