Skip navigation
All Places > eCommerce > Blog

eCommerce

3 posts

Recently, I was at a cookout and talking with an old friend I hadn’t seen in several years. After going over family info, we moved on to careers, and when I told him I worked for Vantiv (and explained what we did), he perked-up and said he was about to expand his business (he owns several small stores selling souvenirs and collectables) to the Internet and wanted to pick my brain about how to select a good processor for eCommerce transactions. He was mostly concerned with the fact that his nephew, a recent Boston University graduate, was going to set up his site and do all the coding to send transactions to whatever processor he selected. While I had some suggestions, not being a coder myself I couldn’t answer all his questions. When I returned to work on Monday, I asked several Vantiv eComm developers to put themselves in a merchant’s shoes and let me know what they would want in an API. This is their list.

 

1. Good documentation, including usable and re-usable examples
I have to admit, being the Leader of the Technical Publications group at Vantiv, this item--and the fact that it was the first one several of the engineers mentioned--gives me great pleasure. They stated that having complete, well-defined documentation makes any code development much easier, while incomplete or inaccurate documentation can make code development a nightmare. Augmenting the documentation with usable code examples also makes everything progress more smoothly.

2. Consistency across the API

Most processors have large development teams working on different parts of their APIs. Some teams might be working on new features, while others work on updates to meet mandated card network changes. All teams should be uniform in their treatment of the API. The development groups need to have well-defined standards, conventions, and object naming and they need to adhere to these items. The end result for the merchant’s developer is an API that is readable, consistent, understandable, and ultimately, does what a programmer expects it to do.

 

3. Regular maintenance of the API
Is the API updated regularly? What is the cadence of changes? Is backward compatibility maintained? These are all questions you should investigate. If an API isn’t updated regularly, especially in the eCommerce world, it rapidly becomes stale and outdated. The card brands have a regular cadence of updates and requirement changes twice per year in April and October (though they also do some in between). A failure to update the API also indicates a lack of new feature development. You may not always have interest in a particular new feature, but you want your processor to be engaged in constant improvement. As for backward compatibility, you never want new development to force you into an unnecessary and expensive update.

 

4. A robust test environment

When you code to the API, you want to test everything. If your application/checkout page fails, the result is lost sales and an unsatisfied customer. You want a test environment that allows you to either do complete end-to-end testing or at least has the capacity to simulate end-to-end testing. You also want contact with a support group to assist you with resolving any difficulties during your testing and certification process. Most developers won’t need their hands held, but want someone responding to questions when they need help.

 

Finally, the test environment must support regression testing. Over time, your needs and code will change. When it does, you will want to test the API completely before deploying for customer use.

 

5. Popularity/Active developer community
You don’t want to go with an API that no one else uses, unless you are getting a great deal from a start-up and are willing to take your chances. Look for established processors with many users. Also, look on sites such as GitHub and see how many stars the API has from other developers. Last, but certainly not least, look for an active developer community. Other developers who have already worked with the API are a great source of knowledge and their comments are often the best measure of a good or bad API.

Vantiv provides developers with several methods of integrating to its powerful payment processing platform, ranging from direct integrations to easy to use client-side SDKs for eCommerce or mobile integrations.

 

In an earlier article I looked at getting started with Vantiv’s Express API, a versatile API often used for Card Present POS environment. In this article, I’ll provide an overview of how to get started with Vantiv’s eCommerce API (formerly known as the Litle API) and show how developers can get productive quickly testing payment transactions against Vantiv’s eCommerce sandbox.

 

What you’ll need to get started

 

Like other payment APIs from Vantiv, the eCommerce API is essentially a message specification. As long as a client-side program can open a secure network connection, generate and post XML content, and parse responses from the server, it can integrate with Vantiv. You can send transactions to the server via an HTTPS Post, a TLS protected socket connection, a secure sFTP session, or through a regular FTP session, where transaction content is encrypted using PGP (Pretty Good Privacy) or GPG (GNU Privacy Guard). The examples contained in this article use Vantiv’s online interface, posting and retrieving messages interactively via the HTTPs protocol.

 

The Vantiv eCommerce Sandbox

 

Vantiv operates an eCommerce Sandbox that simulates the production and certification environments for Vantiv’s eCommerce payment services.  There are no forms to fill out or special credentials required to get started. For simplicity, transactions are not actually tied to one another in the sandbox. Developers can test different scenarios by changing the test card numbers to generate different responses from the server. This is explained in the eCommerce sandbox document.

 

Sending a simple payment transaction

 

The example below shows a simple Authorization transaction. Using cURL (included in most Linux distributions) we open a connection to Vantiv’s sandbox and sent an XML formatted transaction.

 

In this example, we are requesting a credit card authorization for $10.00. By using the card number “xxxxxxxxxxxx000” we are seeking to generate an approved response. You will need to use one of the test card numbers as described in the eCommerce sandbox document. The last three digits of the card number are understood to be encoded to represent the response we desire for testing. Because the last three digits of the card are 000 in this case, we are simulating a clean authorization.

 

In my testing, I found it was necessary to use TLS (tlsv1.2) explicitly when contacting Vantiv’s sandbox servers. For security reasons, Vantiv no longer supports earlier versions of SSL. You should be able to cut and paste the code below after substituting your own username, password and a valid test card number, and run it on any internet connected system with cURL. This code simulates a payment authorization by processing against the Vantiv eCommerce sandbox.

 

curl --tlsv1.2 https://www.testlitle.com/sandbox/communicator/online \
-H "Content-Type: text/xml" \
-d \
'<litleOnlineRequest version="9.4" xmlns="http://www.litle.com/schema" merchantId="default">
    <authentication>
        <user>MyTestStore</user> <!--substitute with your username -->
        <password>MyPa$$word</password> <!--substitute with your password -->
    </authentication>
    <authorization id="auth-id" reportGroup="IQRptGrp" customerId="12345">
        <orderId>1</orderId>
        <amount>1000</amount> <!--Amount is $10.00, no decimals-->
        <orderSource>ecommerce</orderSource>
        <billToAddress>
            <name>John Smith</name>
            <addressLine1>20 Main Street</addressLine1>
            <city>San Jose</city>
            <state>CA</state>
            <zip>95032</zip>
            <country>USA</country>
            <email>jdoe@vantiv.com</email>
            <phone>978-551-0040</phone>
        </billToAddress>
        <card>
            <type>VI</type>
            <number>xxxxxxxxxxxx000</number> <!--substitute with your test card number-->
            <expDate>0112</expDate>
            <cardValidationNum>349</cardValidationNum>
        </card>
        <customBilling>
            <phone>8885551212</phone>
            <descriptor>mystore*001</descriptor>
        </customBilling>
    </authorization>
</litleOnlineRequest>'

 

If you want to understand all the parameters in the above example, the best source of information is the LitleXML Reference Guide.

 

Additional developer guides and technical documents about Vantiv’s eCommerce platform can be found in the eCommerce documentation.

 

When you run the shell script above, the server should respond with XML similar to that shown below:

 

[ec2-user@ip-172-31-21-85 curl]$ . ./auth_litle_curl.sh
<litleOnlineResponse version='10.1' response='0' message='Valid Format' xmlns='http://www.litle.com/schema'>
  <authorizationResponse id='auth-id' reportGroup='IQRptGrp' customerId='12345'>
    <litleTxnId>771643925628630000</litleTxnId>
    <orderId>1</orderId>
    <response>000</response>
    <responseTime>2015-11-22T08:14:53</responseTime>
    <message>Approved</message>
    <authCode>77673</authCode>
  </authorizationResponse>
</litleOnlineResponse>

 

 

By changing the last three digits of the card to a different number and re-running the transaction, we can simulate different outcomes. For example, replacing the last three digits of the card with the code 110 simulates a case where insufficient funds are available. Running the same script with this change generates the following output:

 

[ec2-user@ip-172-31-21-85 curl]$ . ./auth_litle_curl.sh
<litleOnlineResponse version='10.1' response='0' message='Valid Format' xmlns='http://www.litle.com/schema'>
  <authorizationResponse id='auth-id' reportGroup='IQRptGrp' customerId='12345'>
    <litleTxnId>460269071422121110</litleTxnId>
    <orderId>1</orderId>
    <response>110</response>
    <responseTime>2015-11-22T08:41:01</responseTime>
    <message>Insufficient Funds</message>
  </authorizationResponse>
</litleOnlineResponse>

 

 

A more realistic example

 

Not many real payment applications are implemented by running cURL scripts from the command line, so to provide a more realistic example, this section shows payment transactions initiated by an application running on a web server. Typically, this is how web or mobile users would access an eCommerce application. Also, generating and parsing raw XML is not very convenient for developers. Vantiv provides SDKs for PHP, Ruby, Java, .NET and Python that make it easier to integrate with Vantiv’s eCommerce platform. We’ll focus on a PHP-based example, since PHP is one of the most popular web programming environments.

 

Installing and configuring the Vantiv PHP SDK

 

Vantiv makes its PHP SDK freely available for download from GitHub (https://github.com/LitleCo/litle-sdk-for-php) or Packagist, a popular PHP repository (https://packagist.org/packages/litle/payments-sdk). The Vantiv PHP SDK depends on a package called composer to manage package dependencies. Composer is available from https://getcomposer.org.  Instructions for installing and configuring composer along with Vantiv’s PHP SDK are provided in the Packagist repository.

 

By default, the Apache web-server serves content from /var/www/html and this is where we store the code examples that follow. We stored the contents of the SDK in the default directory name litle-sdk-for-php in the web hosting area. Alternately, the SDK can exist outside of the directory serving web content and be referenced via a symbolic link instead.

 

With the SDK installed and configured on the web-server, we can now build and deploy some simple PHP scripts to demonstrate various types of transactions. In our testing we found that we needed to explicitly open several ports on the AWS hosted server hosting our pages that were blocked by default with Amazon’s security groups. OS firewall rules need to be similarly relaxed of course. The ports that need to be open are listed in the table below.

 

Table 1: Ports that need to be opened for payment transaction examples

 

TypeProtocolPort
HTTPTCP/80Inbound / Outbound
SSHTCP/22Inbound / Outbound
DNS (UDP)UDP/53Inbound / Outbound
DNS (TCP)TCP/53Inbound / Outbound
HTTPSTCP/443Inbound / Outbound
GIT (Custom)TCP/9418Inbound / Outbound

 

 

To install the Vantiv eCommerce SDK we used the git command to clone the GitHub repository, which requires port 9418 be opened

 

Authorizing a payment transaction

 

When using the SDK, creation of payment transactions becomes easier for the developer. We use the PHP namespace command to specify the location of the Litle SDK classes. In the example below the $auth_info array is populated with the inputs for the authorization transaction. $initialize holds an instance of the LitleOnlineRequest object defined in the SDK and we invoke the authorizationRequest method, passing it the populated$auth_array. The SDK handles all the details of creating the XML, opening the TCP/IP sockets connection, passing the XML to the server and listening for the response. The SDK also provides a getNode method that makes it easy to parse the resulting XML response from the server.

 

<?php
namespace litle\sdk;
?>
<html>
    <head>
        <title>Vantiv Demo</title>
    </head>
    <body>
        <h2>Authorization Example</h2>
        <?php
            require_once realpath(__DIR__). '/litle-sdk-for-php/litle/sdk/../../vendor/autoload.php';
            $auth_info = array(
             'orderId' => '1',
       'amount' => '10010',
                      'id'=> '456',
       'orderSource'=>'ecommerce',
       'billToAddress'=>array(
       'name' => 'John Smith',
       'addressLine1' => '1 Main St.',
       'city' => 'Burlington',
       'state' => 'MA',
       'zip' => '01803-3747',
       'country' => 'US'),
       'card'=>array(
       'number' =>' xxxxxxxxxxxx000',
       'expDate' => '0112',
       'cardValidationNum' => '349',
       'type' => 'VI')
  );

            $initialize = new LitleOnlineRequest();
            $authResponse = $initialize->authorizationRequest($auth_info);


            echo "<h3>Parsed results</h3>";
            echo ("Response: ".(XmlParser::getNode($authResponse,'response')) . "<br>");
            echo ("Message: ".XmlParser::getNode($authResponse,'message') . "<br>");
            echo ("Litle Transaction ID: " . XmlParser::getNode($authResponse,'litleTxnId'));


            if(XmlParser::getNode($authResponse,'message')!='Approved')
                throw new \Exception('LitleAuthorizationTransaction does not get the right response');
        ?>
    </body>
</html>

 

 

Invoking the PHP script above from the browser results in the output below. In this simple example, we just show the parsed results, including the response code from the server, the message corresponding to the code, and the Litle Transaction ID. A real application would need to handle other types of possible responses (for example, insufficient funds, issuer not available, partial approvals and processing network not available).

 

authorizationExample_result.png

Capturing a previously authorized transaction

 

Now that we have authorized the transaction, and have a Transaction ID reflecting the authorization, a logical next step is to Capture the transaction. A Capture operation results in previously authorized funds being moved by Vantiv from the issuer to the merchant account. With Vantiv’s eCommerce API, capturing the previously authorized transaction is simple. All we need to do is reference the previously returned transaction ID associated with the authorization.

 

Below a self-contained PHP program that illustrates this using the Vantiv eCommerce SDK to perform the Capture transaction. In this example, we expose a little more debugging information by showing details of the actual on-line request. We also show the raw XML retrieved by the web application from the Vantiv eCommerce sandbox. The <xmp> tags (<pre> can be used also) allow the display of raw code without interpretation by the browser.

 

<?php
namespace litle\sdk;
?>
<html>
    <head>
        <title>Vantiv capture example</title>
    </head>
    <body>
        <p>Capture Example</p>
<?php


require_once realpath(__DIR__). '/litle-sdk-for-php/litle/sdk/../../vendor/autoload.php';

#Transaction capture
$capture_info = array(
             'litleTxnId' => '100000000000000011',
                      'id'=> '456'
  );

$initialize = new LitleOnlineRequest();
$captureResponse = $initialize->captureRequest($capture_info);


echo '<xmp>';
print_r ($initialize);
echo '</xmp>';




echo '<xmp>';
echo ("XML document" . XmlParser::getDomDocumentAsString($captureResponse));
echo '</xmp>';

#display results
echo ("Response: " . (XmlParser::getNode($captureResponse,'response')) . "<br>");
echo ("Message: " . XmlParser::getNode($captureResponse,'message') . "<br>");
echo ("Litle Transaction ID: " . XmlParser::getNode($captureResponse,'litleTxnId'));


?>
    </body>
</html>

 

 

Running the script above from the browser, generates the following output.

 

phpSDKexample_capture_result.png

 

Providing a Credit

 

Often in a payment application, it is necessary to fully or partially refund money associated with a transaction to a cardholder. You use the Credit transaction type to return funds from a previously executed Capture or Sale transaction. Developers can optionally specify an amount to be credited. If you do not provide an amount, the transaction results in a refund of the full amount of the associated Capture or Sale. The sample code below shows using the PHP SDK to provide a credit:

 

 

<?php
namespace litle\sdk;
?>
<html>
    <head>
        <title>Vantiv credit example</title>
    </head>
    <body>
        <p>Credit Example</p>
<?php


require_once realpath(__DIR__). '/litle-sdk-for-php/litle/sdk/../../vendor/autoload.php';

#Transaction credit
$credit_info = array(
             'litleTxnId' => '100000000000000002',
                      'id'=> '456'
  );

$initialize = new LitleOnlineRequest();
$creditResponse = $initialize->creditRequest($credit_info);


echo '<xmp>';
print_r ($initialize);
echo '</xmp>';




echo '<xmp>';
echo ("XML document" . XmlParser::getDomDocumentAsString($creditResponse));
echo '</xmp>';

#display results
echo ("Response: " . (XmlParser::getNode($creditResponse,'response')) . "<br>");
echo ("Message: " . XmlParser::getNode($creditResponse,'message') . "<br>");
echo ("Litle Transaction ID: " . XmlParser::getNode($creditResponse,'litleTxnId'));


?>
    </body>
</html>

 

When we run this script from the browser, we see the result below. The Credit transaction refunds the amount previously captured, returning the transaction ID associated with the credit operation.

 

initiate_credit_result_PHPSDK.png

 

There are a variety of other transaction types supported by the Vantiv eCommerce platform. All transactions follow essentially the same recipe as the three example transactions (Authorization, Capture and Credit).

 

Next steps and application certification

 

The eCommerce sandbox is ideal for developers who want to explore how Vantiv’s eCommerce APIs work and experiment with code at their own pace.  For developers who wish to take the next step, and process transactions against Vantiv’s production payment platform, a certification process is supported to help verify that transactions generated by your application will meet the requirements of our on-line API.

 

Certification is a required step before applications can be deployed in production.  Once you have reached the point where you are comfortable with your testing to the sandbox, you can obtain an account on the official pre-live certification environment by going to https://www.testlitle.com/sandbox/.

 

The pre-live environment is the official test environment that you will ultimately use to perform and complete all required certification testing.  You will be able to run through all of the standard test cases, and even the standard certification test cases that are detailed in section 2.4 of the LitleXML Reference Guide.

 

The test account supports basic payment processing functionality, but will not currently support any of the eCommerce platform’s value-added services (VAS).  

 

Once an official relationship has been established with Vantiv (either merchant or processing partner), the project will be added to the eCommerce on-boarding work queue.  The next available Vantiv Implementation Consultant will be assigned to the project, and will work directly with you to support the completion of all on-boarding requirements, including the official integration certification.  If you are interested in leveraging any available VAS, your Implementation Consultant will work with you at this time to support the inclusion within your processing integration.    

Developers have a key role to play

 

While fraud has always been a concern, with the EMV liability shift upon us, combating fraud at the point of sale (POS) is top of mind for merchants. As the POS becomes a harder target however, fraudsters are likely to shift their focus toward softer targets like the merchant website and mobile platforms. As the nature of the threat evolves, developers have a key role to play in helping merchants combat fraud across all their payment channels.

 

Striking the right balance

 

Developers of payment applications face a difficult dilemma. If they don’t pay enough attention to fraud, they leave the merchants that rely on them vulnerable to increased chargebacks, sanctions from credit card companies and other potential costs. If developers are too aggressive in implementing anti-fraud measures, they risk turning away legitimate transactions and antagonizing the merchant’s customers. Merchants are looking for the “Goldilocks solution” – one that calibrates anti-fraud measures precisely such that they catch the majority of bad transactions while minimizing false positives. With this in mind, it is useful to step back and recall how fraud, and associated countermeasures have evolved.

Necessity is the mother of invention

 

Innovations in fraud prevention have come about mainly in response to abuse. Looking back almost a decade and half, when card fraud became an issue with CNP eCommerce and other channels such as mail order and telephone order transactions, the card industry responded with Card Verification Values (CVV) and the Address Verification Service (AVS). These measures, implemented around the year 2000, helped ensure that customers were physically in possession of cards and helped merchants manage fraud from stolen cards. Most developers built applications with custom logic or in-house rules to filter or perform additional reviews on transactions that failed AVS or CVV. They paired these basic checks with certain white lists and black lists based on the card number and customer name. These basic filters and black lists are now table stakes for most payment processors. For example, Vantiv offers a wealth of features that help eCommerce merchants make better decisions about what transactions to accept. These include additional options to Filter pre-paid cards to avoid them being used for recurring payment transactions, flagging cards that have resulted in prior chargebacks, and velocity filters that can trigger declines when a threshold number of authorization or sales transactions have taken place.

 

Beyond these basic capabilities, Advanced Fraud Tools from Vantiv help “score” transactions based on dozens of fraud predictors for even greater accuracy. Some specific techniques include:

 

  • Fingerprinting devices, and detecting machines that have exceeded configurable payment thresholds within particular periods
  • Detecting devices originating transactions on behalf of multiple customers
  • Identifying devices originating transactions through multiple proxies, anonymous proxies, or attempting to cloak their identity
  • Flagging transactions involving the same customer originating from multiple geographies or mismatches between the location and the browser language

 

While these techniques are powerful, cost is an issue - especially for smaller merchants. Having dedicated analysts and even data scientists on staff makes sense for large merchants where the savings outweigh the costs, but smaller merchants cannot deploy the same types of sophisticated analytic environments that will make sense for a major retailer.

 

Toward more automated detection

 

To address the challenge of providing increasingly sophisticated analytics in a manner that is easy for developers to implement and merchants to manage, leading providers like Vantiv are investing in new approaches to better detect and manage fraud. One such approach is the use of “beacon” technology – small fragments of JavaScript that developers can embed in the merchant’s web store that silently relays telemetry back to the payment provider, tracking the behavior of the website visitor at every step (behavioral analysis). Similar to the way Google Analytics functions, this approach frees developers from the need to instrument and analyze fraud related activity themselves.

 

Owing to their economies of scale, payment processors collaborating with Fraud providers can centrally and cost-efficiently deliver sophisticated behavior-based analytics, monitoring users for anomalous behavior on the website and flagging activity that looks suspicious. By processing this gathered information with machine-learning algorithms able to fine tune predictive models, merchants can find the optimal balance. This level of sophistication would be impractical and cost prohibitive for most merchants to implement and manage themselves.

 

Vantiv provides developers with a choice. They can collect critical information, relay it to Vantiv as payment transaction metadata, and let Vantiv make the determination of what constitutes fraud based on server-side fraud detection settings configurable for each merchant. As an alternative, developers can take advantage of API level extensions that expose sophisticated anti-fraud capabilities, providing developers with more granular control over how to handle potentially fraudulent transactions.

 

Taking a broader view of fraud

 

With the need to support EMV, developers and merchants are re-examining their POS technologies. The time is ripe to think beyond the checkout line, to solutions that can cost efficiently combat fraud across all the channels. For developers interested in learning more about how developers can help reduce fraud for CNP transactions, download our whitepaper A Developer’s Guide to Combating Fraud.

 

More information about Vantiv’s Advanced Fraud Technologies, and other security solutions of interest to developers, visit the Vantiv Developer Network at https://www.vantiv.com/developers/ecommerce-payments#security-features.