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>firstname.lastname@example.org</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
|HTTP||TCP/80||Inbound / Outbound|
|SSH||TCP/22||Inbound / Outbound|
|DNS (UDP)||UDP/53||Inbound / Outbound|
|DNS (TCP)||TCP/53||Inbound / Outbound|
|HTTPS||TCP/443||Inbound / Outbound|
|GIT (Custom)||TCP/9418||Inbound / 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).
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.
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.
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.