Apple Pay In-App on Core Integration Process

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



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.




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:




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


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

Visa Transaction ID (XID)

Syntax: DDD..DDD where:

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


Cardholder Authentication Verification Value (CAVV)

Syntax: DDD..DDD where:

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


Universal Cardholder Authentication Field (UCAF)

Syntax: DDD..DDD where:

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


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.


Populating Point of Service Entry Mode (Field 22)


  • Field 22 – Point of Service Entry Mode = 81