Apple Pay In-App on Core Integration Process

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

Overview

 

When integrating an Apple Pay app with Vantiv's core platform there is only a single integration method.

 

Merchant apps that support in-app Apple Pay with Vantiv's core platform will submit a PKPaymentRequest to Apple Pay’s PassKit interface and receive back a PKPaymentToken. 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 extracted from the token as they would any other payment card.

 

Processing the card transaction with Vantiv will be similar to any other ISO 8583 transaction and will involve populating the ISO 8583 fields with payment related values retrieved from the payment token.

 

This guide assumes that the reader has some familiarity with Vantiv's core processing platforms (ISO 8583 / 610). It explains the necessary steps to support Apple Pay as a method of payment and how to pass payment transactions to Vantiv.

 

  • If you are new to Vantiv, be aware that Vantiv has multiple payment platforms and front-ends. Before starting a project, please contact us and speak to an integration consultant. We can help you choose the payment platform appropriate for your business and help setup necessary credentials for access and testing.
  • This guide assumes that the developer is already familiar with Apple iOS application development.

 

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. Information specific to using Apple Pay in your iOS app can be found in the Apple Pay Guide. (Note that what Apple describes as an In-App purchase for digital goods is a different processing involving purchasing digital goods from the App Store using Apple's Store Kit framework to access payment credentials in iTunes. This is a separate process, unrelated to this guide)
  • 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.

 

Apple Pay Operation

 

The operation of Apple Pay on the iPhone 6 and other supported devices is relatively simple, but will require either the development of new native iOS applications or the modification of your existing applications that include the use of the Apple PassKit Framework. The Apple PassKit 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.

 

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

 

  1. When the consumer selects the Apple Pay option from your application, your application makes use of the Apple PassKit Framework to request payment data from Apple Pay.
  2. When Apple Pay receives the call from your application, 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 (referred to as a d-pan) and a cryptogram. The network payment token is also sometimes referred to simply as the network token in some documentation.
  3. Apple Pay returns the Apple PKPaymentToken to your application.
  4. Your mobile application forwards the PKPaymentToken from Apple Pay to your order processing server, along with other normal information from the transaction (such as Bill To and Ship To Address etc.)
  5. Using your private key, you decrypt the PKPaymentToken, construct the appropriate ISO 8583 transaction, populate the transaction with payment related fields from the payment token and submit it to Vantiv.
  6. Vantiv detects that this is an Apple Pay transaction based on your ISO 8583 message and submits the transaction with the appropriate information to the card networks for approval.
  7. Vantiv sends the Approval/Decline message back to your system, using the standard format for an ISO 8583 Authorization or Sale response.
  8. You return the Approval/Decline message to your mobile application.

 

A high level overview of the process is shown below:

 

apple_pay_in_app_core_process_flow.PNG

 

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. Contains the device primary account number of the card that funds the transaction.

 

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.

 

Submit an In-App authorization request to the RAFT front-end:

 

1. Decrypt and parse the PkPaymentToken using the following detailed payment data keys (3-D Secure):

  • onlinePaymentCryptogram - This string value is the online payment cryptogram as defined by 3-D Secure.
  • eciIndicator - This optional string value is the ECI indicator as defined by 3-D Secure; however, it is mandatory for Vantiv. You must always populate it. See the Apple developer’s site for additional information about the PKPaymentToken and decryption.

2. Map the Payment Data elements to specific ISO 8583 fields.

3. Populate other ISO 8583 fields with specific values that enable Vantiv to interpret the transaction as an Apple Pay /e-Commerce transaction.

 

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

 

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 field.

 

You can also use this field to distinguish various types of transactions for bill payment. Field 22 (Point of Service Entry Mode) when set to 81 (Magnetic - Track 1) is also related to Apple Pay / eCommerce transactions.

 

Field 126 has a data type of LLL...ans 999, a length of 0-999, and has the following syntax: <EC><I><DATA>

 

To use Field 126 to set up payment data:

 

  1. In the first two bytes, specify the length indicator.
  2. In the next two bytes, pass the Secure Code transaction identifier (<EC>). The in-app provider supplies this, and it is a value of either 05 or 07.
  3. Set the next one byte to 6, which is 3-D Secure Data (variable), in the following format:

       

        XXDDD…DDD

        where:

          XX is the length of data to follow (1 byte hex)

          DDD…DDD is the onlinePaymentCryptogram.

 

         Following are the variable data formats:

 

    • MasterCard – AAV
    • Visa – CAVV + XID (optional)
    • American Express – AEVV + XID (optional)
    • Discover – CAVV

 

Only include variable data, <DATA>, for the specific electronic commerce transactions that require it; otherwise, only send the <EC> value.

 

  1. In the next 20-40 bytes (<DATA>), supply the paymentData provided by Apple and converted to hexadecimal. MasterCard, Visa and American Express result in a 20 bytes hexadecimal value

 

2 - Byte Electronic Commerce/MOTO Indicator <EC>

ValueDescription
01

Single 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
3

Visa Transaction ID (XID)

Syntax: DDD..DDD where:

DDD..DDD = 20 byte XID (optional for Verified by Visa)

4

Cardholder Authentication Verification Value (CAVV)

Syntax: DDD..DDD where:

DDD..DDD = 20 byte CAVV (Required for Verified by Visa)

5

Universal Cardholder Authentication Field (UCAF)

Syntax: DDD..DDD where:

DDD..DDD = 20 byte UCAF (Required for MasterCard Secure Code – not BASE 64 encoded)

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

 

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.

 

 

Attachments

    Outcomes