triPOS Cloud Integration Guide

Document created by Worldpay Bot on May 25, 2017Last modified by jhess on Aug 18, 2019
Version 16Show 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 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 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 your dedicated integration resource. 

 

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.

 

Certification Process

The use of our test environment, test credentials and Express specifications fall under Worldpay’s legal Terms and Conditions and end-user acceptance agreements. The information presented here and access to the testing environment does not represent a path to certification.

 

You will want to work closely and in advance of any development with your Worldpay business development relationship manager. In order to queue up and keep your project on track, assign a dedicated integration resource and help ensure the success of your development work, it is important that you plan and coordinate with a Worldpay business relationship manager before you engage in further development work.

 

If you do not have a Relationship Manager with Worldpay, email ISVBusinessDevelopment@worldpay.com and arrange to discuss your solution with our business development team.

 

 

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.worldpay.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.worldpay.com/api/v1/sale
", "method":"POST", "rel":"sale" }, ... ... { "href":"
https://triposcert.worldpay.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.worldpay.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.worldpay.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 determine to reverse when necessary.

pinPadIdleMessage (triPOS.config)

idleMessage (Cloud)

Welcome to my store

[empty]

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)

false

[empty]

 

Currently available on the API.

isDebitSupported (triPOS.config)

allowDebit (Cloud)

false

false

 

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)

true

[empty]

 

Currently available on the API.

marketCodeRetailCurrently available on the API.

creditSaleSignatureThresholdAmount

thresholdAmount (Cloud)

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

 

 

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

4 people found this helpful

Attachments

    Outcomes