RESTful Credit Transactions on triPOS

Document created by matthew.milner on May 9, 2016Last modified by matthew.milner on Jun 1, 2016
Version 7Show Document
  • View in full screen mode

Through our triPOS RESTful API, developers can easily post payments in minutes. All requests should be sent in testMode during development. Documentation and descriptions of the RESTful API for triPOS are located on the installed triPOS service. Browse to http://localhost:8080/help for up-to-date documentation.

 

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

 

 

Required HTTP request headers

 

To verify that each request is coming from an authorized source, triPOS checks specific values that the client must send up in the header with each request in a value called tp-authorization. Along with the tp-authorization header, the client must always send up application-related fields in the header.

 

triPOS can be switched into test mode by editing the application section in the triPOS.config file and setting testMode to true. The authorization header should look like this in testMode:

 

tp-authorization: Version=1.0, Credential=045c58b9-7441-495f-849a-5a6de45fbe31
tp-application-id: 12345
tp-application-name: MyApplication
tp-application-version: 1.0.0
tp-return-logs: false
accept: application/json

 

Parameters

Parameter

Parameter Type

Data Type

Description

tp-application-id            

header

string

The ID of the business application.

tp-application-name

header

string

The name of the business application.

tp-application-version

header

string

The version of the business application.

tp-authorization

header

string

The authorization header.

tp-request-id

header

string

A unique ID for this request. This value should be a UUID or GUID.

tp-return-logs

header

boolean

Set to true to have logs populated in the response.

 

POSTS

All transactions are posted to http://localhost:8080/api/v1/ followed by the transaction type at the end of the URL. For example, a credit authorization would be: http://localhost:8080/api/v1/authorization

 

 

Credit Request Transaction Examples

 

api/v1/Sale

A Credit Sale is used to process a credit card purchase (VISA, MasterCard, American Express, Discover, Carte Blanche, Diner’s Club, JCB or Other) in one step.

 

POST Request

LaneId and transactionAmount are required fields

 

{
  "laneId": "9999",
  "transactionAmount": "3.25",
  "emvFallbackReason":"None",
  "address": {
    "billingAddress1": "123 Sample Street",
    "billingCity": "Chandler",
    "billingPostalCode": "85224",
    "billingState": "AZ"
},
  "configuration": {
    "allowPartialApprovals": "true",
    "checkForDuplicateTransactions": "true",
    "marketCode": "Retail"
  }

 

api/v1/authorization

This approach is used when the credit purchase occurs in two steps, authorization and completion. This is commonly used when the exact purchase amount unknown, but the final transaction will be processed for payment later. The authorization is used to estimate an amount on a credit card. The transaction will be finalized using a subsequent completion, discussed in the next example.

 

POST Request

LaneId and transactionAmount are required field

 

{
  "laneId": "9999",
  "transactionAmount": "3.25",
  "emvFallbackReason":"None",
  "address": {
    "billingAddress1": "123 Sample Street",
    "billingCity": "Chandler",
    "billingPostalCode": "85224",
    "billingState": "AZ"
  },
  "configuration": {
    "allowPartialApprovals": "true",
    "checkForDuplicateTransactions": "true",
    "marketCode": "FoodRestaurant"
}

 

 

/api/v1/authorization/{transactionId}/completion

Completion is used to finalize a previous authorization transaction so that settlement can occur. The transactionId is the value returned by the original authorization response.

 

POST Request

LaneId and transactionAmount are required fields

 

{
  "laneId": "9999",
  "transactionAmount": "3.25",
  "tipAmount": "1.00",
  "emvFallbackReason":"None",
  "address": {
    "billingAddress1": "123 Sample Street",
    "billingCity": "Chandler",
    "billingPostalCode": "85224",
    "billingState": "AZ"
  },
  "configuration": {
    "allowPartialApprovals": "true",
    "checkForDuplicateTransactions": "true",
    "marketCode": "FoodRestaurant"
}

 

/api/v1/refund

A Refund is an independent, non-referenced transaction used to credit a cardholder’s account. This method should be called when refunding a debit Payment Transaction or  the transactionId is unknown from a previous credit authorization or sale.

 

POST Request

LaneId and transactionAmount are required fields

 

{
  "laneId": "9999",
  "transactionAmount": "3.25",
  "emvFallbackReason":"None",
},
  "configuration": {
    "allowPartialApprovals": "false",
    "checkForDuplicateTransactions": "true",
    "marketCode": "Retail"
  }

 

/api/v1/return/{transactionId}/{paymentType}

The triPOS return endpoint maps to several Express endpoints depending on the payment type. Since return takes a transaction ID, it does not require a card swipe. The payment type must be passed in as a part of the request path. If the payment type is credit, triPOS sends a CreditCardReturn to Express. If the card type is debit, triPOS will return an error. To use the Express method DebitCardReturn see the triPOS method refund.

 

POST Request

LaneId and transactionAmount are required fields

 

{
  "laneId": "9999",
  "transactionAmount": "3.25",
  "emvFallbackReason":"None",
},
  "configuration": {
    "allowPartialApprovals": "false",
    "checkForDuplicateTransactions": "true",
    "marketCode": "Retail"
  }

 

/api/v1/reversal/{transactionId}/{paymentType}

Creates a new full reversal based on given transactionId, paymentType, and the passed in amounts.

Reverals refer to a practice within the card processing industry of communicating directly with the card Issuing bank in order to reverse the transaction and release the held funds back into the cardholder’s account. This is the preferred method for cancelling a transaction within the open batch. Reversals generally take less time (from 2 to 72 hours) to be removed from the cardholder’s banking statement. Reversals may be used to reverse an existing Credit Sale, Authorization and Authorization Completion.

 

{
  "laneId": "9999",
  "transactionAmount": "3.25",
  "emvFallbackReason":"None",
},

  "configuration": {
    "allowPartialApprovals": "false",
    "checkForDuplicateTransactions": "true"
}

 

 

Credit Response Transaction Example

Some information from the response below has been removed for brevity.

 

{
  "cashbackAmount":0,
  "debitSurchargeAmount":0,
  "approvedAmount":3.25,
  "convenienceFeeAmount":0,
  "subTotalAmount":3.25,
  "tipAmount":0,
  "accountNumber":"************6781",
  "binValue":"4003000000000000",
  "cardHolderName":"GLOBAL PAYMENTS TEST CARD/",
  "cardLogo":"Visa",
  "currencyCode":"Usd",
  "entryMode":"Swiped",
  "paymentType":"Credit",
  "signature":{},
  "terminalId":"0000009999",
  "totalAmount":3.25,
  "approvalNumber":"000021",
  "isApproved":true,
  "_processor":
 {
   "processorLogs":[],
   "processorRawResponse":"<CreditCardSaleResponse xmlns=\"https://transaction.elementexpress.com\">
     <Response>
       <Address>
         <BillingAddress1>123 Sample Street</BillingAddress1>
         <BillingZipcode>85224</BillingZipcode>
       </Address>
       <Batch>
         <HostBatchID>1</HostBatchID>
         <HostItemID>131</HostItemID>
         <HostBatchAmount>425.75</HostBatchAmount>
       </Batch>
       <Card>
         <CardLogo>Visa</CardLogo>
       </Card>
       <ExpressResponseMessage>Approved</ExpressResponseMessage>
       <ExpressTransactionDate>20150514</ExpressTransactionDate>
       <ExpressTransactionTime>122139</ExpressTransactionTime>
       <ExpressTransactionTimezone>UTC-05:00:00</ExpressTransactionTimezone>
       <HostResponseCode>000</HostResponseCode>
       <HostResponseMessage>AP</HostResponseMessage>
       <Transaction>
         <AcquirerData>aVb001234567810425c0425d5e00</AcquirerData>
         <ApprovalNumber>000021</ApprovalNumber>
         <ApprovedAmount>3.25</ApprovedAmount><ProcessorName>NULL_PROCESSOR_TEST</ProcessorName>
         <ReferenceNumber>Ref000001</ReferenceNumber>
         <TransactionID>2005013738</TransactionID>
         <TransactionStatus>Approved</TransactionStatus>
         <TransactionStatusCode>1</TransactionStatusCode>
       </Transaction>
       <ExpressResponseCode>0</ExpressResponseCode>
     </Response>
   </CreditCardSaleResponse>",
   "processorReferenceNumber":"Ref000001",
   "processorRequestFailed":false,
   "processorRequestWasApproved":true,
   "processorResponseCode":"Approved",
   "processorResponseMessage":"Approved"
 },
  "statusCode":"Approved",
  "transactionDateTime":"2015-05-14T10:21:39.0000000-07:00",
  "transactionId":"2005013738",
  "_errors":[],
  "_hasErrors":false,
  "_links":[],
  "_logs":[],
  "_type":"saleResponse",
  "_warnings":[]
}

Attachments

    Outcomes