Method 2 - In-App Integration via LitleXML

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




This is an alternate method of integrating In-App Apple Pay payments with Vantiv eCommerce.


Similar to the eProtect integration method, with this approach Vantiv takes responsibility for decrypting the PKPaymentToken.


The PKPaymentToken is passed to Vantiv via an Apple specific extension to Vantiv's LitleXML protocol specifying Apple Pay as the source of payment.


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




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, Vantiv will decrypt the PKPaymentToken for you.


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.




How Apple Pay payments are processing using this integration method


In this scenario, you submit the Apple Pay PKPaymentToken to the Vantiv eCommerce platform using LitleXML (see LitleXML <applepay> Structure), typically from your server.


As with the eProtect scenario, Vantiv decrypts the PKPaymentToken from Apple Pay using the private key.


After completing the first three steps (described 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. You do not decrypt the PKPaymentToken, but rather forward the data to Vantiv in the Authorization/Sale transaction using the <applepay> element structure instead of <card> (Server-side API submit) and setting the <orderSource> element to applepay.
  3. Using the private key retained by Vantiv, we decrypt the PKPaymentToken and submit 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 you mobile application.


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








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




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.




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 or order management or other systems.


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




Request Authorization or Sale with Vantiv using <applepay> 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.


When using the LitleXML integration method, you will be submitting the PKPaymentToken directly as a source of payment.


Vantiv's eCommerce service supports an <applepay> element where the PKPaymentToken can be submitted directly as a method of payment.



<litleOnlineRequest version=“10.3" xmlns="" merchantId="default">
       <authorization id="ididid" reportGroup="rtpGrp" customerId="12345">
              <data>User Name</data>
                 <applicationData>Base64 Hash of App Data Property</applicationData> 
                 <ephemeralPublicKey>Base64 Encoded Ephemeral Public Key</ephemeralPublicKey>
                 <publicKeyHash>Base64 Hash of Public Merchant Key Cert</publicKeyHash> 
                 <transactionId>Hex Transaction Id</transactionId>
              <signature>Signature of Payment and Header Data</signature>
              <version>Payment Token Version Info</version>





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.


curl --tlsv1.2  \
   -H "Content-Type: text/xml; charset=UTF-8"  \
   -X POST  \
   -d  \
     '<?xml version="1.0"?>
      <litleOnlineRequest version="10.3" xmlns="" merchantId="default">
        <capture id="ididid" reportGroup="rtpGrp" customerId="12345">


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=''>
  <captureResponse id='ididid' reportGroup='rtpGrp' customerId='12345'>
    <message>Transaction Received</message>