Apple Pay and Recurring Payments

Document created by gjsissons on Nov 16, 2016Last modified by gjsissons on Nov 21, 2016
Version 11Show Document
  • View in full screen mode

 

Please note: Vantiv documentation relating to Apple Pay and recurring payments is in the process of being revised. While the examples below have been tested in the eCommerce Pre-live environment, LitleXML is in the process of being enhanced and this document may contain inaccuracies. This document will be updated as new details become available. Please feel free to comment and help improve the quality of this document.

 

Normally, an on-line Apple Pay transaction involves only a single payment transaction. For security reasons, the PKPaymentToken contains a one-time cryptogram that prevents the Apple Pay token from being used repeatedly to fund multiple transactions.

 

Despite this, merchants often wish to use Apple Pay in-App, or Apple Pay on the Web to fund a series of future payment transactions using a payment card in the Apple Wallet. For example, a consumer may be purchasing a one year gym subscription billed monthly, or a subscription to an on-line service.

 

Vantiv’s payment platforms provide features that allow Apple Pay to be used as a source of payment for recurring, subscription style transactions.

 

A step-by-step example is provided below.

 

A Recurring Payments Example

 

Consider the case of a gym membership. In our simple example, a membership costs $100.00 / per month and lasts for a 12-month period.

 

For traditional card payments, merchants familiar with Vantiv’s Recurring Engine would simply define a one year payment plan, and associate the plan with a subscription in their Authorization or Sale transaction.  Wallet-based payments including Apple Pay and Android Pay are new however, and are not yet supported by the Recurring Engine. This means that developers and merchants will need to manage the recurring payment stream themselves in their applications for the time being.

 

The example below assumes that a merchant is using eProtect, one of multiple integration methods between Apple Pay and Vantiv’s eCommerce platform. If you are using other integration methods, additional guidance is provided later in this document. You can learn more about the various integration methods with Apple Pay on the Vantiv O.N.E. developer portal.

 

After your iOS app or website has retrieved a PKPaymentToken from Apple, you will call Vantiv’s eProtect service to decrypt and vault the token. Your application will receive an eProtect token in return, also known as the “low-value token” or the paypageRegistrationId.

 

The first step is to call Vantiv’s eCommerce servers, and exchange the low-value token (representing the Apple Pay / wallet payment credentials) for a Vantiv token that can be used for future payment transactions.

 

This involves using a registerTokenRequest transaction as shown below.

 

Step 1: Exchange the eProtect low-value token for a Vantiv token

 

Your application will send a request like the one below to Vantiv’s eCommerce endpoint passing the low-value token (paypageRegistrationId):

 

<litleOnlineRequest version="9.9" xmlns="http://www.litle.com/schema" merchantId="1268016">
        <authentication>
            <user>u82918854344049902</user>
            <password>QVtHWtb6UGk5XCz</password>
        </authentication>
        <registerTokenRequest id="12345" reportGroup="67890">
               <orderId>Order Id</orderId>
<paypageRegistrationId>Q2FvZ3V1bDFXajdqcEJ3eGtWMnBvbVE0ZWlRN3NNL2U2V1IrQXM5MDhFTHdxTW4wVTZwQUtGb2poek5abFBJOQ==</paypageRegistrationId>
        </registerTokenRequest>
      </litleOnlineRequest>

 

In response, you will receive a message that contains the litleToken. The litleToken represents the Apple Pay network token (dPAN) vaulted by Vantiv, and can be used for payment transactions.

 

<litleOnlineResponse version="9.9" xmlns="http://www.litle.com/schema"
    response="0" message="Valid Format">
    <registerTokenResponse id="12345" reportGroup="67890">
        <litleTxnId>82919306294805964</litleTxnId>
        <orderId>Order Id</orderId>
        <litleToken>1111000277280009</litleToken>
        <response>801</response>
        <responseTime>2016-11-16T11:51:06</responseTime>
        <message>Account number was successfully registered</message>
        <bin>445701</bin>
        <type>VI</type>
    </registerTokenResponse>
</litleOnlineResponse>

 

Note that the low-value Token will expire after 24 hours, so it is a good idea to send the registerTokenRequest immediately after receiving the low-value token.

 

Once you have the Vantiv token in your possession, you can process payments.

 

Please note: although not shown in this example above, if the registerTokenResponse involves Apple Pay as a source of payment (as is the case here), the response will also contain an onlinePaymentCryptogram inside an applePayResponse XML element. The online payment cryptogram will need to be provided as an authentication value along with the initial Apple Pay transaction as shown in step 2 below.

 

It will be up to your application to process payments on the appropriate dates depending on the terms of the subscription.

 

Step 2: The Initial Payment Transaction

 

To process the initial payment of $100.00, submit a Sale transaction. Most on-line merchants use a sale transaction, also known as a conditional deposit to simultaneously authorize and capture funds.

 

You will provide the Vantiv token (litleToken) as the source of payment. Note the additional specific requirements for an initial payment in a recurring payment stream involving Apple Pay:

 

  • The <orderSource> in the initial payment must be set to “applepay so that Vantiv’s systems will recognize this is an Apple Pay transaction
  • The onlinePaymentCryptogram received in the registerTokenResponse should be included in the <authenticationValue> element as shown below for the initial Apple Pay payment transaction only
  • A new <processingType> tag must be set to the value “initialRecurring” or “initialInstallment. This advises Vantiv that there will be future recurring payments coming.

 

In future versions of LitleXML, Vantiv will return a <networkTransactionId> element to be referenced in future recurring transactions to comply with new network requirements.

 

<litleOnlineRequest version="9.9" xmlns="http://www.litle.com/schema" merchantId="1268016">
        <authentication>
            <user>u82918854344049902</user>
            <password>QVtHWtb6UGk5XCz</password>
        </authentication>
        <sale id="16111600" reportGroup="67890" customerId="6548346">
            <orderId>1</orderId>
            <amount>10000</amount>
            <orderSource>applepay</orderSource>
            <billToAddress>
                <name>John H. Smith</name>
                <addressLine1>123 Main Street</addressLine1>
                <city>Albany</city>
                <state>NY</state>
                <zip>12345</zip>
                <country>US</country>
                <email>john.doe@gmail.com</email>
                <phone>(212) 555-1212</phone>
            </billToAddress>
            <token>
                <litleToken>1111000277280009</litleToken>
            </token>
            <cardholderAuthentication>
                 <authenticationValue>insert the value from the onlinePaymentCryptogram here</authenticationValue>
            </cardholderAuthentication>
            <processingType>initialRecurring</processingType>
        </sale>
  </litleOnlineRequest>

 

If successful, submitting the initial transaction above will result in a response like the one below:

 

<litleOnlineResponse version="9.9" xmlns="http://www.litle.com/schema"
    response="0" message="Valid Format">
    <saleResponse id="16111600" reportGroup="67890" customerId="6548346">
        <litleTxnId>82919306320527798</litleTxnId>
        <orderId>1</orderId>
        <response>000</response>
        <responseTime>2016-11-16T11:55:12</responseTime>
        <postDate>2016-11-16</postDate>
        <message>Approved</message>
        <authCode>11111 </authCode>
        <fraudResult>
            <avsResult>20</avsResult>
            <cardValidationResult>M</cardValidationResult>
        </fraudResult>
    </saleResponse>
</litleOnlineResponse>

 

Step 3: Processing subsequent transactions

 

For the next month's payment, and for several months thereafter, your application will perform similar monthly transactions charging $100.00 to the payment card stored in the consumer’s Apple Pay wallet. You’ll be using the same persistent Vantiv payment token.

 

  • For all subsequent transactions following the initial transaction, the <orderSource> element must be set to recurring.  This advises Vantiv and the card networks that the transactions are linked.

 

 <litleOnlineRequest version="9.9" xmlns="http://www.litle.com/schema" merchantId="1268016">
        <authentication>
            <user>u82918854344049902</user>
            <password>QVtHWtb6UGk5XCz</password>
        </authentication>
        <sale id="16111601" reportGroup="67890" customerId="6548346">
            <orderId>1</orderId>
            <amount>10000</amount>
            <orderSource>recurring</orderSource>
            <billToAddress>
                <name>John H. Smith</name>
                <addressLine1>123 Main Street</addressLine1>
                <city>Albany</city>
                <state>NY</state>
                <zip>12345</zip>
                <country>US</country>
                <email>john.doe@gmail.com</email>
                <phone>(212) 555-1212</phone>
            </billToAddress>
            <token>
                <litleToken>1111000277280009</litleToken>
            </token>
        </sale>
      </litleOnlineRequest>

 

If successful, you should receive a response like the one below indicating that the monthly subscription payment is successful.

 

<litleOnlineResponse version="9.9" xmlns="http://www.litle.com/schema"
    response="0" message="Valid Format">
    <saleResponse id="16111601" reportGroup="67890" customerId="6548346">
        <litleTxnId>82919306320529067</litleTxnId>
        <orderId>1</orderId>
        <response>000</response>
        <responseTime>2016-11-16T11:59:30</responseTime>
        <postDate>2016-11-16</postDate>
        <message>Approved</message>
        <authCode>11111 </authCode>
        <fraudResult>
            <avsResult>20</avsResult>
            <cardValidationResult>M</cardValidationResult>
        </fraudResult>
    </saleResponse>
</litleOnlineResponse>

 

Additional notes

 

As explained above, if you are using different integration methods, handling recurring payments is similar with the following caveats:

 

  • If you are not using eProtect with Vantiv’s eCommerce platform, but are still relying on Vantiv to decrypt the PKPaymentToken, the sequence of steps will be almost identical to those above. The only difference is that instead of supply the low-value token using the <paypage> tag, you will provide an <applepay> tag containing the PKPaymentToken in the registerTokenRequest.
  • If you are not using eProtect, but are using Vantiv’s eCommerce platform, and are decrypting the Apple PKPaymentToken yourself, you will submit the decrypted Network token (dPAN) in a <card> element.

 

Additional information about both of these additional methods is provided in the Vantiv eCommerce Apple Pay Solution documentation.

 

Future changes due to network rules

 

With the October 2016 release, Visa is implementing changes that represent the new framework for merchant-initiated transactions. Most of these changes are optional for cardholder PAN transactions but are highly recommended for payment token transactions (like the ones above).

 

While optional presently, these changes will be mandated in future releases. To meet these future requirements, Vantiv is adding additional elements to LitleXML 8.3.0, 9.10 and 10.5 and later.

 

In response to Authorization, Sale and CaptureGivenAuth requests, Vantiv will be returning a new networkTransactionId element.  Applications in future will need to store this element along with the initial transaction amount, and reference it in subsequent recurring payment transactions.

 

In Authorization, Sale and CaptureGiveAuth transactions, Vantiv will also be adding the following additional XML elements to facilitate passing these values to meeting network requirements:

 

  • originalNetworkTransactionId
  • originalTransactionAmount

 

Details will be provided in future releases of the Vantiv eCommerce Apple Pay Solution documentation and the LitleXML Reference Guide.

Attachments

    Outcomes