Young Developers - eCommerce Quickstart Guide

Document created by gjsissons on Mar 28, 2017Last modified by gjsissons on Jul 18, 2017
Version 18Show Document
  • View in full screen mode

 

About Vantiv eCommerce

 

Vantiv eCommerce is a sophisticated platform with advanced features geared towards card-not-present payments. This is Vantiv's main platform for enabling web-based eCommerce applications purchases from within mobile-apps.

 

Because the programming interface is designed for card-not-present applications, it is also referred to as the "cnp API".  You may also find references on the public internet referring to this platform as "Litle" or "Lowell". For our purposes, we'll refer to the platform simply as Vantiv eCommerce.

 

The eCommerce environment supports both batch functionality (often used by large retailers for end-of-day or periodic processing) and an on-line, real-time interface. In the examples below, we use the on-line interface.

 

API End-point and Credentials


Like other web-oriented APIs, developers can process payments by sending XML formatted messages to an internet endpoint and receive a response.  There are multiple endpoints for the eCommerce platform, but for learning purposes, we'll use Vantiv's non-production "pre-live" environment:

 

https://transact-prelive.litle.com/vap/communicator/online

 

You will need credentials in the form of a username and password to connect to this endpoint. To save students the hassle of hunting these down, the shared credentials below are available for your use.

UsernamePassword
u82918854344049902QVtHWtb6UGk5XCz

 

Reference Documentation

 

The main source of documentation for the eCommerce platform is the Vantiv cnpAPI Reference Guide.  We suggest that you download this PDF guide and keep it handy for reference as you work through the examples below.  The guide is nearly 900 pages long and makes excellent bedtime reading!

 

Coding Examples

 

Step 1: Authorizing a Credit Card Payment


One of the most common activities when accepting a credit card payment from a web-site or mobile app is seek an Authorization from the bank that issued the customer’s credit card. Vantiv facilitates this using the aptly named Authorization transaction.

 

An Authorization ensures that a card is valid and in good standing, and that there is sufficient credit available to cover a purchase. An Authorization also "holds" funds for a period of time, typically until a Capture operation is performed or until an authorization is Cancelled.

 

If you or a friend have purchased fuel at an automated gas pump, you're already familiar with how this works.  You authorize a card for a "not to exceed amount". Once you finish pumping gas, and perhaps buy a car wash, the actual amount owing is determined.  A corresponding Capture transaction follows the authorization and results in funds being moved from the cardholder's credit card account to the merchant's bank account (in this case the gas station).  The function of a payment processor (that's Vantiv) is to manage this entire process.

 

  • To send an Authorization you'll need to POST an XML message to our internet endpoint via HTTPS.  There are several ways to do this:
    • You can use a tool like cURL (This is recommended as the easiest way to get started).
    • You can also use a utility like Postman.  If you don't have cURL, this is your next best bet.  We've provided instructions and examples on how to use Postman  here.
    • If you're comfortable with internet programming, you can also write your own software using your language of choice (Python, Java, C#, Objective-C etc..) to generate an XML messages, open a TCP/IP socket connection to our endpoint, send the message and receive the response.
    • You can save some coding by using one of Vantiv's client-side SDKs (discussed below) to generate and parse XML messages for you, thus simplifying the integration.

 

Assuming you have access to a platform with cURL installed, you can build a shell script to process the authorization as below. This script is available here on GitHub.

 

#!/bin/sh
curl -v https://transact-prelive.litle.com/vap/communicator/online --tlsv1.2  \
   -H "Content-Type: text/xml; charset=UTF-8"  \
   -X POST  \
   -H "Expect:" \
   -d  \
     '<?xml version="1.0"?>
      <litleOnlineRequest version="9.9" xmlns="http://www.litle.com/schema" merchantId="1268016">
        <authentication>
            <user>u82918854344049902</user>
            <password>QVtHWtb6UGk5XCz</password>
        </authentication>
        <authorization id="ididid" reportGroup="YDP" 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>my-email-address@vantiv.com</email>
                <phone>978-551-0040</phone>
            </billToAddress>
            <card>
                <type>MC</type>
                <number>5454545454545454</number>
                <expDate>1112</expDate>
                <cardValidationNum>123</cardValidationNum>
            </card>
        </authorization>
      </litleOnlineRequest>'

 

This example assumes that you are running on a Linux or Mac OS X environment. If you don't have access to a Linux machine, you can obtain cURL for Windows as well.  Another way to get started is to register for a free trial with a cloud provider (Like Amazon, Microsoft Azure or Google Cloud Engine) who will be happy to loan you a free cloud-resident virtual machine for the duration of their trial periods.

 

A few things to note about this example:

 

  • Using the cnp API, dollar amounts are expressed without using the decimal place. In the example above, 1000 is used to represent $10.00. (Don't worry - you don't need to part with any money to run these examples)
  • While not strictly necessary, address information is usually included as a security measure with card not present Authorizations. You've probably noticed that you usually need to enter your name, address and a CVV code (or equivalent) when making a credit card purchase on a website. The Address Verification Service (AVS) is a feature that helps reduce fraud by validating that the address information matches that of the cardholder. The CVV code helps ensure that you are in physical possession of the card. Before chip cards became the norm, stealing credit card numbers using a mag-stripe reader at a point of sale was a common form of fraud. The CVV code is not included on the magstripe, so verifying this number provides an extra measure of security for an online purchase.
  • The payment examples below involve XML <card> tags that direct include the card's primary account number (PAN) - PAN is payment geek-speak for your credit card number in case you're wondering.  We've presented our initial example by providing a test MasterCard PAN for simplicity, but payment transactions are seldom coded this way any more in the real world. The problem with this approach is that your application has visibility to sensitive cardholder information.  As a developer, this puts you at risk in the event that your application, or system where it resides is breached by a hacker. Payment Applications that handle credit card information are said to be within PCI PA DSS scope. This imposes significant and costly certification requirements on software developers. In subsequent examples, we'll show how a tokenization solution (eProtect in our case) can be used to reduce PCI scope.

 

Assuming you've copied the example above correctly and your environment is working, when you execute the script above, you should see a response like this one:

 

<litleOnlineResponse version="9.9" xmlns="http://www.litle.com/schema"
    response="0" message="Valid Format">
    <authorizationResponse id="ididid" reportGroup="YDP" customerId="12345">
        <litleTxnId>82920248169269131</litleTxnId>
        <orderId>1</orderId>
        <response>000</response>
        <responseTime>2017-03-29T13:33:53</responseTime>
        <postDate>2017-03-29</postDate>
        <message>Approved</message>
        <authCode>123457</authCode>
        <fraudResult>
            <avsResult>00</avsResult>
            <cardValidationResult>M</cardValidationResult>
        </fraudResult>
        <tokenResponse>
            <litleToken>1112000263555454</litleToken>
            <tokenResponseCode>802</tokenResponseCode>
            <tokenMessage>Account number was previously registered</tokenMessage>
            <type>MC</type>
            <bin>545454</bin>
        </tokenResponse>
    </authorizationResponse>
</litleOnlineResponse>

 

In the AuthorizationResponse you will receive a LitleTxnId - 82920248169269131. When you run this, you'll see a different number. Your application will need to retain this value as a reference for future transactions (like to Capture funds or Cancel the Authorization if necessary).

 

Assuming the transaction was approved by the card issuing bank, you should see a message of Approved with an authCode.

 

We also receive a fraudResult indicator following AVS verification. Your application should pay attention to the Fraud result. If you detect Fraud, you may want to cancel the transaction (by sending a Cancel transaction) rather thank risk incurring the cost of a Chargeback. Chargebacks occur when a cardholder successfully challenges a purchase by calling their bank. If a merchant cannot prove a purchase was legitimate, funds are returned to the cardholder and the merchant is charged a Chargeback fee. Administering this process between merchants, banks representing consumers, and card brands (Visa, Mastercard, Discover and company) is another function of a payment processor like Vantiv.

 

Also, importantly in the Authorization response you will have received another value in the "litleToken" field.  This is referred to as the "high-value" token.  You can safely store this token in a database.  The cool thing about this high-value Token is that you can store this in your database and use it to make repeat purchases. Payment developers much prefer to store these Tokens rather than actual credit card numbers, because even if the token is stolen, it is of no use to a thief because the actual credit card details associated with the Token are stored in Vantiv's secure vault.

 

Step 2: Capturing a Transaction

 

In order to Capture the authorized payment transaction you issue a Capture transaction as shown below.  This operation is used to actually move money from a consumers credit card to the merchant's bank account. A Capture requires that the payment was previously authorized as above.

 

This shell script shown below is available here on GitHub

 

#!/bin/sh
curl -v https://transact-prelive.litle.com/vap/communicator/online --tlsv1.2  \
   -H "Content-Type: text/xml; charset=UTF-8"  \
   -X POST  \
   -H "Expect:" \
   -d  \
     '<?xml version="1.0"?>
      <litleOnlineRequest version="9.9" xmlns="http://www.litle.com/schema" merchantId="1268016">
        <authentication>
            <user>u82918854344049902</user>
            <password>QVtHWtb6UGk5XCz</password>
        </authentication>
        <capture id="ididid" reportGroup="YDP" customerId="12345">
            <litleTxnId>82920248169269131</litleTxnId>
        </capture>
      </litleOnlineRequest>'

 

Note that all you need to pass to capture the transaction is the litleTxnId value received in the AuthorizationResponse.

 

You'll need to change the example above and replace the litleTxnId field with the value you retrieved when you ran the Authorization.

 

Assuming the Capture of funds is successful, you should see a response like the one below from the server.

 

<litleOnlineResponse version="9.9" xmlns="http://www.litle.com/schema"
    response="0" message="Valid Format">
    <captureResponse id="ididid" reportGroup="YDP" customerId="12345">
        <litleTxnId>82920248240374405</litleTxnId>
        <response>000</response>
        <responseTime>2017-03-29T13:48:23</responseTime>
        <postDate>2017-03-29</postDate>
        <message>Approved</message>
    </captureResponse>
</litleOnlineResponse>

 

Congratulations! You are now an official payment geek!

 

There is a separate transaction called a "Sale" that performs the Authorization and Capture in a single step. Whether you use an Authorization followed by a Capture, or use a Sale only, has to do with business rules.

 

Typically a merchant should only capture funds after they have delivered a service for a final amount.  If a customer is purchasing a digital asset online for immediate download, a Sale transaction might be appropriate.

 

If a merchant accepting a purchase and will ship an item at a later date, it is better to Authorize the purchase first and Capture the transaction only once the merchant physically ships goods to the consumer.

 

Step 3: Using Tokenization to Improve Security and Reduce PCI Scope

 

In the example above, we passed an actual credit card number in the initial payment Authorization. (Remember the PAN )

 

This is no longer good practice, even when communications are encrypted and secure.  The credit card number is potentially subject to compromise.

 

Credit card numbers are unfortunately very easy to detect using a simple software program. In fact, you can write one yourself for bonus marks!

 

Depending on the type of credit card, the length can be anywhere from 13 to 19 numeric digits. Credit cards use a mod 10 algorithm (also known as the Luhn algorithm) to reduce the chances of cards being keyed incorrectly. With a simple scanning program, credit card numbers are incredibly easy to spot in databases, e-mails, documents or anywhere else.

 

eProtect is a facility offered by Vantiv that securely exchanges PCI sensitive card data for a Low-value Token (LVT) that can be used with an initial payment transaction in place of the actual credit card.  This low-value token is also referred to as a RegistrationId

 

eProtect has its own internet endpoint and is a separate service from the Vantiv eCommerce endpoint we used above.

 

Before continuing to the examples below, we recommend that you read through our eProtect Resource Page and try the examples there yourself.  To proceed to the next step, you'll need a Low-value Token generated by the eProtect service.

 

Step 4: Obtain a Low-Value Token (LVT) to avoid handling Card Data

 

For an eCommerce application, the LVT will normally be obtained using the eProtect JavaScript library included in a web application.  Low-value Tokens provided by Vantiv are only valid for 24 hours, so for convenience we've provided a simple script that will call the service with a test credit card and return a valid LVT.  You'll need to run the script below to obtain a token that can be used in the next step.

 

This script is available on GitHub here.

 

It is important that you use the paypageId provided since these eProtect credentials are configured for use with Vantiv's eCommerce vault.  In our example we use the same credit card number we used in step 1.  In case you're wondering, the call to eProtect is usually made directly from a client's web browser facilitated by a JavaScript library.  As a developer, your web-site is completely out of the communication loop and never sees the credit card data. Sensitive HTML form field inputs can be served directly from Vantiv's servers rather than from your own website.  The client JavaScript library takes the credit card number (PAN) and passes it to Vantiv's eProtect service in response for a low-value token that represents the payment credential. This cURL transaction is typicaly of the key-value pairs passed to the eProtect service from the eProtect JavaScript library in the browser.

 

#/bin/bash
#
# Call eProtect with a PayPage account and test MasterCard to retrieve a low-value token suitable for use
# with Vantiv's eCommerce platform
#
curl -H "Content-Type: application/x-www-form-urlencoded" \
 -d"paypageId=a2y4o6m8k0&reportGroup=67890&orderId=cust_order&id=12345&accountNumber=5454545454545454&cvv=111" \
https://request-prelive.np-securepaypage-litle.com/LitlePayPage/paypage

 

When you run this script, you will see the output below. Note that these response from eProtect is JSON formatted (JavaScipt Object Notation)

 

{
"paypageRegistrationId":"Nm9RWnN6UFBsUlNGWjR3UzNYMzFpRXBUcVZWa3ZwRnhGWnVaNkovcTIrWlZrTDg2L2p6ekREVjBxcWdtckVtMg\u03d\u03d",
"bin":"545454",
"type":"MC",
"firstSix":"545454",
"lastFour":"5454",
"litleTxnId":"82920248454268384",
"orderId":"cust_order",
"response":"870",
"responseTime":"2017-03-29T14:31:49",
"message":"Success",
"reportGroup":"67890",
"id":"12345"
}

 

The long value provided as the paypageRegistrationId is the low-value token that you'll need to provide as part of the Authorization in step 5.

 

Note that JSON strings directly support Unicode encoding. The value "\u03d" above represent hex value 3d (decimal 61) which responds to an "=" symbol. When you pass unicode encoded characters in the example below you should use the character representation.

 

Step 5: Authorize a Payment using a Low-Value Token

 

Authorizing a payment using the LVT retrieved from eProtect is similar to an Authorization involving card data except that you pass the LVT inside a paypageRegistrationId element as shown below.  There is no need to pass a card element in this case because the paypageRegistrationId acts as a reference to the credit card vaulted by Vantiv's eProtect service.

 

#!/bin/sh
curl -v https://transact-prelive.litle.com/vap/communicator/online --tlsv1.2  \
   -H "Content-Type: text/xml; charset=UTF-8"  \
   -X POST  \
   -H "Expect:" \
   -d  \
     '<?xml version="1.0"?>
      <litleOnlineRequest version="9.9" xmlns="http://www.litle.com/schema" merchantId="1268016">
        <authentication>
            <user>u82918854344049902</user>
            <password>QVtHWtb6UGk5XCz</password>
        </authentication>
        <authorization id="ididid" reportGroup="YDP" 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>my-email-address@vantiv.com</email>
                <phone>978-551-0040</phone>
            </billToAddress>
            <paypage>
            <paypageRegistrationId>Nm9RWnN6UFBsUlNGWjR3UzNYMzFpRXBUcVZWa3ZwRnhGWnVaNkovcTIrWlZrTDg2L2p6ekREVjBxcWdtckVtMg==</paypageRegistrationId>
            </paypage>
        </authorization>
      </litleOnlineRequest>'

 

When you run the Authorization above, you should see a successful transaction.

 

Note that in the tokenResponse field, the card type (MasterCard) and the Bank Identification Number portion of the credit card is present, confirming that the Authorization transaction successfully looked up the actual card number in the eProtect vault before processing the authorization through to the card networks.

 

<litleOnlineResponse version="9.9" xmlns="http://www.litle.com/schema"
    response="0" message="Valid Format">
    <authorizationResponse id="ididid" reportGroup="YDP" customerId="12345">
        <litleTxnId>82920248517673927</litleTxnId>
        <orderId>1</orderId>
        <response>000</response>
        <responseTime>2017-03-29T14:44:56</responseTime>
        <postDate>2017-03-29</postDate>
        <message>Approved</message>
        <authCode>123457</authCode>
        <fraudResult>
            <avsResult>00</avsResult>
        </fraudResult>
        <tokenResponse>
            <litleToken>1112000263555454</litleToken>
            <tokenResponseCode>802</tokenResponseCode>
            <tokenMessage>Account number was previously registered</tokenMessage>
            <type>MC</type>
            <bin>545454</bin>
        </tokenResponse>
    </authorizationResponse>
</litleOnlineResponse>

 

As before, you can use the litleToken response (the high-value token) is provided process subsequent payments.  Unlike the like LVT, this token does not expire and it can be used to provide "card on file" functionality without the developer or merchant needing to take the risk of holding customer credit card data in their databases.

 

Vantiv's eCommerce SDKs

 

The examples above are instructive because they are easy to follow regardless of the programming language you are using.  Rather than write applications that directly generate and parse XML as shown above, some developers will prefer to use a language-specific SDK that generates and parses the XML messages for them.  Vantiv offers multiple language specific SDKs for our eCommerce platform.

 

 

It's worth noting that SDKs have pros and cons among professional developers.

 

Some developers will prefer to use SDKs offered by payment providers, but others will prefer to code directly to an XML specification so that they avoid dependencies on client-side libraries that can complicate their software release cycles.

 

Learning exercises

 

  1. Consider a scenario where a card is authorized and it's necessary for a merchant to cancel the order before goods are shipped.  Build on the example in Step 1 by writing code to Authorize a Credit card and then Cancel the Authorization.
  2. The examples above show performing the Authorization and Capture as separate steps.  Re-write the code example in step 1 to use a Sale transaction (also known as a conditional deposit) to perform the Authorization and Capture as a single step.  Under what circumstances would it be appropriate to use this type of transaction?

 

Advanced Exercises

  1. Using one of Vantiv's SDKs, or coding an application yourself, build a web-based form that accepts a credit card (use only test cards provided in the Vantiv eCommer document), posts the credit card information to a web server, and authorizes and captures the payment from the web-server.  Your application will need to parse the XML Authorization Response to make sure the Authorization succeeded and extract the litleTransactionId before calling the Capture.
  2. Write a web-based application that uses the eProtect JavaScript library to securely capture a payment card, and Authorize and Capture a payment using the low-value token to keep your web application out of PCI scope. (An end-to-end example of an application written in PHP that does this is provided on GitHub at https://github.com/VantivLabs/eProtectDemo )

Attachments

    Outcomes