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.
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.
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:
- Register a Merchant ID. You can use your existing Merchant ID if you already use Apple Pay In-App payments.
- 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.
- 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.
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:
- 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.
- 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.
- The Safari browser posts the PKPaymentToken to your server.
- 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.
- Vantiv submits the authorization to the card networks and receives an approval or a decline.
- Your server receives an aproval or a decline.
- You return the response to the website and handle it appropriately.
The high-level process flow is shown below:
Decrypting the PKPaymentToken
The structure of the PKPaymentToken is shown below:
Payment Data Keys
After the decryption of the PKPaymentToken, the payment data contains the following keys and values:
|applicationPrimaryAccountNumber||String||Device-specific account number of the card that funds this transaction|
|applicationExpirationDate||Date as a string||Card expiration date in the YYMMDD format|
|currencyCode||String||ISO 4217 numeric currency code, as a string to preserve leading zeros|
|cardholderName||String||Cardholder name (optional)|
|deviceManufacturerIdentifier||String||Hex-encoded device manufacturer identifier|
|paymentDataType||String||3DSecure or EMV (EMV is for future use.)|
|paymentData||Payment data dictionary||Detailed 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 Value||ISO8583||Field Note|
|applicationPrimaryAccountNumber||Field 2 – Primary Account Number|
|applicationExpirationDate||Field 14 – Date, Expiration||Vantiv only supports YYMM; the merchant must truncate DD before submitting.|
|currencyCode||Field 49 – Currency Code, Transaction|
|transactionAmount||Field 4 – Amount, Transaction|
|paymentData||Field 126||See "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
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>
|05||Verified by Visa authenticated or MasterCard Secure Code with AAV data|
|07||Electronic commerce, but neither Verified by Visa nor MasterCard Secure Code|
|20||Token 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>|
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:
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
- Vantiv ISO 8583 Specification - Network Tokenization (ApplePay)
- Apple Pay JS API (for incorporating Apple Pay into your website)
- Vantiv ISO 8583 Specification
- Vantiv Online Systems 610 Interface Reference Guide