About In-Store Payments
Vantiv Integrated Payments
APIs for In-Store Payments
Using the Express API
- About In-Store Payments
- Vantiv Integrated Payments
- APIs for In-Store Payments
- Using the Express API
About In-Store Payments
Vantiv has multiple payment platforms that can be used for In-store payments. The examples presented here center around Vantiv's Express Gateway and Vantiv's triPOS payment middleware.
- Express is a payment gateway built for card-present in-store payments. Express can be used to process payments with Vantiv as well as with third-party processors. For students interested in learning about payment gateways, Payment Gateways Whitepaper is a good place to start.
- triPOS payment middleware is a solution that makes it easier for developers to support normally complex integrations with EMV capable payment terminals and Pin Pads. For a primer on triPOS and the role of payment middleware in point of sale systems, we have a similar whitepaper - triPOS - Building a Next Generation POS.
If you have no idea what these things are, no worries! Read on! You've come to the right place.
Integrating with these devices is a headache for point of sale developers, and this is one of the major problems that the triPOS technology solves.
Point of sale systems used to fairly easy to built and test, but with EMV (chip cards), NFC "tap" payments, and the growing popularity of mobile wallets like Apple Pay and Android Pay, in-store payments have become much more complex.
This is why developers need simpler solutions, and why the world needs more developers.
Vantiv Integrated Payments
Integrated Payments solutions are point-of-sale solutions that integrate with other back-office systems. These may include inventory management, accounting and customer relationship management (CRM) solutions. These systems are generally built by third party developers to service specific industries.
Ever show up at a busy restaurant only to have a greeter take your name, put you on a waiting list, and hand you one of those fancy pagers that lights up when your table is ready? This is your Integrated POS at work! Besides managing payments, the integrated point of sale increasingly handles all facets of the customer experience. Integrated Payment applications are being enhanced at a rapid clip to support on-line reservations, order-ahead, pay at table functionality and more.
Integrated Payment solutions usually built around a general purpose computing platform and may run an operating system like Microsoft Windows or Linux under the covers. Integrated POS solutions need to accommodate interfaces to devices like cash drawers, mag stripe readers, EMV terminals and Pin Pads, scanners and other devices (like remote pagers in our restaurant example).
APIs for In-Store Payments
For in-store payment processing, developers can think of payment APIs as having two distinct parts.
- The Transaction processing API - This is the API that handles the actual processing of payments. It handles payment transactions involving Credit cards, Debit cards, Checks and various types of Gift cards, Loyalty program cards and other specialty cards. The API is similar in many respects to the eCommerce API presented earlier, but APIs designed for in-store systems need to incorporate additional features (lane manage in super markets, EMV chip cards, handling loyalty and gift cards etc. In our examples we use Vantiv's Express platform are our API for card-present processing.
- Payment middleware / Device control API - Managing devices like Pin Pads and complying with technical and certification requirements for EMV (chip cards) is a major headache for point of sale providers. EMV integrations are complicated, and developers are required to re-certify their applications with card brands whenever they make changes. To make integrations simpler, payment middleware solutions have become popular. With a payment middleware solution, the point of sale developer can treat payment hardware like EMV capable terminals as a "back box" and avoid coding to specific devices. The payment middleware abstracts away all this complexity. Payment integrations that involve this type of middleware are often referred to as "Semi-Integrated Payment Solutions". With a semi-integrated solution, the middleware vendor handles all these details around certification to devices and interacting with the payment gateway so that the developer doesn't need to deal with this. Vantiv's payment middleware solution that works with the Express gateway is called triPOS. I diagram of how these solutions fit together is shown below.
Using the Express API
You can learn about the Express API by reviewing the Express Interface API documentation.
The Express API supports either W3C SOAP 1.1 or XML messages sent using the POST method via HTTPS. In this respect it is similar to Vantiv's eCommerce API.
In the examples below we illustrate integrations using the simpler XML POST integration method. The type of integration facilitated by Express (sometimes called a direct integration) is shown below. In this type of integration your point of sale application will be responsible for interfacing directly with devices like card readers and processing payments via the Internet. Typically builders of custom point of sale solutions who are technically sophisticated would opt for this approach.
This method of integration is a little more difficult, but it is helpful to understand how Express works before we move on to the simpler interface presented by the triPOS API.
As with the eCommerce interface, payment requests are made by sending XML formatted messages to an internet accessible endpoint.
For testing against our non-production certification environment you can use the following endpoint:
You will need credentials to connect to the endpoint.
The shared credentials in the table below are available for your use. You can check the Express Interface API documentation for details on each credential.
Exercise 1: Authorizing a Payment
Typically, the first thing you do when processing an in-store payment is seek an Authorization from the bank that issued the customer’s Credit or Debit card.
The Authorization ensures that the card is valid and that there is sufficient credit to cover the purchase. The Authorization also "holds" the funds for a period of time, typically until a Capture operation is performed or until an authorization is Cancelled.
To send an authorization, you will need to POST an XML message via HTTPS to our endpoint above. There are several ways to do this:
- You can use a tool like cURL (This is recommended as an easy way to get started for learning purposes)
- You can use a utility like Postman. If you don't have cURL this is your best bet. We've provided detailed instructions on how to use Postman here.
- You can construct your own XML POST transaction using your language of choice (Python, Java, C#, Objective-C etc..) to generate the appropriate XML and send it to the endpoint
There are no client-side SDKs for Vantiv's Express API. There are two reasons for this:
- Developers often prefer to code directly to our XML specification so that they are not dependent on a third party SDK that can complicate testing and inject externally dependencies into their software releases.
- Developers who code to the tirPOS payment middleware (via a RESTful API) don't need talk directly to Express since the triPOS middleware handles the Express Integration for them.
A sample Authorization using Vantiv's Express API is shown below.
This example is available here on GitHub.
#!/bin/sh 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>1011363</AccountID> <AccountToken>90F5CE4ED18F4E214051394E6D7E43754D8BEC95504C9CC59A66D3BB7BC68898DB061301</AccountToken> <AcceptorID>3928907</AcceptorID> </Credentials> <Application> <ApplicationID>2803</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>5499990123456781</CardNumber> <ExpirationMonth>12</ExpirationMonth> <ExpirationYear>19</ExpirationYear> </Card> <Transaction> <TransactionAmount>10.00</TransactionAmount> <MarketCode>7</MarketCode> </Transaction> </CreditCardAuthorization>'
Note some of the differences between the Express API used for in-store processing and the eCommerce API
- The Express API gathers information related to the Application name and version. Rather than being aimed at individual merchants, the Express API is more tailored to point of sale integrated solution providers (ISVs).
- The Express API requires significant detail about the payment terminal. This is useful because payment processing fees and card rules can vary depending on the type of terminal and payment transaction. Some of the information about the payment terminal includes:
- Terminal ID - A unique terminal identifer, useful in multi-lane checkout environments to identify where the payment was made
- CardHolderPresentCode - Indicates the presence of the cardholder at the time of the transaction: present, not present, mail-order, phone-order etc.
- TerminalCapabilityCode - Describes the capabilities of the payment terminal: unknown, magstripe reader, contactless magstripe reader etc ..
- TerminalEnvironmentCode - Describes the conditions where the terminal operates - local attended, local unattended, eCommerce, remote attended, remote unattended etc.
- CardPresentCode - Similar to CardHolderPresentCode but refers to the card: values are default, unknown, present, not present
- MotoECICode - Used specifically for Mail-order, Telephone order transactions (MOTO) to define the type of transaction
- CVVPresenceCode - Indicates whether the CVV was provided with the transaction, and if not why not: not provided, provided, illegible etc.
- A MarketCode is used to identify the industry of the merchant. Market codes can be values like AutoRental, DirectMarketing, eCommerce, FoodRestaurant, Quick-serve Restaurant (QSR etc.)
A complete list of all these enumerations are provided in the Express Interface API documentation.
If you run the script above successfully, you should see a response like the message below:
<CreditCardAuthorizationResponse xmlns='https://transaction.elementexpress.com'> <Response> <ExpressResponseCode>0</ExpressResponseCode> <ExpressResponseMessage>Approved</ExpressResponseMessage> <HostResponseCode>000</HostResponseCode> <HostResponseMessage>AP</HostResponseMessage> <ExpressTransactionDate>20170410</ExpressTransactionDate> <ExpressTransactionTime>044344</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>2013670299</TransactionID> <ApprovalNumber>000043</ApprovalNumber> <AcquirerData>bMCC1440300714</AcquirerData> <ProcessorName>NULL_PROCESSOR_TEST</ProcessorName> <TransactionStatus>Authorized</TransactionStatus> <TransactionStatusCode>5</TransactionStatusCode> <ApprovedAmount>10.00</ApprovedAmount> </Transaction> </Response> </CreditCardAuthorizationResponse>
Exercise 2: Completing a Payment Authorization
Once we've Authorized a Credit Card payment, we can perform a CreditCardAuthorizationCompletion transaction to actually transfer the funds.
Authorization Completions are used to complete a final amount based on a previously Authorized transaction. For example restaurants use Authorization Completions to enter a final amount that includes a tip. Authorized Completions can be performed for any amount up to an allowable excess limit determined by the Card Associations.
When you submit an Authorization Completion (shown below), it is essential that you include the TransactionID returned in the initial Authorization Response (above) so that the Authorization Completion has a reference to the original Transaction.
If you run the script below without including the TransactionID returned in Example 1 you'll see an error.
The source for this example is included here in GitHub.
#!/bin/sh 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>1011363</AccountID> <AccountToken>90F5CE4ED18F4E214051394E6D7E43754D8BEC95504C9CC59A66D3BB7BC68898DB061301</AccountToken> <AcceptorID>3928907</AcceptorID> </Credentials> <Application> <ApplicationID>2803</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>5499990123456781</CardNumber> <ExpirationMonth>12</ExpirationMonth> <ExpirationYear>19</ExpirationYear> </Card> <Transaction> <TransactionAmount>10.00</TransactionAmount> <MarketCode>7</MarketCode> <TransactionID>2013670299</TransactionID> </Transaction> </CreditCardAuthorizationCompletion>'
On submitting the Authorization Completion transaction above, you should 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>20170410</ExpressTransactionDate> <ExpressTransactionTime>072851</ExpressTransactionTime> <ExpressTransactionTimezone>UTC-05:00:00</ExpressTransactionTimezone> <Batch> <HostBatchID>1</HostBatchID> <HostItemID>1</HostItemID> <HostBatchAmount>10.00</HostBatchAmount> </Batch> <Card> <CardLogo>Mastercard</CardLogo> <CardNumberMasked>xxxx-xxxx-xxxx-6781</CardNumberMasked> </Card> <Transaction> <TransactionID>2013670834</TransactionID> <ApprovalNumber>000043</ApprovalNumber> <AcquirerData>bMCC1440300714</AcquirerData> <ProcessorName>NULL_PROCESSOR_TEST</ProcessorName> <TransactionStatus>Approved</TransactionStatus> <TransactionStatusCode>1</TransactionStatusCode> </Transaction> </Response> </CreditCardAuthorizationCompletionResponse>
The examples above are specific to Credit Cards, but the Express API supports other types of payment transactions as well including Debit transactions and Check transactions. Review the Express Interface API for details. Although we won't cover it in these simple examples, the API provides a separate family of transactions specific to Debit Cards.
Merchants can also use a "CreditCardSale" to Authorize and Complete a payment in a single transaction. Other commonly used transaction types with Express include:
- AVSOnly Transactions
- Credit / Return Transactions
- Reversal Transactions
- Force Transactions
- Void Transactions
- Adjustment Transactions
- Incremental Authorization Transactions
You can learn more about interfacing to the Express platform in the Express Certification Details document.
Additional cards you can use for testing are provided in the Express Certification document provided below.
|Card Type||Card Number||Expiration Month||Expiration Year|
For developers building point of sale applications that will interface with devices like EMV terminals, using the triPOS API is an easier way for developers to get started.
Point of sale application development typically requires access to hardware. Students following these examples won't usually have access to physical hardware for testing, so we've structured the exercise so that no hardware is required.
An integration using triPOS is easier for developers to manage because triPOS takes responsibility for interfacing with hardware devices like EMV Terminals and Pin Pads. The triPOS middleware interfaces with the Express Gateway (described above). so that you don't need to worry about this as a developer.
This takes your application out of PS-DSS scope, because your application is not exposed to sensitive card holder data.
There are multiple ways of deploying the triPOS middleware. TriPOS can be downloaded so that it runs locally on a Windows-based point of sale device, it can be run on iOS mobile devices using the triPOS SDK or it can be accessed as a cloud service by a point of sale device that resides on premises or a cloud-based point of sale solution. As a reminder, you can learn about triPOS and how it works in our whitepaper, triPOS - Building a Next Generation POS.
Obtaining the triPOS Software (optional)
There are multiple ways to obtain the triPOS software.
In our examples we'll use triPOS Cloud, because it is easy to get started with and doesn't require any local software.
If you have a Windows PC, and would prefer to install the triPOS PC software locally, you can follow the directions on the Vantiv O.N.E. page Install Requirements for triPOS. Regardless of whether you are using triPOS PC, triPOS mobile or triPOS cloud, you can use the same credentials for the exercises below.
Your triPOS credentials
Pleased use these shared test credentials below in the exercise rather than requesting new credentials from Vantiv.
|Header 1||Header 2|
Exercise: triPOS Cloud
In our environment, we don't have access to physical hardware. In the Vantiv Integrated Payments certification environment, developers have the ability to mimic production processing scenarios without the need for physical hardware or test cards.
The examples below will take you through how to process a sales request using the triPOS API. These examples use the Postman software referenced in previous examples. You can also choose to use these examples to construct your own scripts to send and receive JSON to the triPOS endpoint, or write your own software to do the same.
Tools such as Advanced REST Client, Postman, or cURL are excellent tools to become familiar triPOS Cloud. In previous tutorials we introduced you to Postman and scripts written using cURL. In the tutorial below uses the Advanced REST Client.
Additional resources to aid you through are development efforts can be found here:
Step 1: Add Request Headers
triPOS Cloud supports a production URL and a certification URL. For this scenario, we will demonstrate how to process a sale request using the certification
Using your preferred test tool, add the headers to the request as below.
For a complete list of available transaction types and headers, refer to the triPOS Cloud API
tp-authorization: Version=2.0 accept: application/json Content-Type: application/json
The tp-request-id field above is worth of special mention. This field is a unique identifier for a transaction. While it is optional with triPOS PC (when triPOS runs locally on the PC based point of sale) this value is required for use with triPOS cloud.
You can generate a valid UUID for testing using this handy website: https://www.uuidgenerator.net/version1
UUIDs are guaranteed to be unique by combining the MAC address of a device together with a time stamp to generate a 128 number expressed as 32 hex digits (each hex digit being a "nibble" or 4 bits)
Step 2: Build the transaction payload
The use of laneID 9999 triggers the simulator. In a production environment, laneID is used to identify the PIN pad triPOS Cloud service will initiate. For a complete list of parameters supported within a transaction payload view the triPOS Cloud API
Note how much triPOS simulates the interface for the developer. The developer doesn't need to know details of the device in a particular lane nor details about the payment method. triPOS looks after all this on behalf of the developer.
When you insert the raw headers and the raw payload into the Advanced Rest Client, view should look like below.
Make sure that you select https://triposcert.vantiv.com/api/v1/sale as the endpoint, POST as the method and indicate that the content type is application/json as shown.
Step 3: Send the triPOS Cloud API Request
Step 4: Review the response from triPOS
If the request worked properly, you should see a response like the one below.
It's instructive to read through the detailed response to see all of the information that triPOS is passing back to your application.
Note that triPOS sends you back "masked values" for the card so that your application never has visibility to the actual card data.
From your familiarity with the Express API in the previous exercise, you'll notice that triPOS is calling the Express API on your behalf.
The REST API documentation for the triPOS cloud service is available below:
Check back soon for additional code examples using triPOS cloud
Additional Learning exercises:
- Consider the following scenario and construct and run an Express API call appropriate for the following situation:
- A payment is being made from an unattended, remote parking garage
- The payment is accepted via a "swipe" transaction from an Encrypted Reader
- The payment is done as a single transaction (a "Sale" transaction
- The credit card payment is made via an AMEX card
- The amount of the transaction is $20.00 USD.