Android Pay using eProtect

Document created by gjsissons on Aug 2, 2016Last modified by gjsissons on Aug 14, 2017
Version 22Show Document
  • View in full screen mode

 

Overview

This is the recommended method of implementing Android Pay for Mobile Applications on the Vantiv eCommerce platform.

This guide assumes that the reader has some familiarity with Vantiv's eCommerce platform. It explains the necessary steps to support Android 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 Android Pay. Before starting a project, please contact us and speak to an integration consultant so we can help you choose an integration method appropriate for your business.
  • If you are not familiar with Vantiv eProtect, you can learn more about it in the Vantiv eProtect Integration Guide. Note that Android Pay integration with eProtect is simplified because Google calls the eProtect service on your behalf. Your application will not need to call eProtect directly.
  • This guide assumes that the developer is already familiar with Android application development and that you have access to Android Studio or another IDE suitable for Android application development.
  • The best place to start getting familiar with Android Pay for in-app payments is at the Android Pay page on the Google Developer's website - Android Pay API Overview  |  Android Pay  |  Google Developers.
  • Google provides an excellent sample application that is instructive for Android developers . If you are new to Android Pay, we recommend that you download this example and load it into Android Studio. When reviewing the documentation below it may be helpful to have this sample application available in Android Studio for reference.

 

[top]

 

How Android Pay works with eProtect

The steps below, illustrate the high level flow of messages during an Android Pay purchase using the Vantiv eProtect service. The steps are first presented at a high level, and are explained in detail in the sections that follow.

 

  1. When the consumer clicks the Android Pay button in your application, the action triggers a MaskedWalletRequest to Google. In the MaskedWalletRequest, you must set a new object PaymentMethodTokenizationParameters indicating that you are using Vantiv's eProtect.  The information returned by Google in the MaskedWallet object will include details like a masked card number (last-four digits exposed), shipping information and cart. The consumer has the option of changing this information from their mobile device. If any info changes, Android Pay returns an updated MaskedWallet object to your application.
  2. Upon confirmation of the order by the consumer the application then requests the FullWallet from Google via a  FullWalletRequest.
  3. After receiving the FullWalletRequest from your application, Google submits the card information to Vantiv eProtect on your behalf. Vantiv "vaults" the actual payment details. The eProtect servers then return a low-value token to Google for the transaction (this is referred to be Vantiv as the paypageRegistrationId or sometimes as the "low-value token").
  4. Google returns the paypageRegistrationId token to your Android Pay application along with the Full Wallet information.
  5. Your Android Pay application then sends the payment transaction information to your servers along with the paypageRegistrationId token. Your servers then submit the Authorization / Sale transactions to the Vantiv eCommerce platform. You must set the orderSource element in the XML transaction to "androidpay" (explained below)
  6. Vantiv then processes your transaction normally and returns the results along with a high-value token that can be used to reference the vaulted payment credentials in future transactions.

 

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

 

eProtect_android_pay_flow.PNG

 

[top]

 

Requirements

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

  • Ensure that you have reviewed the Android Pay API overview documentation on the Google developer site.
  • If you are already integrated with Vantiv, you will want to make sure that you are supporting a version of the cnpAPI (formerly LitleXML) that supports Android Pay in-app payments. Vantiv recommends cnpAPI version 9.9 or later. You can view the Vantiv eCommerce cnpAPI Reference Guide that has a section specific to Android Pay.
  • 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 testing 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.
  • You will also need an Android Pay client ID and credentials. The process for obtaining this is included in the Google Android Pay documentation referenced below.
  • 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, Android Pay provides a Payment Network Token that presents the Primary Account Number of the card loaded in the the Google wallet used for payment.

 

With eProtect, the process is different. As a developer, you don't need to worry about handling or decoding the Payment Network Token. Google calls Vantiv's eProtect service directly on your behalf, and exchanges the Payment Network Token for a paypageRegistrationID (also referred to as the low value token). The actual Payment Network Token is vaulted in Vantiv's servers and your application will not need access to it.

 

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 Payment Network Token nor the Customer Card Data. Vantiv's servers have access to the Payment Network Token, but not the Customer Card Data. This provides an extra level of security for Android Pay payment 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 Google on your behalf)
  • 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]

 

Check that the user is ready to pay with Android Pay

 

Sample code is shown in the Android Pay API tutorial under the heading "Check that the user is ready to pay with Android Pay"

 

The app calls Wallet.Payments.isReadyToPay() to determine if the user is able to make payments with Android Pay. If so, then the checkout screen layout includes an instance of the WalletFragment class set to BUY_BUTTON mode. In this mode, the fragment displays an Android Pay button.

 

[top]

 

Request a Payment Gateway Token

 

Before you can request any wallet information, you must build parameters to inform the Android Pay API what type of payment token you wish to receive in the response. In the case of an eProtect integration we want to receive a PAYMENT_GATEWAY token (as opposed to a NETWORK_TOKEN).

 

Note that the Android Pay documentation refers to this token as the "Gateway Token" whereas Vantiv's documentation refers to it as the eProtect "low value token" or the payPageRegistrationId. These terms can be viewed as interchangeable.

 

The payPageId will be provided by the integration consultant. This is the ID used by Google to connect to Vantiv's eProtect service on behalf of the merchant.

 

The orderId, id and reportGroup are specified by the merchant an are used to reference transactions in Vantiv's systems. These variables are explained in the Vantiv eCommerce cnpAPI Reference Guide.

 

Setting the PaymentMethodTokenizationParameters

 

PaymentMethodTokenizationParameters parameters =
PaymentMethodTokenizationParameters .newBuilder()
     .setPaymentMethodTokenizationType(PaymentMethodTokenizationType.PAYMENT_GATEWAY)
     .addParameter("gateway","vantiv")
     .addParameter("vantiv:merchantPayPageId",payPageId)
     .addParameter("vantiv:merchantOrderId",orderId)
     .addParameter("vantiv:merchantTransactionId",id)
     .addParameter("vantiv:merchantReportGroup",reportGroup)
     .build();

 

IMPORTANT: You must use the same orderId for all calls associated with the same trsnaction (i.e., Google, Register Token, Authorization, Sale, etc.). Failure to use the same orderId can prevent customers from tracking their orders using the Android Pay application.

 

[top]

 

Create the MaskedWalletRequest

When you create the MaskedWalletRequest in your code to get details of the MaskedWallet from Google, you will use the setPaymentMethodTokenizationParameters method to pass the PaymentMethodTokenizationParameters defined above.

 

Setting New Object in the MaskedWalletRequest

 

MaskedWalletRequest request = MaskedWalletRequest.newBuilder()  
    .setMerchantName(Constants.MERCHANT_NAME)  
    .setPhoneNumberRequired(true)  
    .setShippingAddressRequired(true)  
    .setCurrencyCode(Constants.CURRENCY_CODE_USD)  
    .setEstimatedTotalPrice(cartTotal)  
    // Create a Cart with the current line items. Provide all the information  
    // available up to this point with estimates for shipping and tax included.  
    .setCart(Cart.newBuilder()  
        .setCurrencyCode(Constants.CURRENCY_CODE_USD)  
        .setTotalPrice(cartTotal)  
        .setLineItems(lineItems)  
        .build())  
    .setPaymentMethodTokenizationParameters(parameters)  
    .build();

 

[top]

 

Add a purchase button with WalletFragment

A purchase button is displayed in your application using the WalletFragment class in the Google API. These is nothing specific to the payment provider in this process. Details are provided in the Android API tutorial under the heading "Add a purchase button with WalletFragment".

 

[top]

 

Request Full Wallet

Create a FullWalletRequest object as explained in the Android Pay API documentation that contains the various line items, tax and shipping where applicable, and a Cart object. Details and example code is provided in the Android Pay API tutorial under the heading "Request the FullWallet".

 

Once you have constructed the FullWalletRequest as explained above, use the Wallet.Payments.loadFullWallet(...) method to get the FullWallet object.

 

When you retrieve the Full Wallet in the callback, you can extract the payment method token as well as the tokenJSON as shown below.

 

// Get payment method token  
PaymentMethodToken token = fullWallet.getPaymentMethodToken();
// Get the JSON of the token object as a String  
String tokenJSON = token.getToken();

 

Because you are using eProtect, you will receive a gateway token. You can parse the tokenJSON variable above and retrieve the "id" field. This id field is the Vantiv low-value token (payPageRegistrationId) that you can use in subsequent calls to Vantiv.

 

You will want to post the payPageRegistrationId along with other details about the purchase to your server which will then initiate a connection to Vantiv to process the payment.

 

[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 eCommerce cnpAPI Reference Guide. Once you have the payPageRegistrationId from Vantiv, processing the Android 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 the ones below.

 

In the eProtect integration method you will be using the Gateway Token (paypageRegistrationId) returned by the Full Wallet Request as the source of payment. Payment information will be included in the <paypage> element as shown below.

 

#!/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>ecommerce</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>'

 

Note: The example above is provided for illustration only. At this time, Vantiv is unable to support end-to-end testing in our Pre-Live environment for Android Pay using eProtect option. Low-value tokens returned from Google are generated independently by their test environment. As a result, all transactions submitted using a low-value token returned by Google will result in a response message containing the Reason Code 878 - Expired PayPage Registration Id. This is explained in the Vantiv eCommerce cnpAPI Reference Guide.

 

[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 using the Gateway Token returned by Android Pay (the paypageRegistrationId) to generate an authorization response message from Vantiv's servers.

 

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. Captures are typically performed when goods are shipped.

 

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

 

Note that 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 by Google in Vantiv's PayPage 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 Android 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.

 

#!/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.

 

<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