Interpreting the Transaction API Response

Assuming that the Transaction API request has not failed (i.e. it returned with the HTTP 200 status code), and that the Transaction is fully completed (transactionStatus equals to COMPLETED and not PENDING), a Transaction response body (with the content type application/json) will be returned, and it will look similar to the example below:






    "transactionId": "f363c7de-102c-4d80-a902-ed37413ca599",
    "transactionTimeStamp": "201809182353193193",
    "merchantId": "8dac4049-20b3-473f-b3a3-2682667ece33",
    "deviceId": "7070714000",
    "transactionStatus": "COMPLETED",
    "data": {
        "PosVendor": "Smartpay",
        "PosRegisterID": "9444ae07-dc63-e49c-33e3-59a7c108cc81",
        "PosBusinessName": "John Doe's Coffee Shop",
        "AmountTotal": "615",
        "DeviceID": "7070714000",
        "Function": "Card.Purchase",
        "Merchant": "1",
        "Company": "Smartpay",
        "RequestId": "f363c7de-102c-4d80-a902-ed37413ca599",
        "TransactionResult": "OK-ACCEPTED",
        "Result": "OK",
        "ResultText": "Transaction takes longer than usual",
        "AuthId": "PIN147",
        "AcquirerRef": "000013",
        "TerminalRef": "79707014",
        "CardPan": "....0138",
        "CardType": "EMV TEST CARD",
        "AccountType": "CREDIT",
        "AmountSurcharge": "15",
        "AmountTip": "100",
        "Timestamp": "20180919115520",
        "Receipt": "         PAYMARK PKMS         \n        TEST TERMINAL         \n        182 Wairau Rd         \n\n*-----------EFTPOS-----------*\nTERMINAL              79707014\nTIME             19SEP18 11:55\nTRAN 000013             CREDIT\nEMV TEST CARD\nCARD                  ....0138\nVisa Debit\nRID: A000000003\nPIX: 1010\nTC : E0567EF3160C55CF\nTVR: 08C0048000\nATC: 04DE\nTSI: E800\nAUTH PIN147\nREF NO            000147      \nPURCHASE              NZ$ 5.00\nSURCHARGE             NZ$ 0.15\nTIP                   NZ$ 1.00\nTOTAL                 NZ$ 6.15\n\n           ACCEPTED           \n******DUPLICATE  RECEIPT******\n*----------------------------*\n\n",
        "RequestTimestamp": "201809182353196949",
        "ResponseTimestamp": "201809182355302736"

Transaction Outcome

There are two fields in the response (as described in the Transaction API Response page) that are relevant to determining the final outcome of the transaction: data.TransactionResult and data.Result.

The POS application obviously has the freedom to interpret all of the possible combinations of the values these two fields can contain, however the recommended approach is to "narrow down" the outcomes to the following:

  • Accepted - The transaction was successfully processed on the Payment Acceptance Device
  • Declined - The transaction was declined on the Payment Acceptance Device
  • Cancelled - The transaction was cancelled on the the Payment Acceptance Device
  • DeviceOffline - The Payment Acceptance Device could not be reached (likely to be experiencing network connectivity issues)
  • Failed - The transaction failed

The outcomes from above can be deducted based on the following values of the data.TransactionResult and data.Result fields:

data.TransactionResult data.Result Outcome Comment
OK-ACCEPTED OK Accepted Technically, OK is the only allowed value if the TransactionResult is OK-ACCEPTED
OK-DECLINED OK Declined Technically, OK is the only allowed value if the TransactionResult is OK-DECLINED
CANCELLED Anything except FAILED-INTERFACE Cancelled
Any other combination Failed If nothing of the above, the transaction has failed

It is recommended that at least these five distinct outcome states be handled by the POS application.

Surcharge and Tipping

Some POS applications have native surcharge and tipping support built-in. In those cases, the surcharge and/or tip amount are applied directly on the POS before the Transaction request is made, and a final total amount is passed on via the API request, for the customer to pay. In this case, SmartConnect does not distinguish which portion of the amount correlates to which "element" of the transaction, it only presents the final amount to pay (unless the Sale Data information is provided, which may provide this break-down).

However, in some instances a surcharge and/or tip might be applied on the EFTPOS Terminal during the customer input phase of a transaction. As a result, a POS may request a transaction for $X, but the total amount processed by the Terminal may be $X+Y, where $Y represents the amount added by the EFTPOS Terminal if configured to do so.

If this is the case, the Transaction API Response will have two fields which will indicate these amounts:

  • AmountSurcharge
  • AmountTip


The AmountTotal field will always contain the total amount processed by the Payment Acceptance Device, which will include either or both surcharge and tip amounts, if they have been added. The absence of AmountSurcharge and AmountTip fields in the response is indicative that the processed amount is the same as the requested amount.

In the example response from the top of the page, the total amount (AmountTotal) processed by the Payment Acceptance Device is $6.15. AmountSurcharge is $0.15 and AmountTip is $1.00, indicating that the original payment amount requested was $5.00 (this information is not contained in the response).


If the POS application supports either surcharge or tipping, it is expected of the application to process these amounts and make sure they are reflected back in the POS (after the Transaction Response is processed), to make sure everything is reconciled correctly.

The only exception to this would be if the POS does not have native support for either surcharge or tipping, in which case the correct action would be to ignore these values from the response. The receipt data will contain the correct charged information, which will be presented to the customer.

Integrating Receipts

Each time the Payment Acceptance Device generates a receipt, the data contained in that receipt will be returned back in the data.Receipt field of the Transaction API Response.

This device-generated receipt data will contain spaces and new line characters (\n) to format it to a fixed-width (this width may vary by device).

For example, taking the receipt data from the example response at the top of this page and breaking the lines where the \n sequence is would result in a receipt looking like this:

         PAYMARK PKMS         
        TEST TERMINAL         
        182 Wairau Rd         

TERMINAL              79707014
TIME             19SEP18 11:55
TRAN 000013             CREDIT
CARD                  ....0138
Visa Debit
RID: A000000003
PIX: 1010
TC : E0567EF3160C55CF
TVR: 08C0048000
TSI: E800
REF NO            000147      
PURCHASE              NZ$ 5.00
SURCHARGE             NZ$ 0.15
TIP                   NZ$ 1.00
TOTAL                 NZ$ 6.15



If a POS application has receipt printing capability, it is important to include this device-generated receipt data in that receipt, as regulation dictates that this information must be presented to the customer.


Many Payment Acceptance Devices will have a built-in receipt printer, however customer receipts are usually turned off in an integrated scenario, where the POS application would normally print a receipt.

Last Updated: 5/9/2019, 6:05:07 PM