Fusion Cloud

The Fusion Cloud API allows the Sale System to communicate with a POI terminal via a Websocket connected to the DataMesh Unify switch.

Reference code

Development Language	Description	Location
.Net	.Net NuGet package	on Nuget
	Source Code	on GitHub
	Demo Application implementing the sdk	on GitHub
Java	Source Code	on GitHub
	Library	on Maven Central
	Demo Application implementing the sdk	on GitHub
	Android Demo Application implementing the sdk	on GitHub
Swift Framework (for iOS)	Source Code	on GitHub
	Demo Application implementing the sdk	on GitHub
FusionCloudIOS cocoapod (for iOS)	Source Code	on GitHub
	Demo included in the pod Example

Security requirements

Unify utilises secure websockets for communication between Sale System and POI Server.

The Sale System and merchant environment must support outgoing TCP connections to *.datameshgroup.io:443, *.datameshgroup.io:4000, and *.datameshgroup.io:5000 for both the terminal and Sale System
As a cloud service, Unify may run on several IP addresses.
- The Sale System must always use the DNS endpoints provided by DataMesh and never limit connectivity to a specific IP address
The Sale System websocket connection must use TLS v1.2 or v1.3 with the SNI extension and one of the following ciphers:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (TLS v1.2)
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (TLS v1.2)
- TLS_AES_128_GCM_SHA256 (TLS v1.3)
- TLS_CHACHA20_POLY1305_SHA256 (TLS v1.3)
- TLS_AES_256_GCM_SHA384 (TLS v1.3)
The Sale System must ensure the connection to Unify is trusted by validating the server-side certificate chain
- Unify utilises standard, public Root CA
- Contact integrations@datameshgroup.com for alternative connection methods if required
- If certificate validation fails the Sale System must display an error and drop the connection.
The Sale System must resolve the DNS address before each connection attempt, and never hard code IP addresses
The Sale System should manage SSL certificate revocation lists and ensure OS security updates are applied
The Sale System should store the SaleID, POIID, and KEK in a secure location. These values are used to identify the Sale System and authenticate the SecurityTrailer

tip

Over time, Data Mesh may require the Sale System to update the TLS requirements provided above if a security risk is identified. In this situation DataMesh will provide the new requirements and allow a reasonable amount of time to allow the Sale System to meet the new requirements.

Endpoints

Production environment

wss://nexo.datameshgroup.io:5000

Test environment

wss://www.cloudposintegration.io/nexouat1

Message format

SaleToPOIRequest

{
  "SaleToPOIRequest": {
    "MessageHeader":{...},
    "PaymentRequest":{...},
    "SecurityTrailer":{...}
  }
}

SaleToPOIResponse

{
  "SaleToPOIResponse": {
    "MessageHeader":{...},
    "PaymentResponse":{...},
    "SecurityTrailer":{...}
  }
}

All messages use JSON format with UTF-8 encoding.

Supported primitive data elements are:

String text string of variable length
Boolean true or false
Number defined in this document as either integer or decimal. For all number fields the Sale System MUST remove the digits equal to zero on left and the right of the value and any useless decimal point (eg. 00320.00 is expressed 320, and 56.10 is expressed 56.1). This simplifies parsing and MAC calculations.
Null optional types can be represented as null

tip

Additional fields will be added to the message specification over time. To ensure forwards compatibility the Sale System must ignore when extra objects and fields are present in response messages.

The base of every message is the SaleToPOIRequest object for requests, and SaleToPOIResponse object for responses.

The SaleToPOIRequest and SaleToPOIResponse contain three objects:

A MessageHeader object.
A Payload object of variable types.
A SecurityTrailer object.

MessageHeader

"MessageHeader":{
  "ProtocolVersion":"3.1-dmg",
  "MessageClass":"",
  "MessageCategory":"",
  "MessageType":"",
  "ServiceID":"",
  "SaleID":"",
  "POIID":""
}

A MessageHeader is included with each request and response. It defines the protocol, message type, sale and POI id.

Attributes	Requ.	Format	Description
ProtocolVersion	✔	String	Version of the Sale to POI protocol specifications. Set to "3.1-dmg". Present when `MessageCategory` is "Login" otherwise absent.
MessageClass	✔	String	Informs the receiver of the class of message. Possible values are "Service", "Device", or "Event"
MessageCategory	✔	String	Indicates the category of message. Possible values are "CardAcquisition", "Display", "Login", "Logout", "Payment"
MessageType	✔	String	Type of message. Possible values are "Request", "Response", or "Notification"
ServiceID	✔	String	A unique value which will be mirrored in the response. See ServiceID.
SaleID	✔	String	Uniquely identifies the Sale System. The SaleID is provided by DataMesh, and must match the SaleID configured in Unify.
POIID	✔	String	Uniquely identifies the POI Terminal. The POIID is provided by DataMesh, and must match the POIID configured in Unify. For Sale Systems that do not need a POI Terminal, the value must be "POI Server"
			Only in the Login request after a successful QR POS Pairing, this field will contain the PairingPOIID value from the pairing QR code data

Payload

An object which defines fields for the request/response. The object name depends on the MessageCategory defined in the MessageHeader

e.g. a login will include LoginRequest/LoginResponse, and a payment will include a PaymentRequest/PaymentResponse.

The Cloud API Reference outlines the expected payload for each supported request.

SecurityTrailer

"SecurityTrailer":{
  "ContentType":"id-ctauthData",
  "AuthenticatedData":{
   "Version":"v0",
 "Recipient":{
   "KEK":{
  "Version":"v4",
  "KEKIdentifier":{
    "KeyIdentifier":"SpecV2TestMACKey",
    "KeyVersion":"20191122164326.594"
  },
  "KeyEncryptionAlgorithm":{
    "Algorithm":"des-ede3-cbc"
  },
  "EncryptedKey":"834EAB305DD18724B9ADF361FC698CE0"
   },
   "MACAlgorithm":{
  "Algorithm":"id-retail-cbc-mac-sha-256"
   },
   "EncapsulatedContent":{
  "ContentType":"iddata"
   },
   "MAC":"C5142F4DB828AA1C"
 }
  }
}

A SecurityTrailer object is included with each request and response.

Unify authenticates requests from the Sale System by examining the SecurityTrailer, along with the SaleID, POIID, and CertificationCode

Session Keys are used to generate/verify a Message Authentication Code (MAC) to prove the authenticity of transactions. They are also used to protect Sensitive Card Data if sent from the Sale System. Session keys must change for every message.

SecurityTrailer

Attribute	Requ.	Format	Description
ContentType	✔	String	Set to "id-ctauthData"
AuthenticatedData	✔	Object
Version	✔	String	Set to "v0"
Recipient	✔	Object
KEK	✔	Object
Version	✔	String	Set to "v4"
KEKIdentifier	✔	Object
KeyIdentifier	✔	String	"SpecV2TestMACKey" for test environment, and "SpecV2ProdMACKey" for production
KeyVersion	✔	String	An incrementing value. Either a counter or date formatted as YYYYMMDDHHmmss.mmm. See KeyVersion
KeyEncryptionAlgorithm	✔	Object
Algorithm	✔	String	Set to "des-ede3-cbc".
EncryptedKey	✔	String	A double length 3DES key. See EncryptedKey
MACAlgorithm	✔	Object
Algorithm	✔	String	Set to "id-retail-cbc-mac-sha-256"
EncapsulatedContent	✔	Object
ContentType	✔	String	Set to "iddata"
MAC	✔	String	MAC of message content. See MAC

info

For brevity the SecurityTrailer has been excluded from examples.

Perform a purchase

To perform a purchase the Sale System will need to implement requests, and handle responses outlined in the payment lifecycle.

If a login hasn't already been sent for the session, send a login request as detailed in login request
- Ensure "PrinterReceipt" is included in SaleTerminalData.SaleCapabilities if payment receipts are to be redirected to the Sale System
Await the a login response and
- Ensure the ServiceID in the result matches the request
- Record the POISerialNumber to be sent in subsequent login requests
Send a payment request, including all required fields, as detailed in payment request
- Set PaymentData.PaymentType to "Normal"
- Set the purchase amount in PaymentTransaction.AmountsReq.RequestedAmount
- Set SaleTransactionID to a unique value for the sale on this Sale System
- Populate the SaleItem array with the product basket for the transaction
If configured in SaleTerminalData.SaleCapabilities, handle any display, print, and input events the POI System sends
- The expected user interface handling is outlined in user interface
- The expected payment receipt handling is outlined in receipt printing
Await the payment response
- Ensure the ServiceID in the result matches the request
- Check Response.Result for the transaction result
- If Response.Result is "Success", record the following to enable future matched refunds: SaleID, POIID, and POITransactionID
- Check PaymentResult.AmountsResp.AuthorizedAmount (it may not equal the RequestedAmount in the payment request)
- If the Sale System is handling tipping or surcharge, check the PaymentResult.AmountsResp.TipAmount, and PaymentResult.AmountsResp.SurchargeAmount
- Print the receipt contained in PaymentReceipt
Implement error handling outlined in error handling

Perform a refund

To perform a refund the Sale System will need to implement requests, and handle responses outlined in the payment lifecycle.

If refunding a previous purchase, the Sale System should include details of the original purchase.

If a login hasn't already been sent for the session, send a login request as detailed in login request
- Ensure "PrinterReceipt" is included in SaleTerminalData.SaleCapabilities if payment receipts are to be redirected to the Sale System
Await the a login response and
- Ensure the ServiceID in the result matches the request
- Record the POISerialNumber to be sent in subsequent login requests
Send a payment request, including all required fields, as detailed in payment request
- Set PaymentData.PaymentType to "Refund"
- Set the refund amount in PaymentTransaction.AmountsReq.RequestedAmount
- Set SaleTransactionID to a unique value for the sale on this Sale System
- If refunding a previous purchase, set the following fields in PaymentTransaction.OriginalPOITransaction
  - Set SaleID to the SaleID of the original purchase payment request
  - Set POIID to the POIID of the original purchase payment request
  - Set POITransactionID to the value returned in POIData.POITransactionID of the original purchase payment response
  - The product basket is not required for refunds
If configured in SaleTerminalData.SaleCapabilities, handle any display, print, and input events the POI System sends
- The expected user interface handling is outlined in user interface
- The expected payment receipt handling is outlined in receipt printing
Await the payment response
- Ensure the ServiceID in the result matches the request
- Check Response.Result for the transaction result
- Check PaymentResult.AmountsResp.AuthorizedAmount (it may not equal the RequestedAmount in the payment request)
- Print the receipt contained in PaymentReceipt
Implement error handling outlined in error handling

Sample code for Performing a Purchase or Refund

Please refer to the methods in the files listed below to view sample code handling on how to perform a payment/refund.

Development Language	Method Name	GitHub File	GitHub Repository
C# .Net	DoPayment	MainWindow.xaml.cs	sdk-dotnet-testpos
Java	doPayment	FusionClientDemo.java	fusioncloud-sdk-java-demo
Swift	doPayment	ViewController.swift	fusioncloud-sdk-ios-demo

Methods

The Sale System sends a NEXO Login request when it is ready to pair with a POI terminal and before any Reconciliation Request. The Sale System can pair with multiple POI terminals by sending another NEXO Login request.

{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "ProtocolVersion":"3.1-dmg",
         "MessageClass":"Service",
         "MessageCategory":"Login",
         "MessageType":"Request",
         "ServiceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "LoginRequest":{
         "DateTime":"xxx",
         "SaleSoftware":{
            "ProviderIdentification":"xxx",
            "ApplicationName":"xxx",
            "SoftwareVersion":"xxx",
            "CertificationCode":"xxx"
         },
         "SaleTerminalData":{
            "TerminalEnvironment":"xxx",
            "SaleCapabilities":[
               "xxx",
               "xxx",
               "xxx"
            ],
            "TotalsGroupID":"xxx"
         },
         "OperatorLanguage":"en",
         "OperatorID":"xxx",
         "ShiftNumber":"xxx",
         "POISerialNumber":"xxx",
         "Pairing": "true or false"
      },
      "SecurityTrailer":{...}
   }
}

MessageHeader

Attributes	Requ.	Format	Description
ProtocolVersion	✔	String	"3.1-dmg"
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"Login"
MessageType	✔	String	"Request"
ServiceID	✔	String	A unique value which will be mirrored in the response. See ServiceID.
SaleID	✔	String	Uniquely identifies the Sale System
POIID	✔	String	Uniquely identifies the POI Terminal
			Only in the Login request after a successful QR POS Pairing, this field will contain the PairingPOIID value from the pairing QR code data

LoginRequest

Attributes	Requ.	Format	Description
DateTime	✔	String	Current Sale System time, formatted as ISO8601 DateTime. e.g. "2019-09-02T09:13:51.0+01:00"
SaleSoftware	✔	Object	Object containing Sale System identification
ProviderIdentification	✔	String	The name of the company supplying the Sale System. Provided by DataMesh.
ApplicationName	✔	String	The name of the Sale System application. Provided by DataMesh.
SoftwareVersion	✔	String	The software version of the Sale System. Must be the software version of the current build.
CertificationCode	✔	String	Certification code for this Sale System. Provided by DataMesh.
SaleTerminalData	✔	Object	Object containing Sale System configuration
TerminalEnvironment	✔	String	"Attended", "SemiAttended", or "Unattended"
SaleCapabilities	✔	Array	Advises the POI System of the Sale System capabilities. See SaleCapabilities
TotalsGroupId		String	Groups transactions in a login session
OperatorLanguage		String	Operator language. Set to 'en'
OperatorId		String	Groups transactions under this operator id
ShiftNumber		String	Groups transactions under this shift number
POISerialNumber		String	The POISerialNumber from the last login response, or absent if this is the first login
Pairing		Boolean	True if the POI ID in the MessageHeader is the PairingPOIID value from the pairing QR code data for the QR POS Pairing

{
   "SaleToPOIResponse":{
      "MessageHeader":{
         "ProtocolVersion":"3.1-dmg",
         "MessageClass":"Service",
         "MessageCategory":"Login",
         "MessageType":"Response",
         "ServiceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "LoginResponse":{
         "Response":{
            "Result":"xxx",
            "ErrorCondition":"xxx",
            "AdditionalResponse":"xxx"
         },
         "POISystemData":{
            "DateTime":"xxx",
            "POISoftware":{
               "ProviderIdentification":"xxx",
               "ApplicationName":"xxx",
               "SoftwareVersion":"xxx"
            },
            "POITerminalData":{
               "TerminalEnvironment":"xxx",
               "POICapabilities":[
                  "xxx",
                  "xxx",
                  "xxx"
               ],
               "POIProfile":{
                  "GenericProfile":"Custom"
               },
               "POISerialNumber":"xxx"
            },
            "POIStatus":{
               "GlobalStatus":"xxx",
               "PEDOKFlag":"true or false",
               "CardReaderOKFlag":"true or false",
               "PrinterStatus":"xxx",
               "CommunicationOKFlag":"true or false",
               "FraudPreventionFlag":"true or false"
            },
            "TokenRequestStatus":"true or false"
         }
      },
      "SecurityTrailer":{...}
   }
}

MessageHeader

Attributes	Requ.	Format	Description
ProtocolVersion	✔	String	"3.1-dmg"
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"Login"
MessageType	✔	String	"Response"
ServiceID	✔	String	Mirrored from the request
SaleID	✔	String	Mirrored from the request
POIID	✔	String	Mirrored from the request

LoginResponse

Attributes	Requ.	Format	Description
Response	✔	Object	Object indicating the result of the login
Result	✔	String	Indicates the result of the response. Possible values are "Success" and "Failure"
ErrorCondition		String	Indicates the reason an error occurred. Only present when `Result` is "Failure". See ErrorCondition for more information on possible values.
AdditionalResponse		String	Provides additional error information. Only present when `Result` is "Failure". See AdditionalResponse for more information on possible values.
POISystemData		Object	Only present when `Result` is "Success"
DateTime	✔	String	Time on the POI System, formatted as ISO8601 DateTime. e.g. "2019-09-02T09:13:51.0+01:00"
TokenRequestStatus	✔	Boolean	True if POI tokenisation of PANs is available and usable
POITerminalData	✔	Object	Object representing the POI Terminal
TerminalEnvironment	✔	String	Mirrored from the request
POICapabilities	✔	Array	An array of strings which reflect the hardware capabilities of the POI Terminal. "MagStripe", "ICC", and "EMVContactless"
GenericProfile	✔	String	Set to "Custom"
POISerialNumber	✔	String	If POIID is "POI Server", then a virtual POI Terminal Serial Number. Otherwise the serial number of the POI Terminal
POIStatus	✔	String	Object representing the current status of the POI Terminal
GlobalStatus	✔	String	The current status of the POI Terminal. "OK" when the terminal is available. "Maintenance" if unavailable due to maintenance processing. "Unreachable" if unreachable or not responding
SecurityOKFlag	✔	Boolean	True if the security module is present
PEDOKFlag	✔	Boolean	True if PED is available and usable for PIN entry
CardReaderOKFlag	✔	Boolean	True if card reader is available and usable
PrinterStatus	✔	String	Indicates terminal printer status. Possible values are "OK", "PaperLow", "NoPaper", "PaperJam", "OutOfOrder"
CommunicationOKFlag	✔	Boolean	True if terminal's communication is available and usable
FraudPreventionFlag	✔	Boolean	True if the POI detects possible fraud

Logout

Logging out is optional.

If sent, it tells the POI system that it won’t send new transactions to the POI Terminal and unpairs the Sale Terminal from the POI Terminal. Any further transactions to that POI Terminal will be rejected by the POI System until the next Login.

The Sale System may send multiple Login requests without a Logout request.

Logout request

{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "MessageClass":"Service",
         "MessageCategory":"Logout",
         "MessageType":"Request",
         "ServiceID":"xxxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "LogoutRequest":{
         "MaintenanceAllowed":"true or false"
      },
      "SecurityTrailer":{...}
   }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"Logout"
MessageType	✔	String	"Request"
ServiceID	✔	String	A unique value which will be mirrored in the response. See ServiceID.
SaleID	✔	String	Uniquely identifies the Sale System
POIID	✔	String	Uniquely identifies the POI Terminal

LogoutRequest

Attributes	Requ.	Format	Description
MaintenanceAllowed		Boolean	Indicates if the POI Terminal can enter maintenance mode. Default to true if not present.

Logout response

{
   "SaleToPOIResponse":{
      "MessageHeader":{
         "MessageClass":"Service",
         "MessageCategory":"Logout",
         "MessageType":"Response",
         "ServiceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "LogoutResponse":{
         "Response":"xxx",
         "ErrorCondition":"xxx",
         "AdditionalResponse":"xxx xxxx xxxx xxxx xxxx"
      },
      "SecurityTrailer":{...}
   }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"Logout"
MessageType	✔	String	"Response"
ServiceID	✔	String	A unique value which will be mirrored in the response. See ServiceID.
SaleID	✔	String	Uniquely identifies the Sale System
POIID	✔	String	Uniquely identifies the POI Terminal

LogoutResponse

Attributes	Requ.	Format	Description
Response	✔	Object	Object which represents the result of the response
Result	✔	String	Indicates the result of the response. Possible values are "Success" and "Failure"
ErrorCondition		String	Indicates the reason an error occurred. Only present when result is "Failure". Possible values are "MessageFormat", "Busy", "DeviceOut", "UnavailableService" and others. Note the Sale System should handle error conditions outside the ones documented in this specification.
AdditionalResponse		String	Provides additional error information. Only present when result is "Failure". See AdditionalResponse for more information of possible values.

Payment

The payment message is used to perform purchase, purchase + cash out, cash out only, and refund requests.

Payment request

{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "MessageClass":"Service",
         "MessageCategory":"Payment",
         "MessageType":"Request",
         "ServiceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "PaymentRequest":{
         "SaleData":{
            "OperatorID":"xxx",
            "OperatorLanguage":"en",
            "ShiftNumber":"xxx",
            "SaleTransactionID":{
               "TransactionID":"xxx",
               "TimeStamp":"xxx"
            },
            "SaleReferenceID":"xxx",
            "SaleTerminalData":{
               "TerminalEnvironment":"xxx",
               "SaleCapabilities":[
                  "xxx",
                  "xxx",
                  "xxx"
               ],
               "TotalsGroupID":"xxx"
            },
            "TokenRequestedType":"Customer | Transaction"
         },
         "PaymentTransaction":{
            "AmountsReq":{
               "Currency":"AUD",
               "RequestedAmount":"x.xx",
               "CashBackAmount":"x.xx",
               "TipAmount":"x.xx",
               "PaidAmount":"x.xx",
               "MaximumCashBackAmount":"x.xx",
               "MinimumSplitAmount":"x.xx"
            },
            "OriginalPOITransaction":{
               "SaleID":"xxx",
               "POIID":"xxx",
               "POITransactionID":{
                  "TransactionID":"xxx",
                  "TimeStamp":"xxx"
               },
               "ReuseCardDataFlag":true,
               "ApprovalCode":"xxx",
               "LastTransactionFlag":true
            },
            "TransactionConditions":{
               "AllowedPaymentBrand":[
                  "xxx",
                  "xxx",
                  "xxx"
               ],
               "AcquirerID":[
                  "xxx",
                  "xxx",
                  "xxx"
               ],
               "DebitPreferredFlag":true,
               "ForceOnlineFlag":true,
               "MerchantCategoryCode":"xxx"
            },
            "SaleItem":[
               {
                  "ItemID":"xxx",
                  "ProductCode":"xxx",
                  "EanUpc":"xxx",
                  "UnitOfMeasure":"xxx",
                  "Quantity":"xx.x",
                  "UnitPrice":"xx.x",
                  "ItemAmount":"xx.x",
                  "TaxCode":"xxx",
                  "SaleChannel":"xxx",
                  "ProductLabel":"xxx",
                  "AdditionalProductInfo":"xxx",
				  "CostBase":"xxx",
				  "Discount":"xxx",
				  "Categories":["xxx","xxx"],
				  "Brand":"xxx",
				  "QuantityInStock":"xxx",
				  "Tags":["xxx","xxx","xxx"]
                  "PageURL":"xxx",
                  "ImageURLs":["xxx","xxx"],
                  "Size":"xxx",
                  "Colour":"xxx",
                  "Weight":xx.xx,
                  "WeightUnitOfMeasure":"xxx"				  
               }
            ]
         },
         "PaymentData":{
            "PaymentType":"xxx",
            "PaymentInstrumentData":{
               "PaymentInstrumentType":"xxx",
               "CardData":{
                  "EntryMode":"xxx",
                  "ProtectedCardData":{
                     "ContentType":"id-envelopedData",
                     "EnvelopedData":{
                        "Version":"v0",
                        "Recipient":{
                           "KEK":{
                              "Version":"v4",
                              "KEKIdentifier":{
                                 "KeyIdentifier":"xxxDATKey",
                                 "KeyVersion":"xxx"
                              },
                              "KeyEncryptionAlgorithm":{
                                 "Algorithm":"des-ede3-cbc"
                              },
                              "EncryptedKey":"xxx"
                           }
                        },
                        "EncryptedContent":{
                           "ContentType":"id-data",
                           "ContentEncryptionAlgorithm":{
                              "Algorithm":"des-ede3-cbc",
                              "Parameter":{
                                 "InitialisationVector":"xxx"
                              }
                           },
                           "EncryptedData":"xxx"
                        }
                     }
                  },
                  "SensitiveCardData":{
                     "PAN":"xxx",
                     "ExpiryDate":"xxx",
                     "CCV":"xxx"
                  },
                  "PaymentToken":{
                     "TokenRequestedType":"xxx",
                     "TokenValue":"xxx"
                  }
               }
            }
         },
         "CustomFields": [
            {
               "Key": "xxx",
               "Type": "xxx",
               "Value": "xxx"
            }
         ]
      },
      "SecurityTrailer":{...}
   }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"Payment"
MessageType	✔	String	"Request"
ServiceID	✔	String	A unique value which will be mirrored in the response. See ServiceID.
SaleID	✔	String	Uniquely identifies the Sale System
POIID	✔	String	Uniquely identifies the POI Terminal

PaymentRequest

Attributes	Requ.	Format	Description
SaleData	✔	Object	Sale System information attached to this payment
OperatorID		String	Only required if different from Login Request
OperatorLanguage		String	Set to "en"
ShiftNumber		String	Only required if different from Login Request
SaleReferenceID		String	Mandatory for pre-authorisation and completion, otherwise optional. See SaleReferenceID
TokenRequestedType		String	If present, indicates which type of token should be created for this payment. See TokenRequestedType
SaleTransactionID	✔	Object
TransactionID	✔	String	Unique reference for this sale ticket. Not necessarily unique per payment request; for example a sale with split payments will have a number of payments with the same TransactionID
TimeStamp	✔	String	Time of initiating the payment request on the POI System, formatted as ISO8601 DateTime. e.g. "2019-09-02T09:13:51.0+01:00"
SaleTerminalData		Object	Define Sale System configuration. Only include if elements within have different values to those in Login Request
TerminalEnvironment		String	"Attended", "SemiAttended", or "Unattended"
SaleCapabilities		Array	Advises the POI System of the Sale System capabilities. See SaleCapabilities
TotalsGroupId		String	Groups transactions in a login session
PaymentTransaction	✔	Object
AmountsReq	✔	Object	Object which contains the various components which make up the payment amount
Currency	✔	String	Three character currency code. Set to "AUD"
RequestedAmount	✔	Decimal	The requested amount for the transaction sale items, including cash back and tip requested
CashBackAmount		Decimal	The Cash back amount. Only if cash back is included in the transaction by the Sale System
TipAmount		Decimal	The Tip amount. Only if tip is included in the transaction. Setting TipAmount to 0 will display the Tip Entry screen in the POI Terminal. Do not set TipAmount to 0 if you don't want the Tip Entry screen to be displayed in the POI terminal.
PaidAmount		Decimal	Sum of the amount of sale items – `RequestedAmount`. Present only if an amount has already been paid in the case of a split payment.
MaximumCashBackAmount		Decimal	Available if `CashBackAmount` is not present. If present, the POI Terminal prompts for the cash back amount up to a maximum of `MaximumCashBackAmount`
MinimumSplitAmount		Decimal	Present only if the POI Terminal can process an amount less than the `RequestedAmount` as a split amount. Limits the minimum split amount allowed.
OriginalPOITransaction		Object	Identifies a previous POI transaction. Mandatory for Refund and Completion. See OriginalPOITransaction
SaleID	✔	String	SaleID which performed the original transaction
POIID	✔	String	POIID which performed the original transaction
POITransactionID	✔	Object
TransactionID	✔	String	`TransactionID` from the original transaction
TimeStamp	✔	String	`TimeStamp` from the original transaction
ReuseCardDataFlag		Boolean	If 'true' the POI Terminal will retrieve the card data from file based on the `PaymentToken` included in the request. Otherwise the POI Terminal will read the same card again.
ApprovalCode		String	Present if a referral code is obtained from an Acquirer
LastTransactionFlag	✔	Boolean	Set to true to process the Last Transaction with a referral code
TransactionConditions		Object	Optional transaction configuration. Present only if any of the JSON elements within are present.
AllowedPaymentBrand		Array	Restricts the request to specified card brands. See AllowedPaymentBrand
AcquirerID		Array	Used to restrict the payment to specified acquirers. See AcquirerID
DebitPreferredFlag		Boolean	If present, debit processing is preferred to credit processing.
ForceOnlineFlag		Boolean	If 'true' the transaction will only be processed in online mode, and will fail if there is no response from the Acquirer.
MerchantCategoryCode		String	If present, overrides the MCC used for processing the transaction if allowed. Refer to ISO 18245 for available codes.
SaleItem	✔	Array	Array of SaleItem objects which represent the product basket attached to this transaction. See SaleItem for examples.
ItemID	✔	Integer	A unique identifier for the sale item within the context of this payment. e.g. a 0..n integer which increments by one for each sale item.
ProductCode	✔	String	A unique identifier for the product within the merchant, such as the SKU. For example if two customers purchase the same product at two different stores owned by the merchant, both purchases should contain the same `ProductCode`.
EanUpc		String	A standard unique identifier for the product. Either the UPC, EAN, or ISBN. Required for products with a UPC, EAN, or ISBN
UnitOfMeasure	✔	String	Unit of measure of the `Quantity`. If this item has no unit of measure, set to "Other"
Quantity	✔	Decimal	Sale item quantity based on `UnitOfMeasure`.
UnitPrice	✔	Decimal	Price per sale item unit. Present if `Quantity` is included.
ItemAmount	✔	Decimal	Total amount of the sale item
TaxCode		String	Type of tax associated with the sale item. Default = "GST"
SaleChannel		String	Commercial or distribution channel of the sale item. Default = "Unknown"
ProductLabel	✔	String	a short, human readable, descriptive name of the product. For example, `ProductLabel` could contain the product name typically printed on the customer receipt.
AdditionalProductInfo		String	Additional information, or more detailed description of the product item.
ParentItemID		Integer	Required if this item is a 'modifier' or sub-item. Contains the ItemID of the parent `SaleItem`
CostBase		Decimal	Cost of the product to the merchant per unit
Discount		Decimal	If applied, the amount this sale item was discounted by
Categories		Array	Array of categories. Top level "main" category at categories[0]. See Categories for more information.
Brand		String	Brand name - typically visible on the product packaging or label
QuantityInStock		Decimal	Remaining number of this item in stock in same unit of measure as `Quantity`
Tags		Array	String array with descriptive tags for the product
Restricted		Boolean	`true` if this is a restricted item, `false` otherwise. Defaults to `false` when field is null.
PageURL		String	URL link to the sale items product page
ImageURLs		Array	String array of images URLs for this sale item
Style		String	Style of the sale item
Size		String	Size of the sale item
Colour		String	Colour of the sale item
Weight		Decimal	Sale item weight, based on `WeightUnitOfMeasure`
WeightUnitOfMeasure		String	Unit of measure of the `Weight`.
PaymentData	✔	Object	Object representing the payment method. Present only if any of the JSON elements within are present.
PaymentType	✔	String	Defaults to "Normal". Indicates the type of payment to process. "Normal", "Refund", or "CashAdvance". See PaymentType
PaymentInstrumentData		Object	Object with represents card details for token or manually enter card details. See for object structure.
CustomFields		Array	Array of key/type/value objects containing additional payment information

Payment response

{
   "SaleToPOIResponse":{
      "MessageHeader":{
         "MessageClass":"Service",
         "MessageCategory":"Payment",
         "MessageType":"Response",
         "ServiceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "PaymentResponse":{
         "Response":{
            "Result":"Success| Partial | Failure",
            "ErrorCondition":"xxx",
            "AdditionalResponse":"xxx"
         },
         "SaleData":{
            "SaleTransactionID":{
               "TransactionID":"xxx",
               "TimeStamp":"xxx"
            },
            "SaleReferenceID":"xxxx"
         },
         "POIData":{
            "POITransactionID":{
               "TransactionID":"xxx",
               "TimeStamp":"xxx"
            },
            "POIReconciliationID":"xxx"
         },
         "PaymentResult":{
            "PaymentType":"xxx",
            "PaymentInstrumentData":{
               "PaymentInstrumentType":"xxx",
               "CardData":{
                  "EntryMode":"xxx",
                  "PaymentBrand":"xxx",
                  "PaymentBrandID":"xxx",
                  "PaymentBrandLabel":"xxx",
				  "Account":"xxx",
                  "MaskedPAN":"xxxxxx…xxxx",
                  "PaymentToken":{
                     "TokenRequestedType":"xxx",
                     "TokenValue":"xxx",
                     "ExpiryDateTime":"xxx"
                  }
               }
            },
            "AmountsResp":{
               "Currency":"AUD",
               "AuthorizedAmount":"x.xx",
               "TotalFeesAmount":"x.xx",
               "CashBackAmount":"x.xx",
               "TipAmount":"x.xx",
			   "SurchargeAmount":"x.xx"
            },
            "OnlineFlag":true,
            "PaymentAcquirerData":{
               "AcquirerID":"xxx",
               "MerchantID":"xxx",
               "AcquirerPOIID":"xxx",
               "AcquirerTransactionID":{
                  "TransactionID":"xxx",
                  "TimeStamp":"xxx"
               },
               "ApprovalCode":"xxx",
               "ResponseCode":"xxx",
               "HostReconciliationID":"xxx"
            }
         },
         "AllowedProductCodes":[
            "1",
            "2",
            "3"
         ],
         "PaymentReceipt":[
            {
               "DocumentQualifier":"xxx",
               "RequiredSignatureFlag":true,
               "OutputContent":{
                  "OutputFormat":"XHTML",
                  "OutputXHTML":"xxx"
               }
            }
         ]
      },
      "SecurityTrailer":{...}
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"Payment"
MessageType	✔	String	"Response"
ServiceID	✔	String	Mirrored from the request
SaleID	✔	String	Mirrored from the request
POIID	✔	String	Mirrored from the request

PaymentResponse

Attributes	Requ.	Format	Description
Response	✔	Object	Object indicating the result of the payment
Result	✔	String	Indicates the result of the response. Possible values are "Success" and "Failure"
ErrorCondition		String	Indicates the reason an error occurred. Only present when `Result` is "Failure". See ErrorCondition for more information on possible values.
AdditionalResponse		String	Provides additional error information. Only present when `Result` is "Failure". See AdditionalResponse for more information on possible values.
SaleData	✔	Object
SaleTransactionID	✔	Object
TransactionID	✔	String	Mirrored from the request
TimeStamp	✔	String	Mirrored from the request
SaleReferenceID		String	Mirrored from the request
POIData	✔	Object
POITransactionID	✔	Object
TransactionID	✔	String	A unique transaction id from the POI system
TimeStamp	✔	String	Time on the POI system, formatted as ISO8601
POIReconciliationID		String	Present if `Result` is "Success" or "Partial". See POIReconciliationID
PaymentResult		Object	Object related to a processed payment
PaymentType		String	Mirrored from the request
PaymentInstrumentData		Object
PaymentInstrumentType		String	"Card" or "Mobile"
CardData		Object
EntryMode	✔	String	Indicates how the card was presented. See EntryMode
PaymentBrand	✔	String(1,128)	Deprecated. Use PaymentBrandId
PaymentBrandId	✔	String(4,4)	Indicates the payment type used.
PaymentBrandLabel	✔	String(0,256)	Descriptive label of the payment type used.
MaskedPAN	✔	String	PAN masked with dots, first 6 and last 4 digits visible
Account		String	Present if `EntryMode` is "MagStripe", "ICC", or "Tapped". Indicates the card account used. See Account
PaymentToken		Object	Object representing a token. Only present if token was requested
TokenRequestedType	✔	String	Mirrored from the request
TokenValue	✔	String	The value of the token
ExpiryDateTime	✔	String	Expiry of the token, formatted as ISO8601
AmountsResp		Object	Present if `Result` is "Success" or "Partial"
Currency		String	"AUD"
AuthorizedAmount	✔	Decimal	Authorised amount which could be more, or less than the requested amount
TotalFeesAmount		Decimal	Total of financial fees associated with the payment transaction if known at time of transaction
CashBackAmount		Decimal	Cash back paid amount
TipAmount		Decimal	The amount of any tip added to the transaction
SurchargeAmount		Decimal	The amount of any surcharge added to the transaction
OnlineFlag	✔	Boolean	True if the transaction was processed online, false otherwise
PaymentAcquirerData		Object	Data related to the response from the payment acquirer
AcquirerID	✔	String	The ID of the acquirer which processed the transaction
MerchantID	✔	String	The acquirer merchant ID (MID)
AcquirerPOIID	✔	String	The acquirer terminal ID (TID)
AcquirerTransactionID	✔	Object
TransactionID	✔	String	The acquirer transaction ID
TimeStamp	✔	String	Timestamp from the acquirer, formatted as ISO8601
ApprovalCode	✔	String	The Acquirer Approval Code. Also referred to as the Authentication Code
ResponseCode	✔	String	The Acquirer Response Code. Also referred as the PINPad response code
STAN		String	The Acquirer STAN if available
RRN		String	The Acquirer RRN if available
HostReconciliationID	✔	String	Identifier of a reconciliation period with the acquirer. This normally has a date and time component in it
AllowedProductCodes		Array	Present if `ErrorCondition` is "PaymentRestriction". Consists of a list of product codes corresponding to products that are purchasable with the given card. Items that exist in the basket but do not belong to this list corresponds to restricted items
PaymentReceipt		Array	Array of payment receipt objects which represent receipts to be printed
DocumentQualifier	✔	String	"CashierReceipt" for a merchant receipt, otherwise "SaleReceipt"
RequiredSignatureFlag	✔	Boolean	If true, the card holder signature is required on the merchant CashierReceipt.
OutputContent		Array	Array of payment receipt objects which represent receipts to be printed
OutputFormat	✔	String	"XHTML"
OutputXHTML	✔	String	The payment receipt in XHTML format but coded in BASE64

Display

During a payment, the POI System will send status and error display requests to the Sale System, which enables the Sale System to inform the cashier of the current transaction status.

Follow the user interface guide for details on how to implement the required UI to handle display and input requests.

Display request

{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "MessageClass":"Device",
         "MessageCategory":"Display",
         "MessageType":"Request",
         "ServiceID":"xxx",
         "DeviceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "DisplayRequest":{
         "DisplayOutput":{
            "ResponseRequiredFlag":false,
            "Device":"CashierDisplay",
            "InfoQualify":"xxx",
            "OutputContent":{
               "OutputFormat":"Text",
               "OutputText":{
                  "Text":"xxx"
               }
            }
         }
      },
      "SecurityTrailer":{...}
   }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Device"
MessageCategory	✔	String	"Display"
MessageType	✔	String	"Request"
ServiceID	✔	String	Mirrored from payment
SaleID	✔	String	Mirrored from payment
POIID	✔	String	Mirrored from payment

DisplayRequest

Attributes	Requ.	Format	Description
DisplayOutput	✔	Object	Object which represents the display
ResponseRequiredFlag		Boolean	Indicates if the POI System requires a `DisplayResponse` to be sent for this `DisplayRequest`
Device	✔	String	"CashierDisplay"
InfoQualify	✔	String	"Status" or "Error". See InfoQualify
OutputFormat	✔	String	"Text"
Text	✔	String	Single line of text to display

Display response

{
   "SaleToPOIResponse":{
      "MessageHeader":{
         "MessageClass":"Device",
         "MessageCategory":"Display",
         "MessageType":"Response",
         "ServiceID":"xxx",
         "DeviceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "DisplayResponse":{
         "OutputResult":[
            {
               "Device":"xxx",
               "InfoQualify":"xxx",
               "Response":{
                  "Result":"xxx",
                  "ErrorCondition":"xxx",
                  "AdditionalResponse":"xxx"
               }
            }
         ]
      },
      "SecurityTrailer":{...}
   }
}

The Sale System is expected to send a DisplayResponse if one or more displays in DisplayOutput have ResponseRequiredFlag set to true.

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Device"
MessageCategory	✔	String	"Display"
MessageType	✔	String	"Response"
ServiceID	✔	String	Mirrored from display request
SaleID	✔	String	Mirrored from display request
POIID	✔	String	Mirrored from display request

DisplayResponse

Attributes	Requ.	Format	Description
OutputResult	✔	Object	Response for Device/InfoQualify pair where corresponding `ResponseRequiredFlag` in the `DisplayRequest` is set to true.
Device	✔	String	Mirrored from display request
InfoQualify	✔	String	Mirrored from display request
Result	✔	String	"Success", "Partial", or "Failure". See Result.
ErrorCondition		String	Indicates the reason an error occurred. Only present when `Result` is "Failure". See ErrorCondition for more information on possible values.
AdditionalResponse		String	Provides additional error information. Only present when `Result` is "Failure". See AdditionalResponse for more information on possible values.

Input

warning

The Input UI elements are not currently available, and will be supported by a future Unify release. Support for these elements by the Sale System is optional.

During a payment, the POI System will input requests to the Sale System if cashier interaction is required (e.g. signature approved yes/no)

Follow the user interface guide for details on how to implement the required UI to handle display and input requests.

Input request

{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "MessageClass":"Device",
         "MessageCategory":"Input",
         "MessageType":"Request",
         "ServiceID":"xxx",
         "DeviceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "InputRequest":{
         "DisplayOutput":{
            "Device":"CashierDisplay",
            "InfoQualify":"POIReplication",
            "OutputContent":{
               "OutputFormat":"Text",
               "OutputText":{
                  "Text":"xxx"
               }
            },
            "MenuEntry":[
               {
                  "OutputFormat":"Text",
                  "OutputText":{
                     "Text":"xxx"
                  }
               }
            ]
         },
         "InputData":{
            "Device":"CashierInput",
            "InfoQualify":"xxx",
            "InputCommand":"xxx",
            "MaxInputTime":"xxx",
            "MinLength":"xxx",
            "MaxLength":"xxx",
            "MaskCharactersFlag":"true or false"
         }
      },
      "SecurityTrailer":{...}
   }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Device"
MessageCategory	✔	String	"Input"
MessageType	✔	String	"Request"
ServiceID	✔	String	Mirrored from payment request
DeviceID	✔	String	Unique message identifier
SaleID	✔	String	Mirrored from payment request
POIID	✔	String	Mirrored from payment request

InputRequest

Attributes	Requ.	Format	Description
DisplayOutput		Object	Information to display and the way to process the display.
Device	✔	String	"CashierDisplay"
InfoQualify	✔	String	"POIReplication". See InfoQualify
OutputContent	✔	Object
OutputFormat	✔	String	"Text"
OutputText	✔	Object	Wrapper for text content
Text	✔	String	Single line of text. e.g. "Signature Ok?", "Merchant Password", "Select Account Type"
MenuEntry		Array	Conditional. Array of items to be presented as a menu. Only present if InputCommand = "GetMenuEntry"
OutputFormat	✔	String	"Text"
Text	✔	String	One of the selection String items for the cashier to select from. For example: "Savings", "Cheque" and "Credit" for an account type selection.
InputData	✔	Object	Information related to an `Input` request
Device	✔	String	"CashierInput"
InfoQualify	✔	String	"Input" or "CustomerAssistance". See InfoQualify
InputCommand	✔	String	"GetConfirmation", "Password", "TextString", "DigitString", "DecimalString", or "GetMenuEntry". See InputCommand
MaxInputTime		Number	The maximum number of seconds allowed for providing input. Note the Sale Terminal needs to abort the Input process if it receives a DisplayRequest or InputRequest whilst waiting on input from the Cashier.
MinLength		Number	The minimum number of characters allowed for entry. Present if InputCommand = "Password", "TextString", "DigitString", or "DecimalString"
MaxLength		Number	The maximum number of characters allowed for entry. Present if InputCommand = "Password", "TextString", "DigitString", or "DecimalString"
MaskCharactersFlag		Boolean	If true, input should be masked with '*'. Present if InputCommand = "Password"

Input response

{
   "SaleToPOIResponse":{
      "MessageHeader":{
         "MessageClass":"Device",
         "MessageCategory":"Input",
         "MessageType":"Response",
         "ServiceID":"xxx",
         "DeviceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "InputResponse":{
         "OutputResult":{
            "Device":"CashierDisplay",
            "InfoQualify":"POIReplication",
            "Response":{
               "Result":"xxx",
               "ErrorCondition":"xxx",
               "AdditionalResponse":"xxx"
            }
         },
         "InputResult":{
            "Device":"CashierInput",
            "InfoQualify":"xxx",
            "Response":{
               "Result":"xxx",
               "ErrorCondition":"xxx",
               "AdditionalResponse":"xxx"
            },
            "Input":{
               "InputCommand":"xxx",
               "ConfirmedFlag":"true or false",
               "Password":"xxx",
               "MenuEntryNumber":"xxx"
            }
         }
      },
      "SecurityTrailer":{...}
   }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Device"
MessageCategory	✔	String	"Input"
MessageType	✔	String	"Response"
ServiceID	✔	String	A unique value which will be mirrored in the response. See ServiceID.
DeviceID	✔	String	Mirrored from input request
SaleID	✔	String	Mirrored from input request
POIID	✔	String	Mirrored from input request

InputResponse

Attributes	Requ.	Format	Description
OutputResult		Object	Present if `DisplayOutput` is present in the request
Device	✔	String	Mirrored from input request
InfoQualify	✔	String	Mirrored from input request
Response	✔	Object
Result	✔	String	"Success", "Partial", or "Failure". See Result.
ErrorCondition		String	Indicates the reason an error occurred. Only present when `Result` is "Failure". See ErrorCondition for more information on possible values.
AdditionalResponse		String	Provides additional error information. Only present when `Result` is "Failure". See AdditionalResponse for more information on possible values.
InputResult	✔	Object	Information related to the result the input
Device	✔	String	Mirrored from input request
InfoQualify	✔	String	Mirrored from input request
Response	✔	Object
Result	✔	String	"Success", "Partial", or "Failure". See Result.
ErrorCondition		String	Indicates the reason an error occurred. Only present when `Result` is "Failure". See ErrorCondition for more information on possible values.
AdditionalResponse		String	Provides additional error information. Only present when `Result` is "Failure". See AdditionalResponse for more information on possible values.
Input	✔	Object
InputCommand		String	Mirrored from input request
ConfirmedFlag		Boolean	Result of GetConfirmation input request. Present if InputCommand = "GetConfirmation"
Password		String	Password entered by the Cashier. Mandatory, if InputCommand is "Password". Not allowed, otherwise
MenuEntryNumber		Number	A number from 1 to n, when n is total number of objects in `MenuEntry` of `InputRequest`. Mandatory, if InputCommand is "GetMenuEntry". Not allowed, otherwise
TextInput		String	Value entered by the Cashier. Mandatory, if InputCommand is "TextString" or "DecimalString". Not allowed, otherwise
DigitInput		String	Value entered by the Cashier. Mandatory, if InputCommand is "DigitInput". Not allowed, otherwise

Print

During a payment, the POI System may send print requests to the Sale System if a receipt is to be printed before the payment response can be finalised (e.g. when a signature is required).

In this case the Sale System should examine the properties in the print request and print the receipt accordingly.

The final payment receipt, which is to be included in the Sale receipt, is returned in the payment response.

Print request

{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "MessageClass":"Device",
         "MessageCategory":"Print",
         "MessageType":"Request",
         "ServiceID":"xxx",
         "DeviceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "PrintRequest":{
         "PrintOutput":{
            "DocumentQualifier":"CashierReceipt",
            "IntegratedPrintFlag":false,
			"RequiredSignatureFlag":true,
            "OutputContent":{
               "OutputFormat":"XHTML",
               "OutputXHTML":"xxxx"
            },
		},	
      },
      "SecurityTrailer":{...}
   }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Device"
MessageCategory	✔	String	"Print"
MessageType	✔	String	"Request"
ServiceID	✔	String	Mirrored from payment request
DeviceID	✔	String	Unique message identifier
SaleID	✔	String	Mirrored from payment request
POIID	✔	String	Mirrored from payment request

PrintRequest

Attributes	Requ.	Format	Description
PrintOutput	✔	Object
DocumentQualifier	✔	String	"CashierReceipt" for a merchant receipt, otherwise "SaleReceipt"
IntegratedPrintFlag		Boolean	True if the receipt should be included with the Sale receipt, false if the receipt should be printed now and paper cut (e.g. for a signature receipt)
RequiredSignatureFlag	✔	Boolean	If true, the card holder signature is required on the merchant CashierReceipt.
OutputContent		Array	Array of payment receipt objects which represent receipts to be printed
OutputFormat	✔	String	"XHTML"
OutputXHTML	✔	String	The payment receipt in XHTML format but coded in BASE64

Print response

{
   "SaleToPOIResponse":{
      "MessageHeader":{
         "MessageClass":"Device",
         "MessageCategory":"Print",
         "MessageType":"Response",
         "ServiceID":"xxx",
         "DeviceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "PrintResponse":{
	     "DocumentQualifier":"CashierReceipt",
         "Response":{
            "Result":"xxx",
            "ErrorCondition":"xxx",
            "AdditionalResponse":"xxx"
         },
      },
      "SecurityTrailer":{...}
   }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Device"
MessageCategory	✔	String	"Print"
MessageType	✔	String	"Response"
ServiceID	✔	String	Mirrored from print request
DeviceID	✔	String	Mirrored from print request
SaleID	✔	String	Mirrored from print request
POIID	✔	String	Mirrored from print request

PrintResponse

Attributes	Requ.	Format	Description
DocumentQualifier	✔	String	Mirrored from print request
Response	✔	Object
Result	✔	String	"Success", "Partial", or "Failure". See Result.
ErrorCondition		String	Indicates the reason an error occurred. Only present when `Result` is "Failure". See ErrorCondition for more information on possible values.
AdditionalResponse		String	Provides additional error information. Only present when `Result` is "Failure". See AdditionalResponse for more information on possible values.

Transaction status

A transaction status request can be used to obtain the status of a previous transaction. Required for error handling.

Transaction status request

{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "MessageClass":"Service",
         "MessageCategory":"TransactionStatus",
         "MessageType":"Request",
         "ServiceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxxx"
      },
      "TransactionStatusRequest":{
         "MessageReference":{
            "MessageCategory":"xxx",
            "ServiceID":"xxx",
            "SaleID":"xxx",
            "POIID":"xxx"
         }
      },
      "SecurityTrailer":{...}
   }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"TransactionStatus"
MessageType	✔	String	"Request"
ServiceID	✔	String	A unique value which will be mirrored in the response. See ServiceID.
SaleID	✔	String	Uniquely identifies the Sale System
POIID	✔	String	Uniquely identifies the POI Terminal

TransactionStatusRequest

Attributes	Format	Description
MessageReference	Object	Identification of a previous POI transaction. Present if it contains any data.
MessageCategory	String	"Payment"
ServiceID	String	The ServiceID of the transaction to retrieve the status of. If not included the last payment status is returned.
SaleID	String	The SaleID of the transaction to retrieve the status of. Only required if different from the SaleID provided in the `MessageHeader`
POIID	String	The POIID of the transaction to retrieve the status of. Only required if different from the POIID provided in the `MessageHeader`

Transaction status response

{
   "SaleToPOIResponse":{
      "MessageHeader":{
         "MessageClass":"Service",
         "MessageCategory":"TransactionStatus",
         "MessageType":"Response",
         "ServiceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "TransactionStatusResponse":{
         "Response":{
            "Result":"xxx",
            "ErrorCondition":"xxx",
            "AdditionalResponse":"xxx"
         },
         "MessageReference":{
            "MessageCategory":"xxx",
            "ServiceID":"xxx",
            "SaleID":"xxx",
            "POIID":"xxx"
         },
         "RepeatedMessageResponse":{
            "MessageHeader":{...},
            "RepeatedResponseMessageBody":{
               "PaymentResponse":{...},
               "ReversalResponse":{...}
            }
         }
      }
   }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"TransactionStatus"
MessageType	✔	String	"Response"
ServiceID	✔	String	Mirrored from request
SaleID	✔	String	Mirrored from request
POIID	✔	String	Mirrored from request

TransactionStatusResponse

Attributes	Requ.	Format	Description
Response	✔	Object	Object indicating the result of the payment
Result	✔	String	Indicates the result of the response. Possible values are "Success" and "Failure"
ErrorCondition		String	Indicates the reason an error occurred. Only present when `Result` is "Failure". See ErrorCondition for more information on possible values.
AdditionalResponse		String	Provides additional error information. Only present when `Result` is "Failure". See AdditionalResponse for more information on possible values.
MessageReference		Object	Identification of a previous POI transaction. Present if `Result` is "Success", or `Result` is "Failure" and `ErrorCondition` is "InProgress"
MessageCategory	✔	String	Mirrored from request
ServiceID	✔	String	Mirrored from request, or `ServiceID` of last transaction if not present in request.
SaleID		String	Mirrored from request, but only if present in the request
POIID		String	Mirrored from request, but only if present in the request
RepeatedMessageResponse		Object	Present if `Result` is "Success"
MessageHeader	✔	Object	`MessageHeader` of the requested payment
PaymentResponse	✔	Object	`PaymentResponse` of the requested payment

Abort transaction

The Sale System can send an abort transaction message to request cancellation of the in-progress transaction.

tip

Cancel transaction is a "request to cancel". Cancellation of the transaction is not guaranteed. There are a number of instances where cancellation is not possible (for example, when the payment has already completed).

After sending a cancel transaction request, the Sale System should always wait for the payment/card acquisition response and validate the success of the sale by checking the Result property.

Abort transaction request

{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "MessageClass":"Service",
         "MessageCategory":"Abort",
         "MessageType":"Request",
         "ServiceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "AbortRequest":{
         "MessageReference":{
            "MessageCategory":"xxx",
            "ServiceID":"xxxx",
            "SaleID":"xxx",
            "POIID":"xxx"
         },
         "AbortReason":"xxx"
      },
      "SecurityTrailer":{...}
   }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"Abort"
MessageType	✔	String	"Request"
ServiceID	✔	String	A unique value which will be mirrored in the response. See ServiceID.
SaleID	✔	String	Unique identifier for the Sale System
POIID	✔	String	Uniquely identifies the POI Terminal

AbortRequest

Attributes	Requ.	Format	Description
MessageReference	✔	Object	Identification of a POI transaction
MessageCategory	✔	String	"Payment" or "CardAcquisition"
ServiceID	✔	String	The ServiceID of the transaction to cancel
SaleID		String	The SaleID of the transaction to cancel. Only required if different from the SaleID provided in the `MessageHeader`
POIID		String	The POIID of the transaction to cancel. Only required if different from the POIID provided in the `MessageHeader`
AbortReason	✔	String	Any text describing the reason for cancelling the transaction. For example, "User Cancel"

Abort transaction response

Once an abort transaction request has been sent, please continue to wait for the payment response.

If the transaction is successfully aborted, a payment response is returned with Result = "Failure" and ErrorCondition = "Aborted".

If the transaction cannot be aborted, a normal payment response (Result = "Success") is sent back in time.

However, if the abort transaction request message contains an invalid data (e.g. message format error) or if the referenced transaction cannot be not found (e.g. due to an incorrect ServiceID value), an Event Notification will be returned.

Abort transaction response

{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "MessageClass":"Event",
         "MessageCategory":"Event",
         "MessageType":"Notification",
         "DeviceID":"xxx",
         "SaleID":"xxx",
         "POIID":"xxx"
      },
      "EventNotification":{
         "TimeStamp":"xxx",
         "EventToNotify":"xxx",
         "EventDetails":"xxx"
      },
      "SecurityTrailer":{...}
   }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Event"
MessageCategory	✔	String	"Event"
MessageType	✔	String	"Notification"
DeviceID	✔	String	Unique message identifier
SaleID	✔	String	Mirrored from payment request
POIID	✔	String	Mirrored from payment request

EventNotification

Attributes	Requ.	Format	Description
TimeStamp	✔	String	Time of the event on the POI System, formatted as ISO8601
EventToNotify	✔	String	"Reject" if the abort request cannot be accepted (e.g. message format error, `ServiceId` not found). "CompletedMessage" if payment has already completed.
EventDetails	✔	String	Extra detail on the reason for the event

Reconciliation

Reconciliation request

{
  "SaleToPOIRequest":{
    "MessageHeader":{
      "MessageClass":"Service",
      "MessageCategory":"Reconciliation",
      "MessageType":"Request",
      "ServiceID":"xxxx",
      "SaleID":"xxx",
      "POIID":"xxx"
    },
    "ReconciliationRequest":{
      "ReconciliationType":"xxx",
      "POIReconciliationID":"xxx"
    },
    "SecurityTrailer":{...}
  }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"Reconciliation"
MessageType	✔	String	"Request"
ServiceID	✔	String	A unique value which will be mirrored in the response. See ServiceID.
SaleID	✔	String	Unique identifier for the Sale System
POIID	✔	String	Uniquely identifies the POI Terminal

ReconciliationRequest

Attributes	Requ.	Format	Description
ReconciliationType	✔	String	"SaleReconciliation" to close the current period, "PreviousReconciliation" to request the result of a previous reconciliation
POIReconciliationID		String	Present if ReconciliationType is "PreviousReconciliation". See POIReconciliationID

Reconciliation response

{
  "SaleToPOIResponse":{
    "MessageHeader":{
      "MessageClass":"Service",
      "MessageCategory":"Reconciliation",
      "MessageType":"Response",
      "ServiceID":"xxx",
      "SaleID":"xxx",
      "POIID":"xxx"
    },
    "ReconciliationResponse":{
      "Response":{
        "Result":"xxx",
        "ErrorCondition":"xxx",
        "AdditionalResponse":"xxx"
      },
      "ReconciliationType":"xxx",
      "POIReconciliationID":"xxx",
      "TransactionTotals":[
        {
          "PaymentInstrumentType":"xxx",
          "CardBrand":"xxx",
          "OperatorID":"xxx",
          "ShiftNumber":"xxx",
          "TotalsGroupID":"xxx",
          "PaymentCurrency":"AUD",
          "PaymentTotals":[
            {
              "TransactionType":"xxx",
              "TransactionCount":"xxx",
              "TransactionAmount":"0.00",
			  "TipAmount":"0.00",
			  "SurchargeAmount":"0.00"
            }
          ]
        }
      ]
    },
    "SecurityTrailer":{...}
  }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"Reconciliation"
MessageType	✔	String	"Response"
DeviceID	✔	String	Unique message identifier
SaleID	✔	String	Mirrored from payment request
POIID	✔	String	Mirrored from payment request

ReconciliationResponse

Attributes	Requ.	Format	Description
Response	✔	Object	Object indicating the result of the login
Result	✔	String	Indicates the result of the response. Possible values are "Success" and "Failure"
ErrorCondition		String	Indicates the reason an error occurred. Only present when `Result` is "Failure". See ErrorCondition for more information on possible values.
AdditionalResponse		String	Provides additional error information. Only present when `Result` is "Failure". See AdditionalResponse for more information on possible values.
ReconciliationType	✔	String	Mirrored from request
POIReconciliationID		String	Present if `Result` is "Success". The `ReconciliationID` of the period requested
TransactionTotals		Array	Present if `Result` is "Success". An array of totals grouped by card brand, then operator, then shift, then TotalsGroupID, then payment currency.
PaymentInstrumentType	✔	String	"Card" (card payment) or "Mobile" (phone/QR code payments)
CardBrand		String	A card brand used during this reconciliation period
OperatorID		String	An operator id used during this reconciliation period
ShiftNumber		String	A shift number used during the reconciliation period
TotalsGroupID		String	A custom grouping of transactions as defined by the Sale System
PaymentCurrency		String	"AUD"
PaymentTotals		Array	An array [0..10] of totals grouped by transaction payment type. Present if both `TransactionCount` and `TransactionAmount` are not equal to zero
TransactionType		String	Transaction type for this payment. See TransactionType
TransactionCount		String	The number of transactions for the transaction type for the current grouping of transactions
TransactionAmount		Number	The total amount of transactions for the transaction type for the current grouping of transactions

Card acquisition

The card acquisition request allows the Sale System to tokenise a card which can be used in future payment requests.

Card acquisition request

{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "CardAcquisition",
      "MessageType": "Request",
      "ServiceID": "xxx",
      "SaleID": "xxx",
      "POIID": "xxx"
    },
    "CardAcquisitionRequest": {
      "SaleData": {
        "OperatorID": "xxx",
        "OperatorLanguage": "en",
        "ShiftNumber": "xxx",
        "CustomerLanguage": "en",
        "SaleTransactionID": {
          "TransactionID": "xxx",
          "TimeStamp": "xxx"
        },
        "SaleTerminalData": {
          "TerminalEnvironment": "xxx",
          "SaleCapabilities": ["xxx", "xxx", "xxx", …]
        },
        "TokenRequestedType": "Customer",
      },
      "CardAcquisitionTransaction": {
        "AllowedPaymentBrand": ["xxx", "xxx", "xxx", …],
        "ForceEntryMode": "xxx"
      }
    },
    "SecurityTrailer": { ... }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"CardAcquisition"
MessageType	✔	String	"Request"
ServiceID	✔	String	A unique value which will be mirrored in the response. See ServiceID.
SaleID	✔	String	Unique identifier for the Sale System
POIID	✔	String	Uniquely identifies the POI Terminal

CardAcquisitionRequest

Attributes	Requ.	Format	Description
SaleData	✔	Object	Object Sale System information attached to this payment
OperatorID		String	Only required if different from Login Request
OperatorLanguage		String	Set to "en"
ShiftNumber		String	Only required if different from Login Request
CustomerLanguage		String	Set to "en" for English
TokenRequestedType	✔	String	"Customer"
SaleTransactionID		Object
TransactionID	✔	String	Unique reference for this sale ticket
TimeStamp	✔	String	Time of initiating the request on the POI System, formatted as ISO8601 DateTime. e.g. "2019-09-02T09:13:51.0+01:00"
SaleTerminalData		Object	Define Sale System configuration. Only include if elements within have different values to those in Login Request
TerminalEnvironment		String	"Attended", "SemiAttended", or "Unattended"
SaleCapabilities		Array	Advises the POI System of the Sale System capabilities. See SaleCapabilities
CardAcquisitionTransaction		Object	Present if any of the JSON elements within are present
AllowedPaymentBrand		Array	Restricts the request to specified card brands. See AllowedPaymentBrand
ForceEntryMode		String	If present, restricts card presentment to the specified type. See ForceEntryMode

Card acquisition response

{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "CardAcquisition",
      "MessageType": "Response",
      "ServiceID": "xxx",
      "SaleID": "xxx",
      "POIID": "xxx"
    },
    "CardAcquisitionResponse": {
      "Response": {
        "Result": "xxx",
        "ErrorCondition": "xxx",
        "AdditionalResponse": "xxx"
      },
      "SaleData": {
        "SaleTransactionID": {
          "TransactionID": "xxx",
          "TimeStamp": "xxx"
        },
      },
      "POIData": {
        "POITransactionID": {
          "TransactionID": "xxx",
          "TimeStamp": "xxx"
        },
      },
      "PaymentInstrumentData": {
        "PaymentInstrumentType": "xxx",
          "CardData": {
            "MaskedPAN": "xxxxxx......xxxx",
            "EntryMode": "xxx"
          },
          "PaymentToken":  {
            "TokenRequestedType": "xxx",
            "TokenValue": "xxx",
            "ExpiryDateTime": "xxx"
          }
        }
      },
      "SecurityTrailer": {...}
    }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"CardAcquisition"
MessageType	✔	String	"Response"
DeviceID	✔	String	Unique message identifier
SaleID	✔	String	Mirrored from payment request
POIID	✔	String	Mirrored from payment request

CardAcquisitionResponse

Attributes	Requ.	Format	Description
Response	✔	Object	Object indicating the result of the login
Result	✔	String	Indicates the result of the response. Possible values are "Success" and "Failure"
ErrorCondition		String	Indicates the reason an error occurred. Only present when `Result` is "Failure". See ErrorCondition for more information on possible values.
AdditionalResponse		String	Provides additional error information. Only present when `Result` is "Failure". See AdditionalResponse for more information on possible values.
SaleData	✔	Object
SaleTransactionID	✔	Object
TransactionID	✔	String	Mirrored from the request
TimeStamp	✔	String	Mirrored from the request
SaleReferenceID		String	Mirrored from the request
POIData	✔	Object
POITransactionID	✔	Object
TransactionID	✔	String	A unique transaction id from the POI system
TimeStamp	✔	String	Time on the POI system, formatted as ISO8601
PaymentInstrumentData		Object	Object with represents card details for token or manually enter card details.
PaymentInstrumentType		String	Defaults to "Card". Indicates the card source for the payment. See PaymentInstrumentType
CardData		Object
EntryMode		String	Only present if `PaymentInstrumentType` is "Card". "File" if a Payment Token is used, and "Keyed" for a Card Not Present transaction.
MaskedPAN	✔	String	PAN masked with dots, first 6 and last 4 digits visible
PaymentToken	✔	Object	Only present if EntryMode is "File". Object with identifies the payment token.
TokenRequestedType	✔	String	"Transaction" or "Customer". Must match the type of token recorded in the POI System.
TokenValue	✔	String	Token previously returned from the POI System in the payment, or card acquisition response

Error handling

When the Sale System sends a request, it will receive a matching response. For example, if the Sale System sends a payment request it will receive a payment response.

The Sale System should verify the result of the transaction by checking the Response.Result field in the response.

If the Response.Result is "Success", the payment transaction was successful.
If the Response.Result is "Failure", the payment transaction failed. The Sale System may check for any errors specified in the Response.ErrorCondition field in the same response message and handle the error accordingly.

In the event the Sale System does not receive a response (for example, due to network error, timeout, or any other unexpected error) it must enter error handling.

Error handling due to network error, timeout, or any other unexpected error is outlined in the diagram below.

Cashier initiates a payment.
Sale System sets txn_in_progress flag in local persistent storage.
Sale System sends a payment request. The timeout period for waiting for a response is 60 seconds. This should reset every time a response (for example, display request) is received.
Sale System saves message reference details in local persistent storage.
Network error/timeout/any other unexpected error occurs.
Sale System awaits Internet availability.

Sale System enters error handling:

Sale System sends an abort transaction request.

Sale System must set the AbortRequest.AbortReason field to describe the reason for cancelling the transaction.

`AbortRequest.AbortReason` value	Description
Network Error	Network related error occured.
Timeout	No response from the host after the timeout period.
Message Format Error	An error occured while converting a message.
Invalid Data	An invalid data was received.
Other Exception	An unwanted exception has occured.

For a maximum of 90 seconds, the Sale System should perform the below in a loop:

Sale System sends a transaction status request and awaits a transaction status response
Sale System handles the transaction status response:

`Response.Result` value	`Response.ErrorCondition` value	Description
Success		The transaction was successful.
	The transaction result will be contained in `RepeatedMessageResponse`.
	The `RepeatedMessageResponse` will contain the payment response.
Failure	"InProgress"	The Terminal is still processing the payment.
	The Sale System should wait for 5 seconds and send a transaction status request again.
Failure	any other value aside from "InProgress"	The payment failed.
	The Sale System can exit the loop.

If the Sale System is unable retrieve a result within 90 seconds:
- Sale System must display UI to ask Cashier to check the transaction history in the POI terminal.
- Cashier confirms in the Sale System whether the payment transaction succeeded or failed basing on the transaction record in the transaction history in the POI terminal.
Sale System clears the message reference details in the local persistent storage.
Sale System clears the txn_in_progress flag in the local persistent storage.

Sale System proceeds with its successful/failed transaction processing, depending on the transaction result.

Power failure handling

The Sale System can handle a power failure by checking a local transaction status on start up.

Cashier initiates a payment.
Sale System sets txn_in_progress flag in local persistent storage.
Sale System sends a payment request
Sale System saves message reference details in local persistent storage.
Sale System power failure occurs.
Sale System start up after power failure.
Sale System checks if txn_in_progress flag is set. If so, access and use message reference details and enter error handling.
1. Sale System sends an abort transaction request.
  - Sale System must set the AbortRequest.AbortReason field to "Power Failure".
2. For a maximum of 90 seconds, Sale System enters loop to check transaction status.
3. If the Sale System is unable retrieve a result within 90 seconds:
  - Sale System must display UI to ask Cashier to check the transaction history in the POI terminal.
  - Cashier confirms in the Sale System whether the payment transaction succeeded or failed basing on the transaction record in the transaction history in the POI terminal.
4. Sale System clears the message reference details in the local persistent storage.
5. Sale System clears the txn_in_progress flag in the local persistent storage.
Sale System proceeds with its successful/failed transaction processing, depending on the transaction result.

Fusion Cloud

Reference code​

Security requirements​

Endpoints​

Message format​

MessageHeader​

Payload​

SecurityTrailer​

Perform a purchase​

Perform a refund​

Sample code for Performing a Purchase or Refund​

Methods​

Login​

Login request​

Login response​

Logout​

Logout request​

Logout response​

Payment​

Payment request​

PaymentRequest​

Payment response​

Display​

Display request​

Display response​

Input​

Input request​

Input response​

Print​

Print request​

Print response​

Transaction status​

Transaction status request​

Transaction status response​

Abort transaction​

Abort transaction request​

Abort transaction response​

Reconciliation​

Reconciliation request​

Reconciliation response​

Card acquisition​

Card acquisition request​

Card acquisition response​

Error handling​

Reference code

Security requirements

Endpoints

Message format

MessageHeader

Payload

SecurityTrailer

Perform a purchase

Perform a refund

Sample code for Performing a Purchase or Refund

Methods

Login

Login request

Login response

Logout

Logout request

Logout response

Payment

Payment request

PaymentRequest

Payment response

Display

Display request

Display response

Input

Input request

Input response

Print

Print request

Print response

Transaction status

Transaction status request

Transaction status response

Abort transaction

Abort transaction request

Abort transaction response

Reconciliation

Reconciliation request

Reconciliation response

Card acquisition

Card acquisition request

Card acquisition response

Error handling