Getting started with Vantiv’s Express API

Some developers may already be familiar with Vantiv’s Express API as an interface for processing card present (CP) payments in Windows/C# POS environments. Express is versatile however, and is able to accommodate a variety of payment types and applications.

Once on-boarded with Vantiv for payment processing, whether via Express or other integration methods, merchants benefit from a variety of powerful capabilities and value-added features including account updating, reporting, analytics and more.

In this short technical tutorial we’ll provide a quick overview of Express and show how easy it is to use the gateway to access the powerful features of Vantiv’s secure, reliable payment platform for both CP and card not present (CNP) payments.

1. What you’ll need

Express is a service-side API designed to work with your choice of languages and tools. You simply need a platform that can open a secure sockets connection to an internet host. The examples below were tested on Windows and Linux, but should work on any platform that supports cURL, a popular solution for interacting with server-side web interfaces without the need to write code.

Most Linux distributions include cURL. If not, it can be easily installed using tools like yum or apt-get, depending on your distribution. On Windows, you can obtain cURL from multiple sources. We used the cURL implementation included in Cygwin in our examples from Cygwin.com. Cygwin is a free open source Unix-like environment for Windows. If using Cygwin, you will need to make sure you include cURL as part of the Cygwin installation as it is not selected by default.

Although not needed for this example, a full explanation of the parameters included in each payment transaction can be found in the Express API guide at http://www.elementps.com/portals/0/Express-Interface-Specification.pdf.

Aside from a client environment supporting cURL, the only other thing you’ll need is a free test account as explained in step 2.

2. Obtaining a free test account

Obtaining your free test account for Vantiv’s Express API is easy. Simply visit the URL below, register, and your credentials will be sent you via email.

http://www.elementps.com/Resources/Create-a-Test-Account

You’ll be provided with four identifiers that you’ll need to retain and make use of in the examples below.

  • AccountID
  • AccountToken
  • ApplicationID
  • AcceptorID

There are multiple ways to interface with Express including SOAP web-services interfaces and hosted payments. In our example we simply post XML transactions over a secure HTTP interface to an endpoint provided by Vantiv at https://certtransaction.elementexpress.com.

3. Authorizing a payment transaction

With our Express API credentials in hand, we’re now able to authorize a payment transaction. As those familiar with payments know, it is a common practice to pre-authorize payments in cases where the final payment amount is not known in advance such as when checking into a hotel, renting a car or purchasing fuel at an automated pump. This makes sure that the customer has funds available in advance of a purchase.

Run the command below to open a connection to Vantiv’s test endpoint and pre-authorize a payment amount of $10.00 using a customer’s credit card. You will need to modify the example to include your own test credentials supplied by Vantiv in step 2.

If successful, you should see a response like the one below (although cURL may not format the XML response depending on your environment).

Express provides details of the transaction in the response including the Card Logo and a masked version of the card that can be displayed to the customer following the authorization. Developers will want to retain the TransactionID above for the next step – completing the payment transaction.

4. Completing a payment transaction

To complete a previously authorized payment transaction, you can use the CreditCardAuthorizationCompletion operation. Note that you will need to provide the specific TransactionID received with the authorization response in Step 3 above. The number will be unique to your own authorization transaction.

Paste the example below into your local environment after inserting your own account credentials and the previously authorized TransactionID.

If the completion of the sale is successful, you will see a response like the following:

You should retain the transactionID of the CreditCardAuthorizationCompletation transaction in case it is necessary to provide a refund or credit in future.

5. Issuing a refund

In some cases, you may need to issue a refund or provide a credit to a customer’s credit card. Vantiv provides two transactions types for this purpose – A CreditCardReturn and a CreditCardCredit. A CreditCardReturn is used to provide a refund referencing the TransactionID associated with the Authorization Completion operation. Returns are only valid within 90 days of a transaction. A CreditCardCredit can be used to credit a card without referencing the TransactionID, in which case the developer will need to provide information identifying the card.
In the example below, we fully refund the previous transaction by referencing the TransactionID, eliminating the need to pass sensitive card data through the encrypted channel once more.

Assuming the CreditCardReturn is successful, you will see a response similar to the one below:

6. Learning more

The Express API has many rich features and is able to process many payment sources including Credit, Debit and eCheck payments in both CP and CNP scenarios for a variety of industry use cases. Some additional capabilities include:

  • Tokenization – a solution that substitutes sensitive cardholder PAN data for non-PCI sensitive tokens, helping the merchant reduce risk by avoiding the need to store and handle sensitive card data
  • Hosted Payments – a solution that removes the software vendor from PA-DSS scope, by shifting the responsibility to Vantiv for handling card data
  • Recurring transactions – allowing cards to be billed on a period basis based on a specified recurrence pattern
  • triPOS – a client-side software solution that interfaces to Express and simplifies interfacing to a variety of POS peripherals while simultaneously reducing PA-DSS scope for developers

Additional coding examples specific to Vantiv’s Express interface are provided at: http://github.com/ElementPS.
You can learn more about Vantiv developer solutions at http://vantiv.com/developers