Transaction Endpoint

Once a Payment Acceptance Device is paired, the POS can initiate Transactions and poll for a response (or be notified when it happens). As a reminder, SmartConnect will automatically know which device (e.g. which EFTPOS Terminal) to send the Transaction to, given that the POSRegisterID and other parameters (as explained below) are consistent between the Pairing request and the Transaction request.

API Request

The Transaction request is an asynchronous request, i.e. a response containing a reference to the Transaction will come immediately, and the POS is expected to poll for an outcome afterwards. To initiate a Transaction from the POS system, execute the following HTTP request:

POST {environment}/Transaction

The {environment} variable is explained in the Sending API Requests to SmartConnect section.

The content type for the request body needs to be application/x-www-form-urlencoded. The following mandatory parameters need to be always be supplied in the request body:

Parameter Name Example Value Comment Mandatory
POSRegisterID 7444ae07-dc63-e49c-33e3-59a7c108cc80 Unique Register Id Yes
POSBusinessName Toys Shop Store Name Yes
POSVendorName Till2Go POS Software Vendor Yes
TransactionMode ASYNC Indicates asynchronous transaction mode Yes
TransactionType Card.Purchase The desired function to be performed Yes
SaleData Sale (SKU) data No
PosNotificationCallbackUrl https://my-web-service.com/notify To URL to notify once the transaction is complete No

The POSRegisterID, POSBusinessName and POSVendorName parameters need to be identical to the respectful parameters as supplied during the Pairing request.

TransactionMode only supports sending ASYNC as the value, and it indicates that the transaction is performed asynchronously (for backwards-compatibility reasons, we did not make this the default API mode). Omitting this parameter would execute a transaction request in the legacy (synchronous) mode.

Note

Previously, SmartConnect only supported the synchronous Transaction API endpoint, where the response would only come once the Transaction had been completed or otherwise terminated - due to an error or a timeout. This approach, while still supported by the platform (existing integrations can still utilize it), will not be encouraged for new integrations, as the asynchronous API allows for better control and handling of e.g. connection interruptions and other failure scenarios.

Based on the supplied TransactionType parameter, additional parameters may be needed. The supported transaction types are:

Function Name Transaction Type Code
Card Purchase Card.Purchase
Card Refund Card.Refund
QR Purchase QR.Merchant.Purchase (or QR.Consumer.Purchase)
QR Refund QR.Refund
Purchase + Cash Card.PurchasePlusCash
Cash Advance Card.CashAdvance
Authorise Card.Authorise
Finalise Card.Finalise
Logon Acquirer.Logon
Settlement Inquiry Acquirer.Settlement.Inquiry
Settlement Cutover Acquirer.Settlement.Cutover
Reprint Receipt Journal.ReprintReceipt
Get Terminal Status Terminal.GetStatus
Terminal Read Card Terminal.ReadCard

The Supported Transaction Types page contains a full reference (with all additional parameters) for each of these functions.

Note

Some older SmartConnect integrations have implemented the Journal.GetTransResult function in order to receive the result of the last financial transaction from the Payment Acceptance Device. With the asynchronous transaction processing, this function is no longer recommended to be used.

SmartConnect supports sending Sale (SKU) data with any of the transaction types. Even though the API will always accept that data, it might not be meaningful with all of them (e.g. Get Terminal Status or Settlement Inquiry). The parameter is explained in the Sale Data page.

If PosNotificationCallbackUrl is specified, then polling for the outcome is not required, SmartConnect will notify the given URL once the transaction is complete.

API Response

After the transaction request has been sent, a response will be immediately sent (given the request was successful) indicating that the transaction is in progress, and containing the URL to use to poll for the outcome. The HTTP response body will always be a JSON object. An example response will look like this:

{
    "transactionId": "f363c7de-102c-4d80-a902-ed37413ca599",
    "transactionTimeStamp": "201809182353193193",
    "merchantId": "8dac4049-20b3-473f-b3a3-2682667ece33",
    "deviceId": "7070714000",
    "transactionStatus": "PENDING",
    "data": {
        "PosVendor": "Smartpay",
        "PosRegisterID": "9444ae07-dc63-e49c-33e3-59a7c108cc81",
        "PosBusinessName": "John Doe's Coffee Shop",
        "AmountTotal": "500",
        "DeviceID": "7070714000",
        "Function": "Card.Purchase",
        "PollingUrl": "https://api-dev.smart-connect.cloud/pos/transaction/f363c7de-102c-4d80-a902-ed37413ca599?merchantAccessToken=a4934205-e3fa-47ea-88c3-6f6422a0af72"
    },
    "merchantAccessToken": "a4934205-e3fa-47ea-88c3-6f6422a0af72"
}

Notice the value under data.PollingUrl. Executing an HTTP GET command against this URL will poll for the transaction outcome. Polling can be performed any time while the transaction is in progress, or after it has finished, so long as the POS system preserves this URL locally. If there is e.g. a crash in the POS application, the polling URL can be invoked to get the outcome of the transaction that was in progress.

Note

If PosNotificationCallbackUrl has been specified in the request, then polling for the outcome is not required, SmartConnect will notify the given URL once the transaction is complete with the payload from below (refer to the example for a COMPLETED transaction).

Polling For The Outcome

Executing a GET request against the polling URL will return a response like this:

{
    "transactionId": "f363c7de-102c-4d80-a902-ed37413ca599",
    "transactionTimeStamp": "201809182353193193",
    "merchantId": "8dac4049-20b3-473f-b3a3-2682667ece33",
    "deviceId": "7070714000",
    "transactionStatus": "PENDING",
    "data": {
        "PosVendor": "Smartpay",
        "PosRegisterID": "9444ae07-dc63-e49c-33e3-59a7c108cc81",
        "PosBusinessName": "John Doe's Coffee Shop",
        "AmountTotal": "500",
        "DeviceID": "7070714000",
        "Function": "Card.Purchase",
        "Merchant": "1",
        "Company": "Smartpay",
        "RequestId": "f363c7de-102c-4d80-a902-ed37413ca599",
        "TransactionResult": "OK-DELAYED",
        "Result": "DELAYED-TRANSACTION",
        "ResultText": "Transaction takes longer than usual"
    }
}

Note

In the Production Environment polling will be rate-limited to once every 2 seconds. Polling more frequently than this interval may result in a HTTP 429 Too Many Requests response.

As long as the transactionStatus field in the response indicates PENDING, the transaction is still in progress on the Payment Acceptance Device. Once the transaction has been completed (regardless of the outcome, or if it times out), the transactionStatus field will change to COMPLETED, and the transaction outcome will be returned in the HTTP response body.

Notice how, in the example response above, data.TransactionResult says OK-DELAYED and data.Result says DELAYED-TRANSACTION. This will be returned if the transaction is taking longer than expected (>2 minutes, but may depend on a number of factors), and is usually an indication that the Payment Acceptance Device might have gone offline and is unable to upload the result of the transaction, so the POS vendor can choose if they wish to display a visual indication to the user to check their device. This combination of data.TransactionResult and data.Result can only be returned while the transactionStatus is still PENDING.

Completed Transaction

Once a transaction on the Payment Acceptance Device has been fully processed (accepted/declined/cancelled), the polling request will return a COMPLETED transaction response, an example of which is shown 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"
    }
}

The HTTP response body for a transaction will contain a JSON object, which will have the structure as per the table below.

Root Object

Parameter Name Type Comment Presence
transactionId string Unique transaction identifier. Always
transactionTimeStamp string Date and time of the transaction, as generated on the server (UTC time). Always
merchantId string Unique merchant (store) identifier. Always
deviceId string Unique device identifier. Always
transactionStatus string Status of the transaction, one of the following values:
  • PENDING - the result of the transaction is still pending on the Payment Acceptance Device
  • COMPLETED - the transaction is successfully completed on the Payment Acceptance Device
Always
data Data Object Optional

Data Object

Parameter Name Type Comment Presence
TransactionResult string Transaction outcome, one of the following values:
  • OK-ACCEPTED - The transaction was accepted.
  • OK-DECLINED - The transaction was declined.
  • OK-UNAVAILABLE - The transaction could not be processed at this time.
  • OK-DELAYED - The transaction is taking longer than expected to be completed (while the transaction is still pending).
  • CANCELLED - The transaction was cancelled by the operator or customer, or by the Payment Acceptance Device.
  • FAILED - The transaction failed.
  • FAILED-INTERFACE - The transaction failed because of a communications or interface error.
Always
Receipt string Receipt data, as generated by the Payment Acceptance Device. Optional
RequestId string This will be identical to the transactionId field. Optional
AcquirerRef string System trace/audit number. Optional
AccountType string The account type selected on the Payment Acceptance Device, if applicable. Optional
Timestamp string Date and time of the transaction, from the Payment Acceptance Device (local time). Optional
Result string An indication of whether the request was processed by the Payment Acceptance Device, one of the following values:
  • OK - The function was processed successfully.
  • CANCELLED - The function was cancelled.
  • DELAYED-TRANSACTION - The function is taking longer than expected to be completed (while the transaction is still pending).
  • FAILED - The function failed.
  • FAILED-INTERFACE - The function failed because of a communications or interface error.
Always
Function string The Transaction Type invoked. Always
AuthId string For transactions authorised by a third party (e.g. Paymark), this will be the authorisation id. Optional
CardPan string The last four digits of the card used on the Payment Acceptance Device. Optional
AmountTotal string The total amount paid on the Payment Acceptance Device. Optional
Merchant string The merchant Id, as configured on the Payment Acceptance Device. Optional
CardType string The type of card, as returned by the Payment Acceptance Device. Optional
TerminalRef string The Terminal Id, as configured on the EFTPOS Terminal. Optional
AmountSurcharge string The surcharge amount (part of the total amount), if configured and entered on the Payment Acceptance Device. Optional
AmountTip string The tip amount (part of the total amount), if configured and entered on the Payment Acceptance Device. Optional

API Response HTTP Status Codes

The API response will return the following HTTP status codes:

Status Code Description
200 Success
400 Bad Request - most commonly because the device is not paired to a register
429 Too Many Requests - this can happen if polling faster than the 2 second rate limitation

Note

Getting a HTTP 200 status code means that the request was successful and a valid response to that request provided, not necessarily that the Transaction itself was successful (accepted) as well - for example, a declined transaction is also considered a valid response to the request and will return with the status code 200.

See Interpreting the Transaction API Response for details on how to determine the outcome of the Transaction.

In case there is an error, the response body will contain the following content, with the content type application/json:

{
"error": "This register is not paired to a device, please pair it first."
}

The error description will vary for different exception cases.

Last Updated: 5/10/2019, 5:42:59 PM