Young Developers - In-Store Quick Start

Document created by gjsissons on Mar 28, 2017Last modified by gjsissons on Jul 19, 2017
Version 29Show Document
  • View in full screen mode

 

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.

 

mx915.jpgTo the right is an example of an in-store payment terminal supported by Vantiv's triPOS middleware. (we'll get to this shortly) You've likely seen these or similar devices in stores where you shop.

 

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.

 

triPOS_diagram.PNG

 

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.

 

using_element_express.JPG


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:

 

https://certtransaction.elementexpress.com/

 

You will need credentials to connect to the endpoint.

 

Express Credentials

 

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.

CredentialValue
AccountID1011363
AccountToken90F5CE4ED18F4E214051394E6D7E43754D8BEC95504C9CC59A66D3BB7BC68898DB061301
AcceptorID3928907

 

 

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

 

Test Cards

 

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 TypeCard NumberExpiration MonthExpiration Year
Visa/Debit4003000123456781122019
Visa2 (keyed)4003002345678903122019
MasterCard/Debit5499990123456781122019
MasterCard2 (keyed)5499992345678903122019
American Express373953191351005092019
Discover6011000990191250122019
Discover26011000990191243122019
Discover336018634567895122019

 

 

triPOS

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.

 

using_tripos_in_your_application.JPG

 

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 1Header 2
AccountID1045836
AccountToken5CFF00007319E5C0C7DB2F7C144E65068A462ED2549C6360099A962C573ED9EF1BB97401
ApplicationID8415
AcceptorID3928907

 

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

URL  https://triposcert.vantiv.com/api/v1/sale

 

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-application-id: 1234

tp-application-name: triPOS.YDP.Cloud

tp-application-version: 1.0.0

tp-authorization: Version=2.0 accept: application/json  Content-Type: application/json

tp-express-acceptor-id:3928907

tp-express-account-id:1045836

tp-express-account-token:5CFF00007319E5C0C7DB2F7C144E65068A462ED2549C6360099A962C573ED9EF1BB97401

tp-request-id:24dddd32-6c89-11e7-907b-a6006ad3dba0

 

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

 

{

"laneId":"9999",

"transactionAmount":"1.22"

}

 

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

arc_screen_capture.PNG

 

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.

arc_response.PNG

 

 

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:

 

  1. 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.

Attachments

    Outcomes