Android Pay on eCommerce (Merchant Decryption)

Document created by gjsissons on Aug 29, 2016Last modified by gjsissons on Sep 21, 2016
Version 8Show Document
  • View in full screen mode

 

Overview

 

The preferred method of using Android pay with Vantiv's eCommerce platform is using eProtect. If you are using eProtect, and wish to understand how in-app integrations are done, you can learn about the eProtect method here.

 

The integration method described below assumes that you don't want to use eProtect and that you wish to receive a Network Token from Google and decrypt it yourself.

 

Once you decrypt the Payment Token from Google, you can process payments against Vantiv's eCommerce platform as if it were a regular credit card transaction using the Android Pay furnished dpan in place of a regular credit card number.

 

An excellent overview of Payment Token Cryptography for developers is available here on the Google Android Pay developer site.

 

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 where the merchant decrypts the payment data themselves.

 

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

 

How Android Pay works with Vantiv eCommerce and the Merchant Decryption method

 

  1. When the consumer clicks the Android Pay button in your application, the action triggers a MaskedWalletRequest to Google. The information returned by Google in the MaskedWallet object may include a masked card number (last-four digits exposed) and shipping information. The consumer has the option of changing this information. If any info changes, Android Pay returns an updated MaskedWallet object.
  2. Upon confirmation of the order by the consumer your application initiates a FullWalletRequest to Google. Google also returns the encrypted payload. The encrypted payload is a UTF-8 encoded serialized JSON dictionary with the following keys:
    • encryptedMessage (string base64) - an encrypted message containing the payment credentials
    • ephemeralPublicKey (string base64) - the ephemeral public key associated with the private key to encrypt the message
    • tag (string base64) - MAC of encryptedMessage
  3. Your application sends the encrypted payload along with the transaction information to your server.
  4. Your server decrypts the encrypted payload extracting the payment, which is a UTF-8 encoded, serialized JSON dictionary with the following keys:
    • dpan (string (digits only)) - the device-specific personal account number (i.e., device token)
    • expirationMonth (number) - the expiration month of the dpan (1 = January, 2 = February, etc.)
    • expirationYear (number) - The four-digit expiration year of the dpan (e.g., 2015)
    • authMethod (string) - the constant 3DS (may change in future releases).
    • 3dsCryptogram (string) - the 3DSecure cryptogram
    • 3dsEciIndicator ((optional) string) - ECI indicator per 3DSecure specification

After decryption, submit the Authorization/Sale transaction to Vantiv, setting the orderSource element to androidpay and populating the following LitleXML elements with the decrypted information:

        • number - dpan value
        • expDate - MMYY derived from the expirationMonth and expirationYear values
        • authenticationValue - the 3dsCryptogram value

 

  5. Vantiv processes your transaction normally and returns the results in the response message.

 

These steps are summarized in the diagram below:

 

Merchant_decryption_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
            • 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. The consultant will be able to provide you with test credentials against Vantiv's "pre-live" environment (if you don't already have them) that you will need in later steps below.
            • You will also need an Android Pay client ID and credentials.

 

Payment Network Tokenization

 

This is provided for information only. When your Android Pay application interacts with Google, you will need to describe the type of payment token you wish to receive when an Android application user confirms a payment. There are two types of payment tokens supported by Android Pay:

 

            • A Gateway Token - Where Google provides a token that has particular meaning to  a payment provider (in the case of Vantiv an eProtect token for example)
            • A Network Token - Where Google provides a token similar to a PAN that has meaning to the card networks. Sometimes this is referred to simply as the "Payment Token"

 

If you are using this method of integration (where the merchant decrypts the token) you will be using a Network Token. The Network Token (also known as the d-pan) has all of the characteristics of a primary account number (PAN) but the actual underlying credit card is not passed on to the merchant nor the processor. The card networks will translate the Network Token to the actual associated card stored in the Google Wallet to be charged. Because the format of the Network Token matches that of an actual card, the card type can be inferred from the token.

 

The format of the d-pan adheres to ISO 7812 - Payment card number - Wikipedia, the free encyclopedia.

 

The Payment Tokenization Specification on the EMVCo website provides additional detail about the token format.

 

 

Obtaining credentials from Vantiv

 

To build and test an application that processes transactions with Vantiv , you'll need access to Vantiv's "pre-live" environment to test payment transactions. 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.

 

 

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

 

Request a Network Token

 

To advise Google that you wish to receive a Network Token (a token resembling a PAN described above) you will need to set the PaymentMethodTokenizationParameters appropriately.

 

Note that you are required to provide a public key. The publicKey parameter is the base-64 encoded version of your encryption key. For more information about generating this key, see Using OpenSSL to Generate and Format a Key. The Elliptic Curve method in this example is most common. and this is also the method used by Vantiv.

 

PaymentMethodTokenizationParameters parameters =  
    PaymentMethodTokenizationParameters.newBuilder()              
      .setPaymentMethodTokenizationType(PaymentMethodTokenizationType.NETWORK_TOKEN)  
        .addParameter("publicKey", publicKey)  
        .build();

 

 

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.

An example is shown below:

 

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();

 

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

 

Request Full Wallet

 

Create a FullWalletRequest object as explained in the Android Pay API documentation. It contains the various line items, tax and shipping details 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();

 

The encrypted payload of the response to the FullWalletRequest to Google will be a UTF-8 encoded serialized JSON dictionary with the following keys:

KeyValue
encryptedMessage(string base64) - an encrypted message containing the payment credentials
ephemeralPublicKey

(string base64) - the ephemeral public key associated with the private key to encrypt the message

tag(string base64) - MAC of encryptedMessage

 

Your application will send the encrypted payload above to your server along with other information about the transaction for decryption and processing.

 

Your server decrypts the encrypted payload extracting the payment, which is a UTF-8 encoded, serialized JSON dictionary with the following keys:

 

KeyValue
dpan(string (digits only)) - the device-specific personal account number (i.e., device token)
expirationMonth(number) the expiration month of the dpan (1 = January, 2 = February, etc.)
expirationYear(number) - The four-digit expiration year of the dpan (e.g., 2018)
authMethod(string) - the constant 3DS (may change in future releases)
3dsCryptogram(string) - the 3DSecure cryptogram
3dsEciIndicator((optional) string) - ECI indicator per 3DSecure specification

 

The approach to decrypting the Network Token (also referred to as the PaymentToken) is discussed in detail in the Android Pay. You can get the details and see a code example showing how the token at the Android Pay Payment Token Cryptography page.

 

An example of the decrypted JSON credentials from the Network Token return by the Full Wallet Request are shown below:

 

{
  “dpan”: “5454545454545454”,
  “expirationMonth”: 11,
  “expirationYear”: 2018,
  “authMethod”: “3DS”,
  “3dsCryptogram”: “AAAAAA...”,
  “3dsEciIndicator”: “eci indicator”
}

 

 

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 dpan (device primary account number) from the decrypted JSON payload above, processing the Android Pay transaction with Vantiv follows the same process as processing a payment with a credit card.

 

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 find examples of common payment transactions under XML Transaction Examples along with explanations of what the transactions do.

 

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.

 

The process below differs from the alternative eProtect integration method you would be using the Gateway Token (paypageRegistrationId) as the source of payment. In this case you will be submitting the d-pan from the encrypted JSON payload just as if it were a regular credit card number in the <card> element as shown below.

 

Note that the <type> element is required in the Vantiv authorization authorization when a card is used as a payment source, but the card type (Mastercard, Visa, Amex etc..) is not explicitly returned by the Full Wallet request. The developer will need to infer the card type based on the ISO 7812 - Payment card number - Wikipedia, the free encyclopedia. as discussed above. Because the dpan starts with "5" we know we are dealing with a MasterCard credit card, so "MC" is entered in the <type> element per the LitleXML specification.

 

#!/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="AndroidPay" customerId="12345">
            <orderId>1</orderId>
            <amount>1000</amount>
            <orderSource>androidpay</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@gmail.com</email>
                <phone>978-551-0040</phone>
            </billToAddress>
            <card>
                <type>MC</type>
                <number>5454545454545454</number>
                <expDate>1118</expDate>
                <cardValidationNum>123</cardValidationNum>
            </card>
        </authorization>
      </litleOnlineRequest>'

 

Note: The example above is provided only for illustration. This shell script is a representation of the format of a transaction that you would send to Vantiv. You will generate similar XML using your own code or using the Vantiv eCommerce SDK.

 

Notice that the payment credentials (d-pan) are provided in the card element. Note that at the time of this writing the Vantiv eCommerce sandbox does not support androidpay as a valid value for the ordersource element. This is supported in the Vantiv pre-live environment however for testing.

 

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

 

<litleOnlineResponse version='10.1' response='0' message='Valid Format' xmlns='http://www.litle.com/schema'>
  <authorizationResponse id='ididid' reportGroup='AndroidPay' customerId='12345'>
    <litleTxnId>888957951822447000</litleTxnId>
    <orderId>1</orderId>
    <response>000</response>
    <responseTime>2016-08-30T10:05:00</responseTime>
    <message>Approved</message>
    <authCode>49484</authCode>
  </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 cardholders issuing bank to their merchant account. Captures are typically performed when the goods are shipped.

 

The payment application will relay the result of the transaction to the Android application so that an appropriate message can be displayed.

 

Capturing the transaction

 

When the merchant wants to capture the payment associated with the authorization, they do so by referencing the litleTxnId returned in the response to the authorization request. (in the example above the litleTxnId is 888957951822447000)

 

#!/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>888957951822447000</litleTxnId>
        </capture>
      </litleOnlineRequest>'

 

The returned XML message below 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>478418122876277001</litleTxnId>
    <response>001</response>
    <responseTime>2016-08-30T10:36:14</responseTime>
    <message>Transaction Received</message>
  </captureResponse>
</litleOnlineResponse>

Attachments

    Outcomes