triPOS Cloud Integration Guide

Document created by Chris Jennings on May 25, 2017Last modified by Chris Jennings on May 25, 2017
Version 3Show Document
  • View in full screen mode

View Previous: triPOS Cloud TutorialView Next: Transaction API or Lane Management API

 

Introduction

triPOS Cloud is a turnkey payment processing application designed to process all payment methods including EMV, credit, PIN debit and mobile wallets (Apple Pay, Andriod Pay, etc.). triPOS Cloud easily interfaces with custom business management software via a REST API. The application supports processing of domestic debit and credit transactions through the Express platform. This document is intended for the integrator who wishes to interface to the Express platform via the triPOS Cloud payment processing application. It provides a high-level view of the API, how to create a valid request, and answers to frequently asked questions have been added to our POS community forum. This document does not cover generic card-present or EMV transaction processing, compliance requirements, hardware interfaces or direct integration to the Express platform. Please refer to the following documentation for further information on these subjects: Express Interface API v2.7.7

 

 

Transaction Flow

triPOS Cloud accepts requests from business management software for processing end-to-end financial transactions through the Express platform. The diagram below illustrates the interaction among the business management software, triPOS Cloud, the PIN pad and Express:

 

triPOS+Cloud+data+flow_update.jpg

 

Before You Begin

Create Your Express Test Credentials

If you do not already have Express test credentials, go to http://www.elementps.com/Create-a-Test-Account and create a test account. You will receive an email containing the credentials needed to access triPOS Cloud:

  • AccountID
  • AccountToken
  • ApplicationID
  • AcceptorID

IMPORTANT NOTE: If you plan testing EMV you will need to request additional credentials from certification@vantiv.com

 

Order Test Equipment

triPOS Cloud has the ability to quickly added new EMV PIN pads with no additional integration work required on your part. Our first EMV certified device is the Verifone MX915. You may request a test device from your assigned implementation consultant or begin your testing efforts by utilizing the simulator. Partners can order test equipment by emailing certification@vantiv.com.

 

Review the Certification Process

We have provided links below to the appropriate certification documents, and please review Express Certification Overview to help prepare you during your development work.  When you are ready to move forward, please complete the certification documents below.

 

 

API Overview

REST Documentation

triPOS Cloud supports two APIs Transaction Processing and Lane Management. For documentation and descriptions of the REST API for triPOS Cloud click the links below:

 

Transaction Processing API Documentation

Lane Management API Documentation

 

Message Transport

The business management software communicates with triPOS Cloud over the public Internet. To simplify integration of existing solutions, requests and responses are transported via HTTPS in the same fashion as the business management software would when interfacing directly to the Express platform.

 

Message Format

triPOS Cloud accepts JSON formatted request messages and returns responses in the same format as the request.

 

Each request is identified by a transaction type and is accompanied by data elements pertaining to the request. However, a typical triPOS Cloud request is simpler than an Express request as card information is not included. Card information is obtained downstream via direct interactions between triPOS Cloud and the PIN pad.

 

Each request requires a header with specific fields:

      • If the request is a POST or PUT request it requires parameters to be sent in the request body (with the exception of the cloudapi/v1/lanes/{{laneId}}/activationCode endpoint, which is a POST with an empty body).
      • For GET and DELETE, any parameters will be sent up in the URL’s query string.
      • For any type of request, some values such as PaymentType may be sent in the URL. See the API documentation for more detailed API documentation.

 

Two Steps To Processing

1. Pair the device to the merchant's API credentials - When the PIN pad device arrives it will be in an un-paired state.  When the device is powered up it will display a seven-character code.  Implement a UI element in the business management software to allow a user to enter this six character code and then send a message to triPOS Cloud to pair the device.  The message structure is defined in the lane management API linked above.

 

2. Send transactions - After the device is paired to the merchant's API credentials the business management software can send any valid API command to perform transaction processing or other types of processing supported via the API.

 

Receipts

Receipts can be generated using the returned data from each transaction. If a signature was collected on the PIN pad, the Signature field of the response will contain a byte array of the signature data along with the format of the signature data. You can look at our CSharp sample DisplaySignature application for triPOS Distributed on GitHub. The source code that shows how to convert this to a byte array into a BMP can be found here.

 

 

HATEOAS API Response Links

triPOS Cloud implements HATEOAS (Hypertext as the Engine of Application State). HATEOAS allows a business application to interact with the triPOS Cloud REST service through dynamic hyperlinks returned in the response. Using these response links is a best practice for decoupling the business application from the triPOS Cloud REST API.

 

NOTE: It is also the best way to future-proof an application for additional triPOS Cloud functionality as it allows you to avoid hard-coding endpoint URLs in your application.

 

Each return link contains three values: href, method, and relation. For example, for a default installation, sending a GET request to the root triPOS Cloud service URL at:  https://triposcert.vantiv.com/api/v1 will return a list of the root triPOS Cloud hyperlinks.

 

Sample Response from GET Request to api/v1

{
    "_errors":[], 
    "_hasErrors":false, 
    "_links": [ { "href":"https://triposcert.vantiv.com/api/v1/sale", "method":"POST", "rel":"sale" }, ... ... { "href":"https://triposcert.vantiv.com/api/v1/authorization", "method":"POST", "rel":"authorization" }, ... ... ... ... ],
    "_logs":[], 
    "_type":"getServicesResponse", 
    "_warnings":[] 
}

 

From this response you know:

      • To transact a sale, POST to the href value of the link containing “sale” as the relation and
      • To transact an authorization, POST to the href value of the link containing “authorization” as the relation

 

Sample Response from POST Request to api/v1

{
    "approvedAmount":25.00,
    "paymentType":"Credit",
    "transactionId":"2004010421",
    ...
    ...
    "_errors":[],
    "_hasErrors":false,
    "_links": [ { "href":"https://triposcert.vantiv.com/api/v1/return/2004010421/credit", "method":"POST", "rel":"return" } ], 
    "_logs":[],
    "_type":"saleResponse",
    "_warnings":[]
}

 

From this response, the href indicates that the endpoint hyperlink for returning a sale is in the format /api/v1/return/{transactionId}/{paymentType}. NOTE: {transactionID} and {paymentType} are variables.

 

For this particular credit card sale request to localhost, the transactionId of 2004010421 was returned, therefore the return endpoint URL is https://triposcert.vantiv.com/api/v1/return/2004010421/credit.

 

NOTE: The triPOS Cloud development team strongly recommends business applications use the HATEOAS response link with the appropriate relation to call any service endpoint (for example, always use the return relation with method POST to POST a Return to the API).

 

Required HTTP Request Headers

The client must always send up application-related fields in the header.  Three headers are required to identify which application is calling triPOS. These values will be passed on to the host and reflected in the Express dashboard:

 

tp-application-id: {ApplicationID}

tp-application-name: {ApplicationName}

tp-application-version: {ApplicationVersion}

 

The authorization version is the current version used to authenticate with triPOS Cloud:

 

tp-authorization: Version=2.0

 

Accept and content-type will always be application/json for triPOS Cloud:

 

accept: application/json

Content-Type: application/json

 

The Express credentials that identify a merchant:

 

tp-express-acceptor-id:{your express acceptor id}

tp-express-account-id:{your express account id}

tp-express-account-token:{your express token}

 

A unique request id that is a valid UUID or GUID and unique for each and every request.

 

tp-request-id:{valid GUID}

 

Device Configuration

Default values used by triPOS Cloud are defined below.  Certain parameters below may be configurable per transaction when included on the triPOS Cloud request. Configuration parameters currently available on a per-transaction basis are in bold

triPOS Cloud ParameterDefault ValueNotes
autoReversalRetryLimit1Will not be configurable. Cloud will deterministically reverse when necessary.
pinPadIdleMessageWelcome to my storeTo be added to the Lane API in a future enhancement.
corsAllowedOrigins*Will not be configurable. Cloud will allow all CORS origins.
allowPartialApprovalstrueCurrently available on the API.
confirmOriginalAmounttrueTo be added to the API in a future enhancement.
creditAvsEntryConditionKeyedTo be added to the API in a future enhancement.
checkForDuplicateTransactionstrueCurrently available on the API.
currencyCodeUsdWill not be configurable in reqeust API.
emvFallbackAllowedAllowAfterChipErrorWill not be configurable. Only one value supported.

isCashbackAllowed (triPOS.config)

cashBackOptions (API only)

false

[empty]

 

Currently available on the API.

isDebitSupported (triPOS.config)

allowDebit (API only)

false

false

 

Currently available on the API.

isDebitRefundSupportedfalseTo be added to the API in a future enhancement.
isGiftSupportedfalseTo be added to the API in a future enhancement.
isEmvSupportedtrueTo be added to the API in a future enhancement.
confirmConvenienceFeeAmounttrueTo be added to the API in a future enhancement.
isHealthcareSupportedtrueSupported through Healthcare in API. If fields exist, healthcare is assumed.

isTipAllowed (triPOS.config)

tipOptions (API only)

true

[empty]

 

Currently available on the API.

marketCodeRetailCurrently available on the API.

creditSaleSignatureThresholdAmount

thresholdAmount (API only)

0.00

[empty]

Supported through thresholdAmount in API.

Specifies the threshold value to use for a signature prompt.  Currently available on the API.

signatureFormatPointsLittleEndianNot currently planed.
terminalTypePointOfSaleNot currently planned.
isManualEntryAllowedtrueTo be added to the API in a future enhancement.
isCscSupportedfalseTo be added to the API in a future enhancement.
isContactlessMsdEntryAllowedtrueTo be added to the API in a future enhancement.
promptForSignature (API only)[empty]Always, Never, UseThreshold.  Currently available on the API.

 

Request a Certification Review

We've outlined important processing and certification/testing scenarios to consider during your development to ensure nothing is missed. When you are ready to certify, both the  Processing Scenarios and Certification Details documents should be reviewed and submitted to certification@vantiv.com. Your assigned implementation consultant will review and provide feedback based on the information provided.

 

Once you've completed the developer work and are ready to deploy it to a production environment, you'll want to certify your application with Vantiv. Our team is standing by to assist as soon as you're ready to submit a Request for Certification. Vantiv records your successful submissions to the sandbox environment to certify that your application is working properly.

 

After you've successfully certified you will receive instructions for requesting production access to begin onboarding live merchant accounts and a certification letter.

 

Start the certification process

 

 

 

 

View Next: Transaction API or Lane Management API View Previous: triPOS Cloud Tutorial

1 person found this helpful

Attachments

    Outcomes