gjsissons

Getting started with Vantiv's Express API

Blog Post created by gjsissons on May 11, 2016

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.

 

 

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.

 

 

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.

 

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.

 

curl https://certtransaction.elementexpress.com \
  -H "Content-Type: text/xml; charset=UTF-8" \
  -X POST \
  -d \
  '<?xml version="1.0"?>
  <CreditCardAuthorization xmlns="https://transaction.elementexpress.com">
  <Credentials>
  <AccountID>as obtained in step 2</AccountID>
 <AccountToken>as obtained in step 2</AccountToken>
  <AcceptorID>as obtained in step 2</AcceptorID>
  </Credentials>
  <Application>
  <ApplicationID>as obtained in step 2</ApplicationID>
  <ApplicationName>MyExpressTest</ApplicationName>
  <ApplicationVersion>1.0.0</ApplicationVersion>
  </Application>
  <Terminal>
  <TerminalID>01</TerminalID>
  <CardholderPresentCode>2</CardholderPresentCode>
  <CardInputCode>5</CardInputCode>
  <TerminalCapabilityCode>3</TerminalCapabilityCode>
  <TerminalEnvironmentCode>2</TerminalEnvironmentCode>
  <CardPresentCode>2</CardPresentCode>
  <MotoECICode>1</MotoECICode>
  <CVVPresenceCode>1</CVVPresenceCode>
  </Terminal>
  <Card>
  <CardNumber>549999012345XXXX</CardNumber>
  <ExpirationMonth>12</ExpirationMonth>
  <ExpirationYear>19</ExpirationYear>
  </Card>
  <Transaction>
  <TransactionAmount>10.00</TransactionAmount>
  <MarketCode>7</MarketCode>
  </Transaction>
  </CreditCardAuthorization>'

 

Important note: In this, and all examples shown here, please do not use real credit card numbers. Please use only the test credit card numbers supplied by Vantiv. The last four digits of the card have intentionally been replaced with “XXXX” in the example above. Before the example will actually work, you will need to replace XXXX above with the final digits of the card 6781. We have avoided spelling out the card number in our examples lest fraud filters of various types mistakenly flag this post as containing real, sensitive cardholder data.

 

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

 

<CreditCardAuthorizationResponse xmlns=’https://transaction.elementexpress.com’>
<Response>
  <ExpressResponseCode>0</ExpressResponseCode>
  <ExpressResponseMessage>Approved</ExpressResponseMessage>
  <HostResponseCode>000</HostResponseCode>
  <HostResponseMessage>AP</HostResponseMessage>
  <ExpressTransactionDate>20151021</ExpressTransactionDate>
  <ExpressTransactionTime>054802</ExpressTransactionTime>
  <ExpressTransactionTimezone>UTC-05:00:00</ExpressTransactionTimezone>
  <Batch>
    <HostBatchID>1</HostBatchID>
  </Batch>
  <Card>
    <AVSResponseCode>N</AVSResponseCode>
    <CardLogo>Mastercard</CardLogo>
    <CardNumberMasked>xxxx-xxxx-xxxx-6781</CardNumberMasked>
  </Card>
  <Transaction>
    <TransactionID>2005663676</TransactionID>
    <ApprovalNumber>000048</ApprovalNumber>
    <AcquirerData>bMCC1440300714</AcquirerData>
    <ProcessorName>NULL_PROCESSOR_TEST</ProcessorName>
    <TransactionStatus>Authorized</TransactionStatus>
    <TransactionStatusCode>5</TransactionStatusCode>
    <ApprovedAmount>10.00</ApprovedAmount>
  </Transaction>
</Response>
</CreditCardAuthorizationResponse>

 

 

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.

 

 

Completing a payment transaction

To complete a previously authorized payment transaction, you can use theCreditCardAuthorizationCompletion 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.

 

curl https://certtransaction.elementexpress.com  \
   -H "Content-Type: text/xml; charset=UTF-8"  \
   -X POST \
   -d  \
     '<?xml version="1.0"?>
         <CreditCardAuthorizationCompletion xmlns="https://transaction.elementexpress.com">
            <Credentials>
                 <AccountID>as obtained in step 2</AccountID>
                 <AccountToken>as obtained in step 2</AccountToken>
                 <AcceptorID>as obtained in step 2</AcceptorID>
            </Credentials>
            <Application>
                 <ApplicationID>as obtained in step 2</ApplicationID>
                 <ApplicationName>MyExpressTest</ApplicationName>
                 <ApplicationVersion>1.0.0</ApplicationVersion>
            </Application>
            <Terminal>
                 <TerminalID>01</TerminalID>
                 <CardholderPresentCode>2</CardholderPresentCode>
                 <CardInputCode>5</CardInputCode>
                 <TerminalCapabilityCode>3</TerminalCapabilityCode>
                 <TerminalEnvironmentCode>2</TerminalEnvironmentCode>
                 <CardPresentCode>2</CardPresentCode>
                 <MotoECICode>1</MotoECICode>
                 <CVVPresenceCode>1</CVVPresenceCode>
            </Terminal>
            <Transaction>
                  <TransactionAmount>10.00</TransactionAmount>
                  <MarketCode>7</MarketCode>
                  <TransactionID>2005663676</TransactionID>
            </Transaction>
        </CreditCardAuthorizationCompletion>'

 

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

 

<CreditCardAuthorizationCompletionResponse xmlns='https://transaction.elementexpress.com'>
  <Response>
    <ExpressResponseCode>0</ExpressResponseCode>
    <ExpressResponseMessage>Success</ExpressResponseMessage>
    <HostResponseCode>000</HostResponseCode>
    <HostResponseMessage>AP</HostResponseMessage>
    <ExpressTransactionDate>20151021</ExpressTransactionDate>
    <ExpressTransactionTime>061606</ExpressTransactionTime>
    <ExpressTransactionTimezone>UTC-05:00:00</ExpressTransactionTimezone>
    <Batch>
      <HostBatchID>1</HostBatchID>
      <HostItemID>2</HostItemID>
      <HostBatchAmount>20.00</HostBatchAmount>
    </Batch>
    <Card>
      <CardLogo>Mastercard</CardLogo>
      <CardNumberMasked>xxxx-xxxx-xxxx-6781</CardNumberMasked>
    </Card>
    <Transaction>
      <TransactionID>2005663687</TransactionID>
      <ApprovalNumber>000048</ApprovalNumber>
      <AcquirerData>bMCC1440300714</AcquirerData>
      <ProcessorName>NULL_PROCESSOR_TEST</ProcessorName>
      <TransactionStatus>Approved</TransactionStatus>
      <TransactionStatusCode>1</TransactionStatusCode>
    </Transaction>
  </Response>
</CreditCardAuthorizationCompletionResponse>

 

 

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

 

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.

 

curl https://certtransaction.elementexpress.com  \
   -H "Content-Type: text/xml; charset=UTF-8" \
   -X POST \
   -d \
     '<?xml version="1.0"?>
         <CreditCardReturn xmlns="https://transaction.elementexpress.com">
            <Credentials>
                 <AccountID> as obtained in step 2</AccountID>
                 <AccountToken> as obtained in step 2</AccountToken>
                 <AcceptorID> as obtained in step 2</AcceptorID>
            </Credentials>
            <Application>
                 <ApplicationID> as obtained in step 2</ApplicationID>
                 <ApplicationName>MyExpressTest</ApplicationName>
                 <ApplicationVersion>1.0.0</ApplicationVersion>
            </Application>
            <Terminal>
                 <TerminalID>01</TerminalID>
                 <CardholderPresentCode>2</CardholderPresentCode>
                 <CardInputCode>5</CardInputCode>
                 <TerminalCapabilityCode>3</TerminalCapabilityCode>
                 <TerminalEnvironmentCode>2</TerminalEnvironmentCode>
                 <CardPresentCode>2</CardPresentCode>
                 <MotoECICode>1</MotoECICode>
                 <CVVPresenceCode>1</CVVPresenceCode>
            </Terminal>
            <Transaction>
                  <TransactionAmount>10.00</TransactionAmount>
                  <MarketCode>7</MarketCode>
                  <TransactionID>2005663687</TransactionID>
            </Transaction>
        </CreditCardReturn>'

 

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

 

<CreditCardReturnResponse xmlns='https://transaction.elementexpress.com'>
  <Response>
    <ExpressResponseCode>0</ExpressResponseCode>
    <ExpressResponseMessage>Approved</ExpressResponseMessage>
    <HostResponseCode>000</HostResponseCode>
    <HostResponseMessage>AP</HostResponseMessage>
    <ExpressTransactionDate>20151021</ExpressTransactionDate>
    <ExpressTransactionTime>070404</ExpressTransactionTime>
    <ExpressTransactionTimezone>UTC-05:00:00</ExpressTransactionTimezone>
    <Batch>
      <HostBatchID>1</HostBatchID>
      <HostItemID>4</HostItemID>
      <HostBatchAmount>20.00</HostBatchAmount>
    </Batch>
    <Card>
      <CardLogo>Mastercard</CardLogo>
      <CardNumberMasked>xxxx-xxxx-xxxx-6781</CardNumberMasked>
    </Card>
    <Transaction>
      <TransactionID>2005663709</TransactionID>
      <ApprovalNumber>000004</ApprovalNumber>
      <ProcessorName>NULL_PROCESSOR_TEST</ProcessorName>
      <TransactionStatus>Approved</TransactionStatus>
      <TransactionStatusCode>1</TransactionStatusCode>
    </Transaction>
  </Response>
</CreditCardReturnResponse>

 

 

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.

Outcomes