Method 1 - In-App Integration via eProtect

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

 

Overview

This is the recommended method of implementing Apple Pay™ for Mobile Applications on the Vantiv eCommerce platform. In this method of integration, the Apple Pay PKPaymentToken (defined in Apple documentation; please refer to https://developer.apple.com/library/ios/documentation/PassKit/Reference/PaymentTokenJSON/PaymentTokenJSON.html) is vaulted by Vantiv's eProtect™ (formerly PayPage) service.

 

If you are already using Vantiv's eProtect service there will be minimal impact to your application since payment processing with Apple Pay is the same as with an eProtect eCommerce application.

 

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 Vantiv's eProtect service.

 

  • 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 eProtect, you can learn more about it in the Vantiv eProtect Integration Guide.
  • 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. Depending on the integration method you choosev, Vantiv will decrypt the PKPaymentToken for you or you will be required to do it yourself.

 

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 works with eProtect

 

In this scenario, your native iOS application performs an HTTPS POST of the Apple Pay PKPaymentToken using the Vantiv Mobile API for Apple Pay. From this point forward, your handling of the transaction is identical to any other eProtect transaction.

 

The eProtect server returns a PayPage Registration ID and your Mobile App (or server) constructs the LitleXML transaction using that ID. In this case, the first three steps are identical to those described above. The process after step 3 is as follows:

 

  1. Your native iOS application sends the PKPaymentToken to our secure server via an HTTPS POST (see Vantiv Mobile API for Apple Pay HTTPS POST Components) and eProtect returns a PayPage Registration ID.
  2. Your native iOS application forwards the transaction data along with the eProtect Registration ID to your order processing server, as it would with any eProtect transaction.
  3. Your server constructs/submits a standard LitleXML Authorization/Sale transaction using the PayPage Registration ID, setting the <orderSource> element to applepay.
  4. Using the private key, Vantiv decrypts the PKPaymentToken associated with the PayPage Registration ID and submits the transaction with the appropriate information to the card networks for approval.
  5. Vantiv sends the Approval/Decline message back to your system. This message is the standard format for an Authorization or Sale response and includes the Vantiv token.
  6. You return the Approval/Decline message to your mobile application.

 

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

 

vantiv_decryption_applepay.PNG

 

[top]

 

Requirements

 

Before you can proceed with building and testing an 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.
  • 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]

 

eProtect and Payment Network Tokenization

 

Normally, with most integration methods, Apple Pay provides an encrypted PKPaymentToken that when decrypted contains a d-pan, often referred to as a network token. The d-pan has the same format as a payment card primary account number (PAN), however it is a different number than the PAN stored in the Apple wallet. on receipt of the d-pan, the card brands are able to recognize the d-pan, and negotiate with Apple's servers to obtain the actual card information.

 

With eProtect, the process for the merchant is simplified. Rather than decrypting the Apple PKPaymentToken, you will simply send the token "as-is" to Vantiv's eProtect service in exchange for a paypageRegistrationID (also referred to as the low value token). The actual PKPaymentToken is vaulted in Vantiv's servers, so your application never needs to access it. The low-value token acts as a reference to the PKPaymentToken.

 

As we'll see below, the low-value token is all that is needed to perform an Authorization or Sale with Vantiv. When you provide the low-value token with an Authorization or Sale transaction, Vantiv's servers will respond with the high-value token that can be used for subsequent payment transactions (for example a Void or Refund). This is explained below and additional information is provided in the Vantiv eProtect Integration Guide.

 

Note that the the merchant's servers never have access to the network token nor the customer payment card data using this integration approach. This provides an extra level of security for Apple Pay transactions.

 

[top]

 

Obtaining credentials from Vantiv

 

To build and test an application that processes transactions with Vantiv via eProtect, you'll need access to two sets of network endpoints

 

  • Endpoints for the eProtect service (called by your iOS application)
  • Endpoints to accept transactions (called by your server)

 

For each of these endpoints there are pre-live, certification and production URLs. You will need your integration consultant to furnish you with credentials for the 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]

 

Contact eProtect from your iOS application

 

On receipt of a PKPaymentToken, your native iOS application will need to send the PKPaymentToken to Vantiv's eProtect server via an HTTPS POST in return for a PayPage Registration ID. This interface from iOS is referred to in the Vantiv documentation as the "Vantiv Mobile API for Apple Pay".

 

It is up to the iOS developer to construct the HTTPS POST, however the Apple specific fields that need to be provided in the POST are detailed here:

Parameter NameDescription
applepay.data

Payment data dictionary, Base64 encoded as a string. Encrypted Payment data.

applepay.signature

Detached PKCS #7 signature, Base64 encoded as string. Signature of the payment and header data.

applepay.versionVersion information about the payment token.
applepay.header.applicationData

SHA-256 hash, hex encoded as a string. Hash of the applicationData property of the original PKPaymentRequest.

applepay.header.ephemeralPublicKey

X.509 encoded key bytes, Base64 encoded as a string. Ephemeral public key bytes.

applepay.header.publicKeyHash

SHA-256 hash, Base64 encoded as a string. Hash of the X.509 encoded public key bytes of the merchant's certificate.

applepay.header.transactionId

Hex identifier, as a string. Transaction identifier, generated on the device.

 

An example cURL script shows how these fields above are posted to the eProtect endpoint (in this case Vantiv's pre-live environment). You will need a paypageId from Vantiv to call the eProtect server.

 

Note that in addition to the Apple specific parameters above, parameters specific to Vantiv eCommerce need to be posted as well to make sure that Vantiv can identify and report on the transaction. These include the paypageId, the reportGroup, the orderId and the transaction Id.

 

These variables are defined in the LitleXML Reference Guide.

 

$ curl --verbose -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Host:MerchantApp" \
    -H "User-Agent:Litle/1.0 CFNetwork/459 Darwin/10.0.0.d3" \
-d "paypageId=a2y4o6m8k0&reportGroup=*merchant1500&orderId=PValid&id=1234&applepay.data=HT897mACd%2F%2FT
pWe10A5y9RmL5UfboTiDIvjni3zWFtyy8dtv72RJL1bk%2FU4dTDlrq1T1V2l0TSnI%0APLdOnn HBO51bt9Ztj9odDTQ5LD%2F4hMZT
Qj3lBRvFOtTtjp9ysBAsydgjEjcCcbnkx7dCqgnwgzuz%0Ay7bX%2B5Fo8a8R <abbreviated>
d792df7c38f301300085dd463e347453ae72debf6f4d14&applepay.header.ephemeralPublicKey=MFkwEwY HKoZIzj0CAQYI
KoZIzj0DAQcDQgAEarp8xOhLX9QliUPS9c54i3cqEfrJD37NG75ieNxncOeFLkjCk%2FBn3jVxHlecRwYqe%2BAWQxZBtDyewaZcmW5l
g%3D%3D
&applepay.header.publicKeyHash=zoV5b2%2BmqnMIxU9avTeqWxc7OW3fnKXFxyhY0cyRixU%3D
&applepay.header.transactionId=23e26bd8741fea9e7a4d78a69f4255b315d39ec14233d6f1b32223d1999fb99f" 
https://request-prelive.np-securepaypage-litle.com/LitlePayPage/paypage 

 

 

Variables returned to your iOS client from the POST to the eProtect servers are listed below:

Parameter NameDescription
paypageRegistrationIdThe temporary identifier used to facilitate the mapping of a token to a card number.
reportGroup(Mirrored back from the request) The LitleXML required attribute that defines under which merchant sub-group this transaction will be displayed in iQ Reporting and Analytics.
orderId(Mirrored back from the request) The merchant-assigned unique value representing the order in your system.
id(Mirrored back from the request) The LitleXML required attribute that assigned by the presenter and mirrored back in the response.
litleTxnIdThe automatically-assigned unique transaction identifier.
firstSix(Mirrored back from the request) The first six digits of the credit card number.
lastFour(Mirrored back from the request) The last four digits of the credit card number.

[top]

 

Relay payment details from iOS to the merchant server

 

At this point, the iOS application will have received the information above required to process a 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 parameters received above in response to the eProtect POST along with other details about the transaction to the merchant server.

 

[top]

 

Request Authorization or Sale with Vantiv

 

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.

 

Once you have the paypageRegistrationId from Vantiv, processing the Apple Pay transaction is identical to any other card not present eProtect eCommerce transaction.

 

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.

 

With the eProtect integration method described here, you will be using the paypageRegistrationId returned by eProtect as the source of payment.

 

Payment information will be included in the <paypage> element as shown below.

 

Note that you will need to set the ordersource element to "applepay" so that Vantiv understands that it is dealing with a vaulted PKPaymentToken rather than actual card data.

 

#!/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>
        <authorization id="ididid" reportGroup="rtpGrp" customerId="12345">
            <orderId>1</orderId>
            <amount>1000</amount>
            <orderSource>applepay</orderSource>
            <billToAddress>
                <name>Jane Doe</name>
                <addressLine1>20 Main Street</addressLine1>
                <city>San Jose</city>
                <state>CA</state>
                <zip>95032</zip>
                <country>USA</country>
                <email>jdoe@litle.com</email>
                <phone>978-551-0040</phone>
            </billToAddress>
            <paypage>
                <paypageRegistrationId>9999999999999</paypageRegistrationId>
            </paypage>
        </authorization>
      </litleOnlineRequest>'

 

 

[top]

 

Parsing the Authorization response

 

In production, the Authorization transaction would be expected to result in a response similar to the one below (illustrated using our sandbox environment).

 

The Authorization example above uses the paypageRegistrationId to reference the actual d-pan stored in Vantiv's vault. Vantiv will process the authorization through to the card networks, and return an XML response message.

 

 

<litleOnlineResponse version='10.1' response='0' message='Valid Format' xmlns='http://www.litle.com/schema'>
  <authorizationResponse id='ididid' reportGroup='rtpGrp' customerId='12345'>
    <litleTxnId>830043457072336000</litleTxnId>
    <orderId>1</orderId>
    <response>000</response>
    <responseTime>2016-08-29T10:05:04</responseTime>
    <message>Approved</message>
    <authCode>45140</authCode>
    <tokenResponse>
      <litleToken>1234567890123456</litleToken>
      <tokenResponseCode>801</tokenResponseCode>
      <tokenMessage>Account number was successfully registered</tokenMessage>
      <type>VI</type>
      <bin>123456</bin>
    </tokenResponse>
  </authorizationResponse>
</litleOnlineResponse>

 

The response is "000" and the message is "Approved" indicating that the authorization is successful.

 

Following a successful authorization, the merchant will typically issue a subsequent Capture transaction to Vantiv to move the funds from the cardholder's issuing bank to the merchant account when goods are shipped or services are performed.

 

In addition to responding with a message and authCode, a <litleToken> element is returned. This is referred to as the high-value Token. This token is used by Vantiv to replace the Network Token that was vaulted in Vantiv's eProtect servers. The use of this token provides an extra layer of security because the merchant never has access to the Network Token when eProtect is used.

 

On receipt of the Authorization response message above, the application will relay the result of the transaction to the iOS application on the client device.

 

[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="rtpGrp" 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='rtpGrp' customerId='12345'>
    <litleTxnId>632929357249868001</litleTxnId>
    <response>001</response>
    <responseTime>2016-08-29T10:26:35</responseTime>
    <message>Transaction Received</message>
  </captureResponse>
</litleOnlineResponse>

Attachments

    Outcomes