triPOS Cloud Integration Guide

Document created by Worldpay Bot on May 25, 2017Last modified by katharine.unsworth on Jul 15, 2019
Version 13Show Document
  • View in full screen mode

View Previous: triPOS Cloud TutorialView Next: Transaction API orLane Management API



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 pos system document is intended for the payments developer integrating to the Express platform via the triPOS Cloud payment processing application. Learn the transaction flow of credential testing, ordering hardware and understanding the payments certification process. It provides a high-level view of the API with REST documentation, how to create a valid request, and also answers frequently asked questions from our Point of Sale 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.



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:




Before You Begin

Create Your Express Test Credentials

If you do not already have Express test credentials, go to 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


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


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 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: will return a list of the root triPOS Cloud hyperlinks.


Sample Response from GET Request to api/v1




"_links": [ { "href":"
", "method":"POST", "rel":"sale" }, ... ... { "href":"
", "method":"POST", "rel":"authorization" }, ... ... ... ... ],






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

"_links": [ { "href":"
", "method":"POST", "rel":"return" } ],



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


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.

pinPadIdleMessage (triPOS.config)

idleMessage (Cloud)

Welcome to my store


Added in triPOS Cloud Release v6.
corsAllowedOrigins[empty]Will not be configurable. For security best practices, CORS requests will NOT be allowed in triPOS Cloud.
allowPartialApprovalstrueCurrently available on the API.
confirmOriginalAmounttrueAdded in triPOS Cloud Release v6.
creditAvsEntryConditionKeyedTo be added to the API in a future enhancement.
checkForDuplicateTransactionstrueCurrently available on the API.
currencyCodeUsdWill not be configurable in request API.
emvFallbackAllowedAllowAfterChipErrorWill not be configurable. Only one value supported.

isCashbackAllowed (triPOS.config)

cashBackOptions (Cloud)




Currently available on the API.

isDebitSupported (triPOS.config)

allowDebit (Cloud)




Currently available on the API.

isDebitRefundSupportedfalseTo be added to the API in a future enhancement.
isGiftSupportedfalseAdded in triPOS Cloud Release v6.
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 (Cloud)




Currently available on the API.

marketCodeRetailCurrently available on the API.


thresholdAmount (Cloud)



Supported through thresholdAmount in API.

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

signatureFormatPointsLittleEndianNot currently planned.
terminalTypePointOfSaleNot currently planned.
isManualEntryAllowedtrueAdded in triPOS Cloud Release v6.
isCscSupportedfalseTo be added to the API in a future enhancement.
isContactlessMsdEntryAllowedtrueTo be added to the API in a future enhancement.
promptForSignature[empty]Always, Never, UseThreshold.  Currently available on the API.
displayTransactionAmountfalseAdded in triPOS Cloud Release v6.
invokeManualEntryfalseAdded in triPOS Cloud Release v6.


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 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 orLane Management API View Previous: triPOS Cloud Tutorial