Android Pay Mobile Web on eCommerce via eProtect

Document created by gjsissons on Aug 29, 2016Last modified by gjsissons on Aug 18, 2017
Version 19Show Document
  • View in full screen mode

 

Overview

These notes are intended for developers or merchants adding Android Pay Mobile Web functionality to their website and processing transactions against Vantiv's eCommerce platform.

 

Android Pay Mobile Web relies on the W3C Payment Request API co-developed by Google, Microsoft, Facebook and others. The purpose of the specification is to standardize an API to allow merchants on websites selling physical or digital goods to utilize one or more payment methods with minimal integration methods. Browser support for this API is evolving. At the time of this writing the API is fully supported on the Chrome Browser on Android and partially supported in the latest Microsoft Edge browser. You can see a table detailing compatibility here. Although the API can be used to support payments with credit cards and other payment sources, the primary use case discussed here is making one-touch payments from the Android Pay mobile wallet.

 

Vantiv supports two distinct integration methods using the browser based PaymentRequest API:

 

  • Gateway Token approach (using Vantiv eProtect) - With this integration method, Google handles the process of obtaining a token from Vantiv in exchange for valid payment credentials. Vantiv calls this token the low-value token or LVT. The token is exchanged for payment credentials directly via a server-to-server connection between Google and Vantiv. This approach is simpler for the developer, because they do not need to worry about decrypting the response to the PaymentRequest. They can simply use the LVT directly as a payment method.
  • Network Token approach - With this integration approach, suitable for developers or merchants not using Vantiv's eProtect service, the PaymentRequest API returns an encrypted network token bundle and the developer is responsible for decrypting this bundle themselves. Once decrypted, the developer will use the Network Token to process payments with Vantiv.  Vantiv's eCommerce platform supports <androidpay> tags as described in the Vantiv cnpAPI Reference Guide allowing the Android Pay Network Token to be used as a payment source.

 

The procedure described here pertains to the first of these two integration methods, the Gateway Token Approach using eProtect.

 

This guide assumes that the reader has some familiarity with Vantiv's eCommerce platform.

 

If you are new to Vantiv, please 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 needs.

 

[top]

 

Vantiv eProtect and your Android Pay Mobile Web Application

 

If you are adding Android Pay as a method of payment via the PaymentRequest API, you are probably already accepting credit cards on your website. Developers should be aware that their website will need to continue to support payments both inside and outside the control of the PaymentsRequest API. This is necessary because not all visitors will have a browser capable of supporting the W3C PaymentRequest standard required for one-touch Android Pay payments.

 

Vantiv eProtect is a good solution for accepting card payments from browsers that do not support the PaymentRequest API.  eProtect makes it easy to capture and vault sensitive cardholder data from a web page without needing to handle cardholder information directly, thus reducing PCI scope. An eProtect JavaScript component running in the browser captures the sensitive fields, and calls Vantiv's eProtect service. eProtect returns a low-value token (LVT) that can be used to process payments with Vantiv.  If you are not already familiar with how to use eProtect for eCommerce purchases made with credit cards, you can review the Vantiv eProtect Integration Guide.

 

Merchants can use a standard eProtect eCommerce integration to handle payments for browsers that don't implement the PaymentsRequest API, and then add additional logic for browsers supporting the PaymentRequest API to support Android Pay Mobile Web payments. This way customers will always be able to make a purchase regardless of whether their computer, phone or tablet supports Android Pay and regardless of the browser they are using.

 

The advantage of using eProtect is that the same LVT is used regardless of whether payments are made inside or outside of the control of the PaymentRequest API. This simplifies integrations since Authorizations can be handled the same way regardless of the whether the payment source is Android Pay or a credit card.

 

 

How the PaymentRequest API works with Vantiv's eProtect service

 

The steps below, explain the high level flow of a payment transaction made from a web-enabled payment application from a browser that implements the PaymentRequest API.

 

  1. The Web Application will first need to determine whether the the PaymentRequest API is available in the client's browser. If it is not available, the application will need to fall-back to a standard eProtect integration path not involving Android Pay, or a different payment integration method outside of the PaymentRequest API.
  2. Assuming the client browser and device supports Android Pay Mobile Web, the application will create a PaymentRequest object that provides important information like cards supported and the Vantiv account credentials required for Google to connect to Vantiv's eProtect service on the merchant's behalf.
  3. When the consumer clicks the "Pay" button in web application (presented by the PaymentRequest API), the browser sends details of the payment request information along with the Vantiv eProtect credentials to Google.
  4. Google in turn call's Vantiv's eProtect service (an HTTP POST API), Vantiv vaults the payment credentials, and Google receives back a low-value token (LVT) in response.
  5. Google then relays the response containing the LVT back to the browser.
  6. From here, the web application will typically post the LVT to the merchant's web-server and the server will initiate a payment transaction such as a Sale or Authorization using LVT as the source of payment. These payment transactions are implemented by POSTing XML to Vantiv's eCommerce endpoint (separate from the eProtect endpoint), or by using one of Vantiv's eCommerce SDKs to construct payment transactions on your behalf.
  7. Vantiv then processes your transaction normally and returns the results along with a high-value token (HVT) that can be safely stored and used to reference the vaulted payment credentials in future transactions. The web application then presents the success or failure of the payment transaction to the web-site user re-directing them as appropriate.

 

[top]

 

Requirements & Prerequisites

 

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:

  • A first step in building an Android Pay Mobile Web integration is to sign up with Google. You can use the same sign up process for Android Pay Mobile Web integrations as you use for In-App integrations. Once you sign up, you will receive a merchant identifier.
  • Ensure that you have reviewed the Payment Request API Integration Guide on the Google developer site.
  • Review also the Google documentation about Integrating Android Pay into the Payment Request.
  • As you start coding, you'll need to refer to the PaymentRequest API specification as well.
  • If you are already integrated with Vantiv, you will want to make sure that you are supporting a version of LitleXML that supports Android Pay. Vantiv recommends LitleXML version 9.9 or later. You can view the Vantiv cnpAPI Reference Guide that has a section specific to Android Pay. You should also review the Vantiv eCommerce Solution for Android Pay documentation that covers both in-app and mobile web payments.
  • To facilitate testing, you'll want to make sure you have the Android Pay app loaded and that you add a card into the app. Instructions are provided here. You'll also want to make sure you have access to Google's Android Pay test environment.
  • To code and test payment transactions against Vantiv's eCommerce environment, you will need to work with a Vantiv integration consultant. If you don't already have an assigned consultant, please Contact us. 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 credentials for Vantiv's payment platforms as well as separate credentials required for the Vantiv eProtect service. 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]

 

Check that the browser supports the Payment Request API (required for Android Pay)

 

The PaymentRequest API is an emerging feature, and many browsers still do not support it. You'll need to insert logic into your web application to determine whether the browser visiting your site even supports the API. Details are provided in the Google Payment Request API documentation.

 

An example of code to check for browser support (from the Google documentation) is provided below:

 

if (window.PaymentRequest) {
  // PaymentRequest supported
  // Continue with PaymentRequest API
} else {
  // PaymentRequest NOT supported
  // Continue with existing form based solution or eProtect integration
}

 

Assuming the PaymentRequest API is supported in the browser, you will still want to check whether a user has a valid payment method available in their wallet. You can use the canMakePayment() method to check this using code like the example below.

 

If there is no method of payment available, you may want to direct the user to a page that implements the standard eProtect web checkout option or another pre-existing method capturing a payment method.  The developer can also choose to accept a credit card on supported browsers using the PaymentRequest API even though there may not be a card loaded into the Android Pay wallet.

 

// Check if `canMakePayment()` exists as older Chrome versions
// don't support it.
if (request.canMakePayment) {
  request.canMakePayment().then(result => {
    if (result) {
      request.show();
    } else {
      // The user doesn't have an active payment method.
      // Forwarding to legacy form based experience or standard eProtect method
      location.href = '/checkout';
    }
  }).catch(error => {
    // Unable to determine.
    request.show();
  });
} else {
  request.show();
}

 

[top]

 

Creating the Android Pay PaymentRequest()

Before you can create a PaymentRequest object that will display the Android Pay checkout page, you will need to populate a JSON structure called supportedInstruments as shown below. This example shows how to identify Vantiv as your payment processor using the Gateway Token / eProtect integration method as explained above.

 

 

var supportedInstruments = [
  {
    supportedMethods: ['basic-card']
    data: {
      supportedNetworks: ['amex', 'discover', 'mastercard', 'visa']
    }
  },
  {
    supportedMethods: ['https://android.com/pay'],
    data: {
      //merchant ID obtained from Google that maps to your origin
      merchantId: '02510116604241796260',
      environment: 'TEST',
      // Credit Cards allowed via Android Pay
      allowedCardNetworks: ['AMEX', 'MASTERCARD', 'VISA', 'DISCOVER'],
      paymentMethodTokenizationParameters: {
        tokenizationType: 'GATEWAY_TOKEN',
        parameters: {
          'gateway': 'vantiv',
          'vantiv:merchantPayPageId': 'payPageId',
          'vantiv:merchantOrderId': 'OrderId',
          'vantiv:merchantTransactionId': 'id',
          'vantiv:merchantReportGroup': 'reportGroup'
        }
      }
    }
  }
];

 

The payPageId will be provided by your Vantiv integration consultant. This is the ID used by Google to connect to Vantiv's eProtect service on behalf of the merchant to exchange payment credentials for Vantiv's low-value token.

 

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 cnpAPI Reference Guide.

 

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

 

You will also need to specify the merchantId assigned to you by Google. Note that this example shows testing against Google's Android Pay test environment. Remove the line environment: 'TEST' to process against the live environment.

 

With the supportedInstruments() structure correctly setup you can create the PaymentRequest object and present the payment interface to the user as shown below.

 

Note that additional details and options will need to be specified when creating the payment object as well. These details are not covered here.

 

var payment = new PaymentRequest(
  supportedInstruments, // required payment method data
  details,              // required information about transaction
  options               // optional parameter for things like shipping, etc.
);


payment.show().then(function(response) {
  // Process response
  response.complete("success");
}).catch(function(err) {
  console.error("Uh oh, something bad happened", err.message);
});

 

[top]

 

 

Request Authorization or Sale with Vantiv

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

 

Once you have the LVT retrieved from the PaymentResponse (the eCommerce document refers to this LVT as the payPageRegistrationId) , processing the Android Pay transaction is similar to any other card not present eProtect eCommerce transaction from Vantiv's perspective.

 

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. They will typically follow this up with a Capture transaction once goods are shipped to actually charge the credit card.

 

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.

 

 

In the eProtect integration method you will be using the Gateway Token (paypageRegistrationId) returned in the PaymentResponse as the source of payment. This is also known as the low-value token (LVT) described earlier. The low-value token is encoded in the <paypage> element as shown below.  The example below shows testing against Vantiv's sandbox. You will likely need to substitute this endpoint for the pre-live environment using the URL recommended by your integration consultant.

 

#!/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 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 using Vantiv's eProtect service. 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 can be confident that the authorization was successful.

 

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

 

Additional Resources

Attachments

    Outcomes