Method 3 - In-App Integration (Merchant Decryption)

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

 

Overview

 

This is the third method of integrating In-App Apple Pay payments with Vantiv eCommerce. 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 eCommerce 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 LitleXML.

 

  • 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.
  • If you are not familiar with Vantiv's eCommerce Platform, our LitleXML Reference Guide provides an excellent primer
  • This guide assumes that the developer is already familiar with Apple iOS application development.

 

[top]

 

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 application 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 and a cryptogram. The network payment token is sometimes referred to simply as the network token.
  3. Apple Pay returns the Apple PKPaymentToken to your application.

 

[top]

 

How Apple Pay payments are processing using this integration method

 

Using this process, the responsibility for the decryption of the PKPaymentToken from Apple Pay falls to the merchant or developer.

 

After completing the first three steps above, the process continues as follows:

 

  1. 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).
  2. Using your private key, you decrypt the PKPaymentToken, construct the Authorization/Sale transaction, and submit it to Vantiv. In this case, you would populate the LitleXML <number> element with the device primary account number, the <expDate> element with the expiration date, and the <authenticationValue> field with the cryptogram extracted from the PKPaymentToken. Also, set the <orderSource> element to applepay (Server-side API submit).
  3. Vantiv detects that this is an Apple Pay transaction and submits the transaction with the appropriate information to the card networks for approval.
  4. Vantiv sends the Approval/Decline message back to your system, using the standard format for an Authorization or Sale response.
  5. You return the Approval/Decline message to your mobile application.

 

These steps are shown in the form of a diagram below:

 

merchant_decryption_of_token.PNG

 

[top]

 

Requirements

 

Before you can proceed with building and testing an integration, please make sure you have access to the following resources below:

  • If you are already integrated with Vantiv, you will want to make sure that you are supporting a version of LitleXML that supports Apple Pay in-app payments. Depending on the version of LitleXML you are integrated with, the following minimum versions are supported:
    • LitleXML 8.29
    • LitleXML 9.2
    • LitleXML 10.0
  • While Vantiv has a sandbox that developers can use to get started and code payment transactions against our eCommerce environment, 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. You can also send an e-mail at anytime to customerservice@litle.com to get connected with an integration consultant. The consultant will be able to provide you with test credentials for Vantiv's various test environments and provide credentials for Vantiv's eProtect service (if you don't already have them) that you will need in later steps below. Vantiv has different test environments including a sandbox, pre-live and post-live environment. You can learn more about these environments in Certification and Testing Environments.
  • Before starting and integration with Vantiv, it is a good idea to review our Onboarding FAQ.

 

[top]

 

Obtaining credentials from Vantiv

 

To build and test an application that processes transactions with Vantiv, you'll need access to our network endpoints

 

Our endpoints have sandbox, pre-live, certification and production URLs. Other than the sandbox, which is open to all, you will need your integration consultant to furnish you with credentials to access our other endpoints.

 

If you know who your integration consultant is, they can provide this information.

 

Otherwise, you can start the ball rolling by requesting credentials here. All you need is your e-mail address and organization name.

 

[top]

 

Relay payment details from iOS to the merchant server

 

Integration requirements to Vantiv start when your client iOS application is in possession of the PKPaymentToken along with other details of the payment transaction.

 

Normally, calls to Vantiv's eCommerce platform are made from the merchant server rather than the iOS client since you will want to update log files and interface to inventory, order management or other systems.

 

You will want to send the the PKPaymentToken along with other relevant details to your merchant server.

 

[top]

 

Decrypting the PKPaymentToken

 

Apple provides details about the PKPaymentToken and how to decrypt it in the iOS developer library.

 

You can find details in the Payment Token Format Reference here: Payment Token Format Reference

 

The structure of the PKPaymentToken is shown below:

 

PKPaymentToken_structure.PNG

The steps involved in extracting the Payment data from the token are detailed in the Apple Payment Token Format Reference

 

You can find sample Java code here that shows how to decrypt the PKPaymentToken.

 

[top]

 

Extracting the contents of the decrypted PKPaymentToken

 

The table below shows elements of the decrypted PKPaymentToken to be passed to Vantiv as part of an Authorization or Sale transaction.

 

Parameter NameDescription
numberThis is the Mod-10 compliant card number. For testing you can use the test numbers in Chapter 2 of the Vantiv LitleXML Reference Guide
expDateThe expiration date for the card
authenticationValue

This is the cryptogram extracted from the decrypted PKPaymentToken. For testing you can use any Base-64 encoded value between 40 and 56 characters in length

orderSourceSet to applepay

 

[top]

 

Request Authorization or Sale with Vantiv using <card> element

 

Processing payments with Vantiv is done by posting appropriately formatted XML messages via HTTPS POST to the Vantiv end-point (URL) supplied by your integration consultant. This is described in detail in the Vantiv LitleXML Reference Guide.

 

Typically, merchants will first use an Authorization transaction to confirm that the customer has submitted a valid payment method with their order and that the card provided has sufficient funds to purchase the goods or services ordered.

 

An approved authorization reduces the customer's credit limit (or bank balance in the case of a debit card) by the amount of the authorization.

 

You can examples of different common payment transactions under XML Transaction Examples along with explanations of what the transactions do.

 

Best practices for payment transactions will vary depending on whether you are selling a service on-line or physical goods.

 

Vantiv provides two useful quick start guides that explain the transactions you will most likely use in both cases.

 

 

As a developer, you can choose to interact with Vantiv's eCommerce platform for processing transactions either by sending XML messages directly to our endpoint (as shown below) or by using one of the available SDKs for Vantiv eCommerce.

 

The SDKs are provided for convenience to generate XML messages similar to those below. Developers will generate this XML message using their preferred programing environment and post the message to the provided endpoint.

 

<litleOnlineRequest version=“10.3" xmlns="http://www.litle.com/schema" merchantId="default">
       <authorization id="ididid" reportGroup="rptGrp" customerId="12345">
             <orderId>1</orderId>
             <amount>1000</amount>
             <orderSource>applepay</orderSource>
             ..
            <card>
                 <type>MC</type>
                 <number>5112010000000003</number>
                 <expDate>0221</expDate>
            </card>
            <cardholderauthentication>
                 <authenticationValue>BwABBJQ1AgAAAAAgJDUCAAAAAAA= </authenticationValue>
            </cardholderauthentication>
        </authorization>
 </litleOnlineRequest>

 

Note that the card type must be specified in the XML request above, but the card type is not included in the PKPaymentToken. The card type can be inferred from the card number.  Vantiv provides documentation on Credit Card Number Formats that will be helpful in deciding what to submit in the type field.

 

[top]

 

Capturing the Transaction

 

When the merchant wants to Capture the payment associated with the Authorization (to actually move the funds), they do so by referencing the litleTxnId returned in the response to the authorization request. A raw XML message that accomplishes this continuing the example is shown here.

 

As before, the implementation of the capture will depend on the programming language and whether the merchant is using Vantiv's SDKs, but an example using cURL is provided for clarity.

 

#!/bin/sh
curl https://www.testlitle.com/sandbox/communicator/online --tlsv1.2  \
   -H "Content-Type: text/xml; charset=UTF-8"  \
   -X POST  \
   -d  \
     '<?xml version="1.0"?>
      <litleOnlineRequest version="10.3" xmlns="http://www.litle.com/schema" merchantId="default">
        <authentication>
            <user>JoesStore</user>
            <password>JoeyIsTheBe$t</password>
        </authentication>
        <capture id="ididid" reportGroup="rptGrp" customerId="12345">
            <litleTxnId>83004345707233600</litleTxnId>
        </capture>
      </litleOnlineRequest>'

 

The returned XML message from the Capture transaction confirms that the Capture was processed successfully.

 

The response can be parsed, and relayed to the application.

 

<litleOnlineResponse version='10.1' response='0' message='Valid Format' xmlns='http://www.litle.com/schema'>
  <captureResponse id='ididid' reportGroup='rptGrp' customerId='12345'>
    <litleTxnId>632929357249868001</litleTxnId>
    <response>001</response>
    <responseTime>2016-08-29T10:26:35</responseTime>
    <message>Transaction Received</message>
  </captureResponse>
</litleOnlineResponse>

 

[top]

Attachments

    Outcomes