SmartConnect Integration Guide

for Point-of-Sale Software Vendors

Overview

This guide is intended for Point-of-Sale (POS) Vendors, to integrate their software with the SmartConnect platform, in order to accept payments from any device running a SmartConnect client (including all compatible Smartpay EFTPOS Terminals).

POS Vendors familiar with older Smartpay integration software (i.e. SmartLink Lite) will find the flows with SmartConnect to be slightly different, but the overall integration being much simpler and faster to implement (literally taking two API calls to have a basic integration up and running!).

Note: While this guide outlines the most common way for POS software integrations to be implemented, in some specific circumstances Smartpay development teams can work with the Vendor to accommodate a slightly different flow if needed. For example, if a given cloud-based POS system has its own set of APIs and/or supports plugins or add-ons for payments, Smartpay can collaborate with the Vendor to provide the best possible solution to our mutual customers.

This guide is not intended for Vendors of payment acceptance devices (i.e. EFTPOS Terminals, mobile wallets, etc). SmartConnect has a separate set of APIs to enable these systems to provide payment acceptance to integrated POS systems. This guide is also not intended for Vendors looking for a e-Commerce (online payment gateway) solution. If you fall into either of these categories, please get in touch today to discuss your specific needs with our team.

Table of Contents

What is SmartConnect?

SmartConnect is an efficient, scalable and secure cloud-based API integration platform. It pairs any payment initiation system, running on any device, to any compatible payment acceptance device.

  • The payment initiator can include applications such as cloud/on-premises Point-of-Sale (POS) software, or online e-Commerce platforms. SmartConnect is integrated with a large number of POS systems already, and new integrations are continuously added.
  • It is device agnostic, connecting devices running on PC, Mac, tablet or mobile phones.
  • Payment acceptance (also called payment termination) devices can be traditional EFTPOS devices (such as PAX payment terminals), or mobile applications (mobile wallets), online payment gateways, etc.

The true power of SmartConnect lies in its open API architecture, which enables third parties to integrate and grow the eco-system with ease.

The added value SmartConnect brings is capturing additional (invoicing) data bundled with transaction requests – SKUs, GST, etc. (whatever the POS can provide – can be captured). Together, this enables SmartConnect to do real-time Data Warehousing and expose additional APIs:

  • Data APIs – which are utilized by Smartpay provided portals showing real-time transaction dashboards, but can also be used to build systems for fraud analysis, advanced analytics and business intelligence, piping the data into external custom solutions, etc.
  • e-Invoice APIs – generating invoices either real-time or on-demand, based on the stored SKU, GST and other available data.

Note: Data APIs are out of scope for this guide. Please get in touch if you wish to consume these APIs in your system. The process of bundling sale data with initiated transactions will be described below.

The Integration Process

As explained in the What is SmartConnect section, SmartConnect is a cloud based platform. From the point of view of a POS system – this means that the POS software never communicates with the device directly, it will always send an API request to the cloud API endpoint, which will then forward the request to the right payment acceptance device.

This simplifies the integration process on many levels:

  • There are no dependencies to be installed or managed. Integrating with SmartConnect requires no SDK to be bundled with the POS software, and no drivers or DLLs or applications to be installed on the host machine running the POS software. The entire communication between the POS system and SmartConnect is made using RESTful API calls.
  • There is no need to handle unnecessary exception cases. Developers familiar with integrating to a specfic EFTPOS Terminal directly will know the pain of handling all the possible things that could go wrong – power failure, connectivity loss, etc. This is all handled by the SmartConnect cloud engine and the corresponding SmartConnect client running on the device. As far as the POS software goes – a simple payment request is sent, and it is either successful or not, with the relevant metadata or error information in the response.
  • Simplified network architecture. In order for the SmartConnect integration to work, neither the host machine running the POS software nor the payment acceptance device need to “know” about each other in the local network (i.e. save each others’ IP addresses or have direct ping visibility). In fact, they can be on completely separate networks, which is not an uncommon scenario in many production sites – e.g. a desktop/tablet machine using WiFi and an EFTPOS Terminal using its own mobile connection. This makes configuring the network/firewalls much easier. Both the POS host machine and the payment device need to have Internet access to the SmartConnect host (which should be white-listed in closed networks) using standard ports – the POS host machine needs to use HTTPS (port 443) and the EFTPOS Terminal TCP port 80.

The integration process consists of two steps:

  1. Pairing. Before a transaction can be made, a register need to be paired to a payment acceptance device (typically an EFTPOS Terminal). This way, once a Transaction has been initiated – SmartConnect automatically knows which device to forward the Transaction to. The process is explained in more detail in the Pairing with a Payment Acceptance Device section.
  2. Transactions. Once the register is paired to a payment acceptance device, it can send Transasction requests to request for payments. The API to achieve this is explained in more detail in the Initiating a Transaction section.

The concept of a Register is important here. A Register is defined as a uniquely identifiable entity that can request for payments. Usually this would be a single physical device (desktop/tablet/etc.) used by one or more operators within a Store (as a physical location). Different POS systems have different hierarchies in place (usually along these lines: Company -> Store (Site/Outlet) -> Register), and call it by different names (other commonly used terms would be Location or just POS), but the concept of a Register is always present.

It is important that a Register has a unique identifier (at least for integration purposes), in the entire domain of the POS Vendor. In other words, each Register in every Store across the entire base of merchants/customers the POS Vendor works with – must have its own unique ID. A GUID is a good choice for this ID, although any ID-issuing system the POS Vendor chooses to use will work fine, so long as the uniqueness is guaranteed.

Note: If two Registers share the same ID, this will cause issues with pairing and transacting. If pairing a device to one register causes another to be unpaired, this is the most common root cause.

Sending API Requests to SmartConnect

As mentioned in The Integration Process section, all communication between the POS system and SmartConnect is via RESTful APIs.

POS Developers will interact with SmartConnect using two different environments:

  • Development Environment. The development environment is where all development, testing and certification (with Smartpay) will typically be done. This environment will typically be used with payment acceptance devices (either the Virtual Terminal or test EFTPOS Terminal) that will not accept “real” money. The host under which contains all API endpoints is:

https://api-dev.smart-connect.cloud/POS

  • Production Environment. The production environment is for live merchants to use with live payment acceptance devices (which will take “real” money). No testing should be performed in this environment. The host under which contains all API endpoints is:

https://api.smart-connect.cloud/POS

Using the HTTPS protocol is mandatory (otherwise the API request will fail). The supported request HTTP operations, content type and requested body, for API endpoints, will be listed in the relevant API section below. Parameters (variables) in the request URL will be shown with {} brackets. The host to which to send requests will be shown as the {environment} variable, which can be replaced with either of the environments from above. For example, in order to initiate the pairing process, the documentation below will say to execute the following HTTP request:

PUT {environment}/Pairing/{pairingCode}

This means that in order to execute a Pairing request on the development environment using the code 123456, the actual HTTP request will look like:

PUT https://api-dev.smart-connect.cloud/POS/Pairing/123456

The Pairing API request (including the content type, request body and response) is explained in more detail in the Pairing with a Payment Acceptance Device section.

Note: It is important not to forget to change the API subdomain from api-dev to api prior to deploying the integration to a pilot/production environment. The application must be changed to use the production API endpoint, otherwise the integration cannot be used with a “live” EFTPOS Terminal or other acceptance devices.

Pairing with a Payment Acceptance Device

Pairing a Register to a particular device enables SmartConnect to automatically “know” which device to forward the Transaction requests to. Essentially, the pairing process creates a link between the Register, identified by its unique ID, and the device, identified by a temporary pairing code. The pairing flow is:

  1. The pairing process gets initiated on the device, which will request the temporary pairing code from SmartConnect and display it on the screen. This code has a certain TTL (time-to-live), and may periodically refresh on the device if pairing is not finalized.
  2. The person doing the pairing would input this pairing code in the POS software, and submit it to SmartConnect via the API call.
  3. If successful, the pairing process is now complete and the Register is ready to submit Transactions!

Depending on how each POS system handles integrations, there would typically be a way for setting up each individual integration and this would be the place to have a UI component where the pairing code can be inputted and submitted to SmartConnect. Pairing is commonly a “back-office” function, although some integrations have places the pairing controls on the POS “front-end” as well.

Pairing information is stored in SmartConnect. The POS system does not need to preserve anything – no pairing codes, device IDs, or anything else. After pairing is successful, every Transaction request will be routed to the right device accordingly so long as the Register information (ID and other metadata, explained below) remains the same.

Note: There is no API to unpair, from the POS system. Unpairing is an operation handled by the payment acceptance device. Typically if users need to e.g. move an EFTPOS Terminal from one Register to another, they would initiate the unpairing process on the Terminal directly, then initiate another pairing on the “new” Register.

For Smartpay EFTPOS Terminals, even when doing a physical swap-out of a device (e.g. if it becomes faulty), so long as Smartpay preserves the same internal ID between the old and new device (which is almost always the case), the new device will be automatically paired once switched on.

It is important to understand the cardinality of the relationship between the Register and the payment acceptance device:

  • One Register can only be paired to one payment acceptance device. Sending a pairing request for an already-paired Register to another device (with a new pairing code) will unpair the previously paired device (so long as the new pairing request is successful, i.e. the pairing code valid).
  • One payment acceptance device can be paired to many Registers. Multiple registers (with different unique IDs) can send pairing requests to the same device. Each pairing request will be independent (i.e. a separate API call to the SmartConnect server), and use its own temporary code (i.e. pairing will be initiated multiple times on the same device).

In case there are multiple Registers paired to the same payment acceptance device, payment requests will be queued in the order in which the server receives them. Depending on how the SmartConnect client on the device is implemented – it may offer the possibility to unpair an individual register and/or unpair all paired registers at one. As stated before, the POS software does not have any control over the unpairing process.

Note: Having one Register paired to multiple payment devices is not supported by design. This can, however, be worked around by the POS system having one “physical” Register and multiple “virtual” Registers (each having its own unique ID). Each “virtual” Register would be separately paired to a different device, and the POS would have a selector which “virtual” Register to use when initiating a Transaction. Most cloud-based POS systems can be set up this way, however it is not always convenient/easy to switch between Registers, especially when finishing a transaction on a “secondary” device.

The Pairing API Request/Response

To initiate pairing from the POS system, execute the following HTTP request:

PUT {environment}/Pairing/{pairingCode}

The {environment} variable is explained in the Sending API Requests to SmartConnect section. The {pairingCode} variable is the pairing code inputted by the user doing the pairing operation.

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

Parameter Name Example Value Comment Mandatory
POSRegisterID 7444ae07-dc63-e49c-33e3-59a7c108cc80 Unique Register Id Yes
POSRegisterName Main Register Register Name Yes
POSBusinessName Toys Shop Store Name Yes
POSVendorName Till2Go POS Software Vendor Yes
Contact Name John Doe   No
Address 123 Example Street   No
City Auckland   No
State Auckland   No
ZipCode 1010   No
Email john.doe@toysshop.co.nz   No
Phone 09 1234567   No

The first four parameters are mandatory and (apart from the Register Name) must be identical to the equivalent parameters supplied to a Transaction request. The Register Name parameter will usually be displayed on the payment acceptance device, to easily identify which Register is paired to which device.

Note: If a Store changes its name, it will have to do the pairing operation again.

The demographic/address component of the request is metadata about the contact person and address of the store (physical location where this Register is located), and is optional.

The API response will return the following HTTP status codes:

Status Code Description
200 Success
400 Error while pairing

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

{
  "error": "Invalid Pairing Code. Please make sure you entered the code correctly"
}
      

The error description will vary for different exception cases.

Initiating a Transaction

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 POS Register ID and other parameters (as explained below) are consistent between the Pairing request and the Transaction 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.

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.

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.

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

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

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

Purchase

This function requests the Payment Acceptance Device to initiate a purchase transaction for a specified amount.

Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Card.Purchase, and additional parameters are:

Parameter Name Example Value Comment Mandatory
TransactionType Card.Purchase   Yes
AmountTotal 500 The purchase amount Yes

Note: The amount is provided in cents – so a $5 amount is specified as 500. The amount needs to be a non-zero positive number. The currency is not explicitly specified, and will default to the currency configured on the Payment Acceptance Device.

Refund

This function requests the Payment Acceptance Device to initiate a refund transaction, refunding the previous Card Purchase transaction.

Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Card.Refund, and additional parameters are:

Parameter Name Example Value Comment Mandatory
TransactionType Card.Refund   Yes
AmountTotal 500 The refund amount Yes

Note: The amount is provided in cents – so a $5 amount is specified as 500. The amount needs to be a non-zero positive number (regardless of the fact that this is a refund). The currency is not explicitly specified, and will default to the currency configured on the Payment Acceptance Device.

QR Purchase

SmartConnect supports a generic QR code interface, that can process transactions for a number of different gateways (i.e. WeChat Pay, Alipay, closed loop payment systems, etc).

From the point of view of the POS, this transaction is identical to a Card transaction, but should be requested explicitly and ideally under a separate Payment Type (i.e. have its own “button” in the POS interface), or have another means to track QR purchase totals separately from Card purchase totals, as they will need to be reconcilled differently.

Once a QR transaction is initiated, the Payment Acceptance Device will display a QR code on the screen, and once that code is scanned by a compatible app – SmartConnect will handle all the back-end communication to the appropriate gateway.

The Transaction request will return a structurally identical response to a Card transaction.

SmartConnect supports two different “modes” of QR transaction (and two different transaction types):

  • QR Code displayed on the device – where the consumer scans the QR code with their smartphone app (the transaction type is QR.Merchant.Purchase);
  • QR Code scanning mode – where the consumer will display the QR code to the merchant on their smartphone app, and the merchant will use the payment device to scan this code, or input it manually if there is no scanner available (the transaction type is QR.Consumer.Purchase).

QR.Merchant.Purchase is the preferred mode and this transaction type should always be implemented, whereas the QR.Consumer.Purchase is optional.

Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as QR.Merchant.Purchase (or QR.Consumer.Purchase), and additional parameters are:

Parameter Name Example Value Comment Mandatory
TransactionType QR.Merchant.Purchase   Yes
AmountTotal 500 The purchase amount Yes

Note: The amount is provided in cents – so a $5 amount is specified as 500. The amount needs to be a non-zero positive number. The currency is not explicitly specified, and will default to the currency configured on the Payment Acceptance Device.

QR Refund

This function requests the Payment Acceptance Device to perform a refund transaction, refunding a previous QR transaction.

Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as QR.Refund, and additional parameters are:

Parameter Name Example Value Comment Mandatory
TransactionType QR.Refund   Yes
AmountTotal 500 The refund amount Yes

Note: The amount is provided in cents – so a $5 amount is specified as 500. The amount needs to be a non-zero positive number (regardless of the fact that this is a refund). The currency is not explicitly specified, and will default to the currency configured on the Payment Acceptance Device.

Logon

This function requests the EFTPOS Terminal to perform a logon operation with an acquirer.

Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Acquirer.Logon, and there are no additional parameters.

Purchase + Cash

This function requests the EFTPOS Terminal to initiate a purchase transaction with a cash-out amount.

Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Card.PurchasePlusCash, and additional parameters are:

Parameter Name Example Value Comment Mandatory
TransactionType Card.PurchasePlusCash   Yes
AmountTotal 500 The total amount of the transaction, including the cash-out amount Yes
AmountCash 100 Cash portion of the AmountTotal Yes

Note: The amount is provided in cents – so a $5 amount is specified as 500. The amount needs to be a non-zero positive number. The currency is not explicitly specified, and will to the currency configured on the Payment Acceptance Device.

Cash Advance

This function requests the EFTPOS Terminal to initiate a cash-out only transaction.

Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Card.CashAdvance, and additional parameters are:

Parameter Name Example Value Comment Mandatory
TransactionType Card.CashAdvance   Yes
AmountTotal 500 The cash-out amount Yes

Note: The amount is provided in cents – so a $5 amount is specified as 500. The amount needs to be a non-zero positive number. The currency is not explicitly specified, and will default to the currency configured on the Payment Acceptance Device.

Settlement Inquiry

This function requests the EFTPOS Terminal to perform a settlement inquiry operation with an Acquirer.

Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Acquirer.Settlement.Inquiry, and additional parameters are:

Parameter Name Example Value Comment Mandatory
TransactionType Acquirer.Settlement.Inquiry   Yes
Date 20180413 The inquiry date (YYYYMMDD) No

Settlement Cutover

This function requests the EFTPOS Terminal to perform a settlement cutover operation with an Acquirer.

Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Acquirer.Settlement.Cutover, and there are no additional parameters.

Authorise

This function requests the EFTPOS Terminal to initiate an Authorise transaction, to reserve funds in the cardholder’s account.

Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Card.Authorise, and additional parameters are:

Parameter Name Example Value Comment Mandatory
TransactionType Card.Authorise   Yes
AmountAuth 500 The amount to authorize Yes
TransactionReference AUTH01 Reference string; alphanumeric, up to 8 characters No

The TransactionReference field is used to look up and retrieve the original auth information when finalising. If the TransactionReference matches an existing stored transaction, the EFTPOS Terminal will prompt whether to continue. If YES, the existing auth transaction will be updated; if NO, the transaction will be cancelled. In all cases, the value used for the transaction is returned in the result message (for accepted transactions) and that value must be used when finalizing.

Note: The amount is provided in cents – so a $5 amount is specified as 500. The amount needs to be a non-zero positive number. The currency is not explicitly specified, and will default to the currency configured on the Payment Acceptance Device.

Finalise

This function requests the EFTPOS Terminal to finalise an auth transaction, debiting funds from the cardholder’s account.

Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Card.Finalise, and additional parameters are:

Parameter Name Example Value Comment Mandatory
TransactionType Card.Finalise   Yes
AmountFinal 500 The amount to debit Yes
TransactionReference AUTH01 Reference string; alphanumeric, up to 8 characters Yes

The TransactionReference field needs to match the reference from the Authorise function, either supplied or returned as the result.

Note: The amount is provided in cents – so a $5 amount is specified as 500. The amount needs to be a non-zero positive number. The currency is not explicitly specified, and will default to the currency configured on the Payment Acceptance Device.

Reprint Receipt

This function is used to reprint the receipt of the last financial transaction on the Payment Acceptance Device.

Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Journal.ReprintReceipt, and there are no additional parameters.

Get Terminal Status

This function requests the current status of the EFTPOS Terminal.

Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Terminal.GetStatus, and there are no additional parameters.

Note: Legacy integrations migrating to SmartConnect tend to call this function prior to initiating any other transacting type. This is not an approach we recommend to check whether the terminal is paired or ready to accept other transaction types. If the intent is to submit a Purchase transactions, the recommend approach is to only send one request (for the Purchase transaction) and handle any eventual errors, rather than doing two API calls.

Terminal Read Card

This function reads the card PAN from the EFTPOS Terminal.

Other than the mandatory Transaction request parameters (POSRegisterID, POSBusinessName, POSVendorName and TransactionMode), as explained above, the TransactionType parameter should be specified as Terminal.ReadCard, and there are no additional parameters.

The full card PAN will be in the CardPan field of the response (which normally contains only the last four digits).

Note: this function will only work for epay cards, under a specific BIN range, it cannot be applied to any other type of card – swiping another card on the EFTPOS Terminal will result in an error, and the Transaction Result will be CANCELLED.

Sale Data

SmartConnect supports sending Sale (SKU) data with any transaction type from above (i.e. as part of the request sent to the Transaction end-point).

Sale data is sent as part of the SaleData field in the request body, which will need to be URL-encoded as all other fields.

This is a single text field, and accepts a serialized JSON object, which has the following structure:

Parameter Name Type Comment Mandatory
root object    
→version string The version of this JSON Schema is “1.0.0”, please supply this version in the content. Yes
→saleData object   Yes
    →saleId string Unique sale identifier from the originating application. No
    →invoiceNumber string Invoice number (if available). No
    →createdAt string Date and time the sale was created, in UTC time, formatted according to ISO 8601. No
    →→updatedAt string Date and time the sale was last updated, in UTC time, formatted according to ISO 8601. No
    →totalAmount string Total amount of all the bundled products/services (tax included). Yes
    →totalTax string Total tax (if applicable). Yes
    →totalTips string Total amount of tips (if not entered on the EFTPOS Terminal, if entered on the Terminal they will be part of the response sent back to the POS). No
    →totalSurcharge string Total surcharge amount (if not entered on the EFTPOS Terminal, if entered on the Terminal they will be part of the response sent back to the POS). No
    →returnFor string If this sale is a return (refund) sale, the Id of the originating sale (if available). No
    →userId string The Id of the user creating the sale. No
    →userName string The name of the user creating the sale. No
    →customerId string The Id of the customer (if available). No
    →customerName string The name of the customer. No
    →lineItems object   No
        →lineId string Id of the line (if available), should be unique per sale, does not need to be unique across all sales. No
        →sequenceNumber string The sequence of this line within a sale. No
        →productId string Id of the product, should be unique inside the scope of the originating application. No
        →productName string Name of the product. Yes
        →productDescription string Product description (if available). No
        →categories object   No
            →categoryId string Id of the category the product belongs to (if available), should be unique inside the scope of the originating application. No
            →categoryName string Name of the category. Yes
            →departmentId string Id of the department the category belongs to (if available), should be unique inside the scope of the originating application. No
            →departmentName string Name of the department. No
        →brandId string Id of the brand the product belongs to (if available), should be unique inside the scope of the originating application. No
        →brandName string Name of the brand. No
        →quantity string Quantity of the product. Yes
        →unitPrice string Price of this line item (tax included), per unit. In case of a returned item, should be a negative amount. Yes
        →unitTax string Tax amount applied to this line item (if applicable), per unit. Yes
        →unitDiscount string Discount applied to this line item (if applicable), per unit. No
        →totalPrice string Total price of this line item (tax included). In case of a returned item, should be a negative amount. Yes
        →totalTax string Total tax amount applied to this line item (if applicable). Yes
        →totalDiscount string Total discount applied to this line item (if applicable). No
        →modifierFor string Implicitly defines if this line item is a modifier to another line item, where this Id should match the lineId (or sequenceNumber) of the line item it modifies. No
        →skuCode string The SKU code, if this line item is a product. No
        →barcode string The barcode, if this line item is a product, which can be UPC (GS1) or EAN. No

The JSON schema is as follows:

{
  "version": "1.0.0",
  "saleData":
    {
      "saleId": "string",
      "invoiceNumber": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "totalAmount": "string",
      "totalTax": "string",
      "totalTips": "string",
      "totalSurcharge": "string",
      "returnFor": "string",
      "userId": "string",
      "userName": "string",
      "customerId": "string",
      "customerName": "string",
      "lineItems": [
        {
          "lineId": "string",
          "sequenceNumber": "string",
          "productId": "string",
          "productName": "string",
          "productDescription": "string",
          "categories": [
            {
              "categoryId": "string",
              "categoryName": "string",
              "departmentId": "string",
              "departmentName": "string"
            }
          ],
          "brandId": "string",
          "brandName": "string",
          "quantity": "string",
          "unitPrice": "string",
          "unitTax": "string",
          "unitDiscount": "string",
          "totalPrice": "string",
          "totalTax": "string",
          "totalDiscount": "string",
          "modifierFor": "string",
          "skuCode": "string",
          "barcode": "string"
        }
      ]
    }
}
        


Surcharging/Tipping

Surcharge and tip are generally applied at 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 and host may be $X+Y. Where it is expected that a surcharge and/or tip may apply, it is incumbent on the POS to check for amount fields in the response to determine what the final transaction amount is.

The absence of amount fields in the response is indicative that the processed amount is the same as the requested amount.

Transaction API Response

After the transaction request has been sent, a response will be immediately sent 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": "d56661a7-692a-405a-8f25-5fda47e5b3bc",
    "transactionTimeStamp": "201806010120219729",
    "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": "1",
        "DeviceID": "7070714000",
        "Function": "Card.Purchase",
        "PollingUrl": "https://api-dev.smart-connect.cloud/pos/transaction/d56661a7-692a-405a-8f25-5fda47e5b3bc?merchantAccessToken=95dc7482-d559-4545-bb96-72d8fbbd4459"
    },
    "merchantAccessToken": "95dc7482-d559-4545-bb96-72d8fbbd4459"
}
        

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

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

{
    "transactionId": "f986b7ac-fc2b-483e-8e4d-45d06cdef45d",
    "transactionTimeStamp": "201804160323064066",
    "merchantId": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "deviceId": "5450545600",
    "transactionStatus": "PENDING",
    "data": {
        "Function": "Card.Purchase",
        "Merchant": "1",
        "Company": "Smartpay",
        "RequestId": "f986b7ac-fc2b-483e-8e4d-45d06cdef45d",
        "DeviceID": "5450545600",
        "AmountTotal": "100",
        "TransactionResult": "OK-DELAYED",
        "Result": "DELAYED-TRANSACTION",
        "ResultText": "Transaction takes longer than usual"
    }
}
        

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

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

Parameter Name Type Comment Presence
root object   Always
→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 object   Optional
    →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

An example response of a COMPLETED transaction:

{
  "transactionId": "3ec7084a-296f-4d2e-93bc-53b0860bbc68",
  "transactionTimeStamp": "201702231038363427",
  "merchantId": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "deviceId": "9999999991",
  "transactionStatus": "COMPLETED",
  "data": {
    "TransactionResult": "OK-ACCEPTED",
    "Receipt": "PAYMARK PKMS         \n        TEST TERMINAL         \n        182 Wairau Rd         \n\n*-----------EFTPOS-----------*\nTERMINAL              00906604\nTIME             23FEB17 10:38\nTRAN 000135             CREDIT\nEMV TEST CARD\nCARD                  ....0138\nCONTACTLESS\nVisa Debit\nRID: A000000003\nPIX: 1010\nARQC: CCD5BD398510E46E\nTVR: 0000000000\nATC: 0322\nTSI: 0000\nAUTH 123456\nREF NO            000144      \nPURCHASE              NZ$ 5.00\nTOTAL                 NZ$ 5.00\n\n           ACCEPTED           \n******DUPLICATE  RECEIPT******\n*----------------------------*",
    "RequestId": "3ec7084a-296f-4d2e-93bc-53b0860bbc68",
    "AcquirerRef": "000135",
    "AccountType": "CREDIT",
    "Timestamp": "20170223103846",
    "Result": "OK",
    "Function": "Card.Purchase",
    "AuthId": "123456",
    "CardPan": "....0138",
    "AmountTotal": "500",
    "Merchant": "1",
    "CardType": "EMV TEST CARD",
    "TerminalRef": "00906604",
    "PosData": "Pos data"
  }
}
        


Last Updated: July 1, 2018.