Data model
Definition of request, response messages and properties used by the Fusion API's.
Data format
- Mandatory fields have a check (✔) mark in the "Requ" column.
- A mandatory field must be present (not null, not whitespace) and if a string, have a length > 0.
- Each field is marked with a data format. Available data formats are outlined below
Type | Format |
---|---|
Integer (MIN, MAX) | A whole number.
|
Decimal (MIN, MAX, PRECISION) | A decimal number.
|
Currency (MIN, MAX) | Decimal formatted as $$$$$$$.CC.
|
String (MIN, MAX) | String representing printable ASCII characters (character code 32-127).
|
UUID | 128-bit text string formatted as: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
ISO8601 | iso8601 formatted date and time. See ISO 8601 - Wikipedia |
Boolean | true or false. |
Object | An object containing other properties. |
Enum | One of an enumeration of values. |
Array (X) | An array of specified data type. |
Request/response messages
SaleToPOI
The SaleToPOIRequest
and SaleToPOIResponse
are used to wrap request and response messages and contain at least two objects:
- A MessageHeader object.
- A
Payload
request or response object of variable types.
SaleToPOIRequest
Attributes | Requ. | Format | Description |
---|---|---|---|
MessageHeader | ✔ | Object | Message header |
PaymentRequest | Object | If payment request | |
LoginRequest | Object | If login request | |
LogoutRequest | Object | If logout request | |
DisplayRequest | Object | If display request | |
InputRequest | Object | If input request | |
PrintRequest | Object | If print request | |
TransactionStatusRequest | Object | If transaction status request | |
AbortRequest | Object | If abort request | |
ReconciliationRequest | Object | If reconciliation request | |
CardAcquisitionRequest | Object | If card acquisition request |
SaleToPOIRequest
{
"SaleToPOIRequest": {
"MessageHeader":{},
"PaymentRequest":{},
"LoginRequest":{},
"LogoutRequest":{},
"DisplayRequest":{},
"InputRequest":{},
"PrintRequest":{},
"TransactionStatusRequest":{},
"AbortRequest":{},
"ReconciliationRequest":{},
"CardAcquisitionRequest":{},
"BalanceInquiryRequest":{},
"StoredValueRequest":{},
}
}
SaleToPOIResponse
Attributes | Requ. | Format | Description |
---|---|---|---|
MessageHeader | ✔ | Object | Message header |
PaymentRequest | Object | If payment request | |
LoginRequest | Object | If login request | |
LogoutRequest | Object | If logout request | |
DisplayRequest | Object | If display request | |
InputRequest | Object | If input request | |
PrintRequest | Object | If print request | |
TransactionStatusRequest | Object | If transaction status request | |
AbortRequest | Object | If abort request | |
ReconciliationRequest | Object | If reconciliation request | |
CardAcquisitionRequest | Object | If card acquisition request |
SaleToPOIResponse
{
"SaleToPOIResponse": {
"MessageHeader":{},
"PaymentResponse":{},
"LoginResponse":{},
"LogoutResponse":{},
"DisplayResponse":{},
"InputResponse":{},
"PrintResponse":{},
"TransactionStatusResponse":{},
"AbortResponse":{},
"ReconciliationResponse":{},
"CardAcquisitionResponse":{},
"BalanceInquiryResponse":{},
"StoredValueResponse":{},
}
}
MessageHeader
A MessageHeader
is included with each request and response. It defines the protocol and message type.
MessageHeader
"MessageHeader":{
"MessageClass":"",
"MessageCategory":"",
"MessageType":"",
"ServiceID":""
}
Attributes | Requ. | Format | Description |
---|---|---|---|
MessageClass | ✔ | Enum | Informs the receiver of the class of message. Possible values are "Service", "Device", or "Event" |
MessageCategory | ✔ | Enum | Indicates the category of message. Possible values are "CardAcquisition", "Display", "Login", "Logout", "Payment" |
MessageType | ✔ | Enum | Type of message. Possible values are "Request", "Response", or "Notification" |
ServiceID | ✔ | UUID | A unique value which will be mirrored in the response. See ServiceID. |
Balance inquiry
Balance inquiry request/response currently in DRAFT status
The Sale System can send a balance inquiry to instruct the POI terminal to read a card and return the outstanding balance.
Balance inquiry request
Balance inquiry request
{
"BalanceInquiryRequest": {
}
}
The BalanceInquiryRequest
node is intentionally empty.
Balance inquiry response
Balance inquiry response
{
"BalanceInquiryResponse": {
"Response": {
"Result": "Success | Failure",
"ErrorCondition": "xxx",
"AdditionalResponse": "xxx"
},
"PaymentAccountStatus": {
"PaymentInstrumentType": "Card",
"PaymentInstrumentData": {
"PaymentInstrumentType": "xxx",
"CardData": {
"EntryMode": "xxx",
"PaymentBrand": "xxx",
"PaymentBrandId": "xxx",
"PaymentBrandLabel": "xxx",
"Account": "xxx",
"MaskedPAN": "xxxxxx…xxxx",
"PaymentToken": {
"TokenRequestedType": "xxx",
"TokenValue": "xxx",
"ExpiryDateTime": "xxx"
}
},
"StoredValueAccountID": {
"StoredValueAccountType": "GiftCard | PhoneCard | Other",
"StoredValueProvider": "",
"OwnerName": "",
"ExpiryDate": "MMYY",
"EntryMode": "",
"IdentificationType": "",
"StoredValueID": ""
}
},
"CurrentBalance": 0.00,
"Currency": "AUD",
"PaymentAcquirerData": {
"AcquirerID": "xxx",
"MerchantID": "xxx",
"AcquirerPOIID": "xxx",
"AcquirerTransactionID": {
"TransactionID": "xxx",
"TimeStamp": "xxx"
},
"ApprovalCode": "xxx",
"ResponseCode": "xxx",
"HostReconciliationID": "xxx"
},
}
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
Response | ✔ | Object | Object indicating the result of the login |
Result | ✔ | Enum | Indicates the result of the response. Possible values are "Success" and "Failure" |
ErrorCondition | String(0,256) | Indicates the reason an error occurred. Only present when Result is "Failure". See ErrorCondition for more information on possible values. | |
AdditionalResponse | String(0,1024) | Provides additional error information. Only present when Result is "Failure". See AdditionalResponse for more information on possible values. | |
PaymentAccountStatus | |||
PaymentInstrumentData | Object | ||
PaymentInstrumentType | String(1,128) | "Card" or "Mobile" | |
CardData | Object | ||
EntryMode | ✔ | Enum | Indicates how the card was presented. |
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(1,64) | PAN masked with dots, first 6 and last 4 digits visible |
Account | String(1,64) | Present if EntryMode is "MagStripe", "ICC", or "Tapped". Indicates the card account used. See Account | |
StoredValueAccountID | Object | Present if the card presented was a gift card / stored value card | |
StoredValueAccountType | ✔ | Enum | Type of stored value account. GiftCard |
StoredValueProvider | String(1,256) | Identification of the provider of the stored value account. | |
OwnerName | String(1,256) | If available, the name of the owner of a stored value account. | |
EntryMode | Enum | Indicates how the payment type was presented. | |
IdentificationType | ✔ | Enum | Type of account identification contained in StoredValueID. Values are PAN |
StoredValueID | ✔ | String(128) | Stored value account identification |
CurrentBalance | ✔ | Currency(0,999999.99) | Balance of an account. |
Currency | ✔ | String(3,3) | Three character (ISO 4217 formatted) currency code. Set to "AUD". |
PaymentAcquirerData | Object | Data related to the response from the payment acquirer | |
AcquirerID | ✔ | String | The ID of the acquirer which processed the transaction |
MerchantID | ✔ | String(1,32) | The acquirer merchant ID (MID) |
AcquirerPOIID | ✔ | String(1,16) | The acquirer terminal ID (TID) |
AcquirerTransactionID | ✔ | Object | |
TransactionID | ✔ | String(1,128) | The acquirer transaction ID |
TimeStamp | ✔ | ISO8601 | Timestamp from the acquirer, formatted as ISO8601 |
ApprovalCode | ✔ | String(0,64) | The Acquirer Approval Code. Also referred to as the Authentication Code |
ResponseCode | ✔ | String(0,8) | The Acquirer Response Code. Also referred as the PINPad response code |
STAN | String(1,32) | The Acquirer STAN if available | |
RRN | String(1,32) | The Acquirer RRN if available | |
HostReconciliationID | ✔ | String(1,32) | Identifier of a reconciliation period with the acquirer. This normally has a date and time component in it |
PaymentReceipt | Array(Object) | Array of payment receipt objects which represent receipts to be printed | |
DocumentQualifier | ✔ | Enum | "CashierReceipt" for a merchant receipt, otherwise "SaleReceipt" |
RequiredSignatureFlag | ✔ | Boolean | If true, the card holder signature is required on the merchant CashierReceipt. |
OutputContent | Array(Object) | Array of payment receipt objects which represent receipts to be printed | |
OutputFormat | ✔ | String(0,32) | "XHTML" |
OutputXHTML | ✔ | String(0,4096) | The payment receipt in XHTML format but coded in BASE64 |
Currency | ✔ | String(3,3) | Three character (ISO 4217 formatted) currency code. Set to "AUD". |
RequestedAmount | ✔ | Currency(0.01,999999.99) | The requested amount for the transaction sale items, including cash back and tip requested |
Login
The Sale System sends a Login request when it is ready to pair with a POI terminal. The Sale System can pair with multiple POI terminals by sending multiple Login requests.
Login request
Login request
{
"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"
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
DateTime | ✔ | ISO8601 | 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(1,256) | The name of the company supplying the Sale System. Provided by DataMesh. |
ApplicationName | ✔ | String(1,256) | The name of the Sale System application. Provided by DataMesh. |
SoftwareVersion | ✔ | String(1,256) | The software version of the Sale System. Must be the software version of the current build. |
CertificationCode | ✔ | GUID | Certification code for this Sale System. Provided by DataMesh. |
SaleTerminalData | ✔ | Object | Object containing Sale System configuration |
TerminalEnvironment | ✔ | Enum | "Attended", "SemiAttended", or "Unattended" |
SaleCapabilities | ✔ | Array | Advises the POI System of the Sale System capabilities. See SaleCapabilities |
TotalsGroupId | String(1,256) | Groups transactions in a login session | |
OperatorLanguage | String(2,8) | Operator language. Set to 'en' | |
OperatorId | String(1,128) | Groups transactions under this operator id | |
ShiftNumber | String(1,128) | Groups transactions under this shift number | |
POISerialNumber | String(1,128) | 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 |
Login response
Login response
{
"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"
}
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
Response | ✔ | Object | Object indicating the result of the login |
Result | ✔ | Enum | Indicates the result of the response. Possible values are "Success" and "Failure" |
ErrorCondition | String(0,256) | Indicates the reason an error occurred. Only present when Result is "Failure". See ErrorCondition for more information on possible values. | |
AdditionalResponse | String(0,1024) | 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 | ✔ | ISO8601 | 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 | ✔ | Enum | Mirrored from the request |
POICapabilities | ✔ | Array(Enum) | An array of strings which reflect the hardware capabilities of the POI Terminal. "MagStripe", "ICC", and "EMVContactless" |
GenericProfile | ✔ | Enum | Set to "Custom" |
POISerialNumber | ✔ | String(1,256) | If POIID is "POI Server", then a virtual POI Terminal Serial Number. Otherwise the serial number of the POI Terminal |
POIStatus | ✔ | Object | Object representing the current status of the POI Terminal |
GlobalStatus | ✔ | String(1,256) | 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 | ✔ | Enum | 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
Logout request
{
"LogoutRequest": {
"MaintenanceAllowed": "true or false"
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
MaintenanceAllowed | Boolean | Indicates if the POI Terminal can enter maintenance mode. Default to true if not present. |
Logout response
Logout response
{
"LogoutResponse": {
"Response": "xxx",
"ErrorCondition": "xxx",
"AdditionalResponse": "xxx xxxx xxxx xxxx xxxx"
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
Response | ✔ | Object | Object which represents the result of the response |
Result | ✔ | Enum | Indicates the result of the response. Possible values are "Success" and "Failure" |
ErrorCondition | String(0,256) | 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(0,1024) | 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
Payment request
{
"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",
"PaymentBrand": "xxx",
"PaymentBrandId": "xxx",
"PaymentBrandLabel": "xxx",
"Account": "xxx",
"MaskedPAN": "xxxxxx…xxxx",
"PaymentToken": {
"TokenRequestedType": "xxx",
"TokenValue": "xxx",
"ExpiryDateTime": "xxx"
}
}
}
},
"CustomFields": [
{
"Key": "xxx",
"Type": "xxx",
"Value": "xxx"
}
]
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
SaleData | ✔ | Object | Sale System information attached to this payment |
OperatorID | String(1,128) | Only required if different from Login Request | |
OperatorLanguage | String(2,8) | Set to "en" | |
ShiftNumber | String(1,128) | Only required if different from Login Request | |
SaleReferenceID | String(1,128) | Mandatory for pre-authorisation and completion, otherwise optional. See SaleReferenceID | |
TokenRequestedType | Enum | If present, indicates which type of token should be created for this payment. See TokenRequestedType | |
SaleTransactionID | ✔ | Object | |
TransactionID | ✔ | String(1,128) | 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 | ✔ | ISO8601 | 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 | Enum | "Attended", "SemiAttended", or "Unattended" | |
SaleCapabilities | Array(Enum) | Advises the POI System of the Sale System capabilities. See SaleCapabilities | |
TotalsGroupId | String(1,256) | Groups transactions in a login session | |
PaymentTransaction | ✔ | Object | |
AmountsReq | ✔ | Object | Object which contains the various components which make up the payment amount |
Currency | ✔ | String(3,3) | Three character (ISO 4217 formatted) currency code. Set to "AUD". |
RequestedAmount | ✔ | Currency(0.01,999999.99) | The requested amount for the transaction sale items, including cash back and tip requested |
CashBackAmount | Currency(0.01,999999.99) | The Cash back amount. Only if cash back is included in the transaction by the Sale System | |
TipAmount | Currency(0.01,999999.99) | 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 | Currency(0.01,999999.99) | 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 | Currency(0.01,999999.99) | Available if CashBackAmount is not present. If present, the POI Terminal prompts for the cash back amount up to a maximum of MaximumCashBackAmount | |
MinimumSplitAmount | Currency(0.01,999999.99) | 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(1,128) | SaleID which performed the original transaction |
POIID | ✔ | String(1,128) | POIID which performed the original transaction |
POITransactionID | ✔ | Object | |
TransactionID | ✔ | String(1,128) | TransactionID from the original transaction |
TimeStamp | ✔ | ISO8601 | 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(1,128) | 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(String) | Restricts the request to specified card brands. See AllowedPaymentBrand | |
AcquirerID | String(1,128) | 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(1,64) | If present, overrides the MCC used for processing the transaction if allowed. Refer to ISO 18245 for available codes. | |
SaleItem | ✔ | Array(Object) | Array of SaleItem objects which represent the product basket attached to this transaction. See SaleItem for examples. |
ItemID | ✔ | Integer(0,9999) | 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(1,128) | 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(1,128) | A standard unique identifier for the product. Either the UPC, EAN, or ISBN. Required for products with a UPC, EAN, or ISBN | |
UnitOfMeasure | ✔ | Enum | Unit of measure of the Quantity . If this item has no unit of measure, set to "Other" |
Quantity | ✔ | Decimal(0,999999,8) | Sale item quantity based on UnitOfMeasure . |
UnitPrice | ✔ | Decimal(0,999999,8) | Price per sale item unit. Present if Quantity is included. |
ItemAmount | ✔ | Currency(0.01,999999.99) | Total amount of the sale item |
TaxCode | String(1,32) | Type of tax associated with the sale item. Default = "GST" | |
SaleChannel | String(1,128) | Commercial or distribution channel of the sale item. Default = "Unknown" | |
ProductLabel | ✔ | String(1,256) | 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(0,9999) | Required if this item is a 'modifier' or sub-item. Contains the ItemID of the parent SaleItem | |
CostBase | [Currency(0.01,999999.99)] | Cost of the product to the merchant per unit | |
Discount | [Currency(0.01,999999.99)] | If applied, the amount this sale item was discounted by | |
Categories | Array(String) | Array of categories. Top level "main" category at categories[0]. See Categories for more information. | |
Brand | String(1,256) | 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) | 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(1,512) | URL link to the sale items product page | |
ImageURLs | Array(String) | String array of images URLs for this sale item | |
Style | String(1,256) | Style of the sale item | |
Size | String(1,64) | Size of the sale item | |
Colour | String(1,64) | Colour of the sale item | |
Weight | Decimal(0,999999,8) | Sale item weight, based on WeightUnitOfMeasure | |
WeightUnitOfMeasure | Enum | 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 | ✔ | Enum | 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(Object) | Array of key/type/value objects containing additional payment information |
Payment response
Payment response
{
"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"
},
"CurrentBalance": "x.xx",
"Currency": "AUD"
},
"AllowedProductCodes": [
"1",
"2",
"3"
],
"PaymentReceipt": [
{
"DocumentQualifier": "xxx",
"RequiredSignatureFlag": true,
"OutputContent": {
"OutputFormat": "XHTML",
"OutputXHTML": "xxx"
}
}
]
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
Response | ✔ | Object | Object indicating the result of the payment |
Result | ✔ | Enum | Indicates the result of the response. Possible values are "Success" and "Failure" |
ErrorCondition | String(0,256) | Indicates the reason an error occurred. Only present when Result is "Failure". See ErrorCondition for more information on possible values. | |
AdditionalResponse | String(0,1024) | Provides additional error information. Only present when Result is "Failure". See AdditionalResponse for more information on possible values. | |
SaleData | ✔ | Object | |
SaleTransactionID | ✔ | Object | |
TransactionID | ✔ | String(1,128) | Mirrored from the request |
TimeStamp | ✔ | ISO8601 | Mirrored from the request |
SaleReferenceID | String(1,128) | Mirrored from the request | |
POIData | ✔ | Object | |
POITransactionID | ✔ | Object | |
TransactionID | ✔ | String(1,128) | A unique transaction id from the POI system |
TimeStamp | ✔ | ISO8601 | Time on the POI system, formatted as ISO8601 |
POIReconciliationID | String(1,128) | Present if Result is "Success" or "Partial". See POIReconciliationID | |
PaymentResult | Object | Object related to a processed payment | |
PaymentType | Enum | Mirrored from the request | |
PaymentInstrumentData | Object | ||
PaymentInstrumentType | String(1,128) | "Card" or "Mobile" | |
CardData | Object | ||
EntryMode | ✔ | String(1,128) | Indicates how the card was presented. |
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(1,64) | PAN masked with dots, first 6 and last 4 digits visible |
Account | String(1,64) | 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(1,64) | Mirrored from the request |
TokenValue | ✔ | String(1,128) | The value of the token |
ExpiryDateTime | ✔ | ISO8601 | Expiry of the token, formatted as ISO8601 |
AmountsResp | Object | Present if Result is "Success" or "Partial" | |
Currency | ✔ | String(3,3) | Three character (ISO 4217 formatted) currency code. Set to "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(1,32) | The acquirer merchant ID (MID) |
AcquirerPOIID | ✔ | String(1,16) | The acquirer terminal ID (TID) |
AcquirerTransactionID | ✔ | Object | |
TransactionID | ✔ | String(1,128) | The acquirer transaction ID |
TimeStamp | ✔ | ISO8601 | Timestamp from the acquirer, formatted as ISO8601 |
ApprovalCode | ✔ | String(0,64) | The Acquirer Approval Code. Also referred to as the Authentication Code |
ResponseCode | ✔ | String(0,8) | The Acquirer Response Code. Also referred as the PINPad response code |
STAN | String(1,32) | The Acquirer STAN if available | |
RRN | String(1,32) | The Acquirer RRN if available | |
HostReconciliationID | ✔ | String(1,32) | Identifier of a reconciliation period with the acquirer. This normally has a date and time component in it |
CurrentBalance | Currency(0,999999.99) | If relevant and known | |
Currency | String(3,3) | If CurrentBalance is relevant and known, the three character ISO 4217 formatted currency code. Set to "AUD". | |
AllowedProductCodes | Array(String) | 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(Object) | Array of payment receipt objects which represent receipts to be printed | |
DocumentQualifier | ✔ | Enum | "CashierReceipt" for a merchant receipt, otherwise "SaleReceipt" |
RequiredSignatureFlag | ✔ | Boolean | If true, the card holder signature is required on the merchant CashierReceipt. |
OutputContent | Array(Object) | Array of payment receipt objects which represent receipts to be printed | |
OutputFormat | ✔ | String(0,32) | "XHTML" |
OutputXHTML | ✔ | String(0,4096) | The payment receipt in XHTML format but coded in BASE64 |
Display request
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
Display request
{
"DisplayRequest": {
"DisplayOutput": {
"ResponseRequiredFlag": false,
"Device": "CashierDisplay",
"InfoQualify": "xxx",
"OutputContent": {
"OutputFormat": "Text",
"OutputText": {
"Text": "xxx"
}
}
}
}
}
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 | ✔ | Enum | "CashierDisplay" |
InfoQualify | ✔ | Enum | "Status" or "Error". See InfoQualify |
OutputFormat | ✔ | String(0,32) | "Text" |
Text | ✔ | String(1,256) | Single line of text to display |
Display response
Display response
{
"DisplayResponse": {
"OutputResult": [
{
"Device": "xxx",
"InfoQualify": "xxx",
"Response": {
"Result": "xxx",
"ErrorCondition": "xxx",
"AdditionalResponse": "xxx"
}
}
]
}
}
The Sale System is expected to send a DisplayResponse
if one or more displays in DisplayOutput
have ResponseRequiredFlag set to true.
Attributes | Requ. | Format | Description |
---|---|---|---|
OutputResult | ✔ | Object | Response for Device/InfoQualify pair where corresponding ResponseRequiredFlag in the DisplayRequest is set to true. |
Device | ✔ | String(1,128) | Mirrored from display request |
InfoQualify | ✔ | Enum | Mirrored from display request |
Result | ✔ | Enum | "Success", "Partial", or "Failure". See Result. |
ErrorCondition | String(0,256) | Indicates the reason an error occurred. Only present when Result is "Failure". See ErrorCondition for more information on possible values. | |
AdditionalResponse | String(0,1024) | Provides additional error information. Only present when Result is "Failure". See AdditionalResponse for more information on possible values. |
Input
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
Input request
{
"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"
}
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
DisplayOutput | Object | Information to display and the way to process the display. | |
Device | ✔ | Enum | "CashierDisplay" |
InfoQualify | ✔ | Enum | "POIReplication". See InfoQualify |
OutputContent | ✔ | Object | |
OutputFormat | ✔ | String(0,32) | "Text" |
OutputText | ✔ | Object | Wrapper for text content |
Text | ✔ | String(1,256) | Single line of text. e.g. "Signature Ok?", "Merchant Password", "Select Account Type" |
MenuEntry | Array(Object) | Conditional. Array of items to be presented as a menu. Only present if InputCommand = "GetMenuEntry" | |
OutputFormat | ✔ | String(0,32) | "Text" |
Text | ✔ | String(1,256) | 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 | ✔ | Enum | "CashierInput" |
InfoQualify | ✔ | Enum | "Input" or "CustomerAssistance". See InfoQualify |
InputCommand | ✔ | Enum | "GetConfirmation", "Password", "TextString", "DigitString", "DecimalString", or "GetMenuEntry". See InputCommand |
MaxInputTime | Integer(1,999) | 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 | Integer(1,999) | The minimum number of characters allowed for entry. Present if InputCommand = "Password", "TextString", "DigitString", or "DecimalString" | |
MaxLength | Integer(1,999) | 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
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":{...}
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
OutputResult | Object | Present if DisplayOutput is present in the request | |
Device | ✔ | Enum | Mirrored from input request |
InfoQualify | ✔ | String(1,128) | Mirrored from input request |
Response | ✔ | Object | |
Result | ✔ | Enum | "Success", "Partial", or "Failure". See Result. |
ErrorCondition | String(0,256) | Indicates the reason an error occurred. Only present when Result is "Failure". See ErrorCondition for more information on possible values. | |
AdditionalResponse | String(0,1024) | 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(1,128) | Mirrored from input request |
InfoQualify | ✔ | Enum | Mirrored from input request |
Response | ✔ | Object | |
Result | ✔ | Enum | "Success", "Partial", or "Failure". See Result. |
ErrorCondition | String(0,256) | Indicates the reason an error occurred. Only present when Result is "Failure". See ErrorCondition for more information on possible values. | |
AdditionalResponse | String(0,1024) | 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" | |
MenuEntryNumber | Integer(1,999) | 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(1,1024) | Value entered by the Cashier. Mandatory, if InputCommand is "TextString" or "DecimalString". Not allowed, otherwise | |
DigitInput | Decimal(0,999999.99) | Value entered by the Cashier. Mandatory, if InputCommand is "DigitString". 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.
The Sale System does not need to implement the Print request as signature receipt printing is currently managed by the POI Terminal.
Print request
Print request
{
"PrintRequest": {
"PrintOutput": {
"DocumentQualifier": "CashierReceipt",
"IntegratedPrintFlag": false,
"RequiredSignatureFlag": true,
"OutputContent": {
"OutputFormat": "XHTML",
"OutputXHTML": "xxxx"
}
}
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
PrintOutput | ✔ | Object | |
DocumentQualifier | ✔ | Enum | "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(Object) | Array of payment receipt objects which represent receipts to be printed | |
OutputFormat | ✔ | String(0,32) | "XHTML" |
OutputXHTML | ✔ | String(0,4096) | The payment receipt in XHTML format but coded in BASE64 |
Print response
Print response
{
"PrintResponse": {
"DocumentQualifier": "CashierReceipt",
"Response": {
"Result": "xxx",
"ErrorCondition": "xxx",
"AdditionalResponse": "xxx"
}
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
DocumentQualifier | ✔ | Enum | Mirrored from print request |
Response | ✔ | Object | |
Result | ✔ | Enum | "Success", "Partial", or "Failure". See Result. |
ErrorCondition | String(0,256) | Indicates the reason an error occurred. Only present when Result is "Failure". See ErrorCondition for more information on possible values. | |
AdditionalResponse | String(0,1024) | 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
Transaction status request
{
"TransactionStatusRequest": {
"MessageReference": {
"MessageCategory": "xxx",
"ServiceID": "xxx",
"SaleID": "xxx",
"POIID": "xxx"
}
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
MessageReference | Object | Identification of a previous POI transaction. Present if it contains any data. | |
MessageCategory | Enum | "Payment" | |
ServiceID | UUID | The ServiceID of the transaction to retrieve the status of. If not included the last payment status is returned. | |
SaleID | String(1,128) | The SaleID of the transaction to retrieve the status of. Only required if different from the SaleID provided in the MessageHeader | |
POIID | String(1,128) | The POIID of the transaction to retrieve the status of. Only required if different from the POIID provided in the MessageHeader |
Transaction status response
Transaction status response
{
"TransactionStatusResponse": {
"Response": {
"Result": "xxx",
"ErrorCondition": "xxx",
"AdditionalResponse": "xxx"
},
"MessageReference": {
"MessageCategory": "xxx",
"ServiceID": "xxx",
"SaleID": "xxx",
"POIID": "xxx"
},
"RepeatedMessageResponse": {
"MessageHeader": {},
"RepeatedResponseMessageBody": {
"PaymentResponse": {},
"ReversalResponse": {}
}
}
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
Response | ✔ | Object | Object indicating the result of the payment |
Result | ✔ | Enum | Indicates the result of the response. Possible values are "Success" and "Failure" |
ErrorCondition | String(0,256) | Indicates the reason an error occurred. Only present when Result is "Failure". See ErrorCondition for more information on possible values. | |
AdditionalResponse | String(0,1024) | 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 | ✔ | Enum | Mirrored from request |
ServiceID | ✔ | UUID | Mirrored from request, or ServiceID of last transaction if not present in request. |
SaleID | String(1,128) | Mirrored from request, but only if present in the request | |
POIID | String(1,128) | 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.
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
Abort transaction request
{
"AbortRequest": {
"MessageReference": {
"MessageCategory": "xxx",
"ServiceID": "xxxx",
"SaleID": "xxx",
"POIID": "xxx"
},
"AbortReason": "xxx"
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
MessageReference | ✔ | Object | Identification of a POI transaction |
MessageCategory | ✔ | Enum | "Payment" or "CardAcquisition" |
ServiceID | ✔ | UUID | The ServiceID of the transaction to cancel |
SaleID | String(1,128) | The SaleID of the transaction to cancel. Only required if different from the SaleID provided in the MessageHeader | |
POIID | String(1,128) | The POIID of the transaction to cancel. Only required if different from the POIID provided in the MessageHeader | |
AbortReason | ✔ | String(1,256) | 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
{
"EventNotification": {
"TimeStamp": "xxx",
"EventToNotify": "xxx",
"EventDetails": "xxx"
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
TimeStamp | ✔ | ISO8601 | Time of the event on the POI System, formatted as ISO8601 |
EventToNotify | ✔ | Enum | "Reject" if the abort request cannot be accepted (e.g. message format error, ServiceId not found). "CompletedMessage" if payment has already completed. |
EventDetails | ✔ | String(1,1024) | Extra detail on the reason for the event |
Reconciliation
Reconciliation request
Reconciliation request
{
"ReconciliationRequest": {
"ReconciliationType": "xxx",
"POIReconciliationID": "xxx"
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
ReconciliationType | ✔ | Enum | "SaleReconciliation" to close the current period, "PreviousReconciliation" to request the result of a previous reconciliation |
POIReconciliationID | String(1,128) | Present if ReconciliationType is "PreviousReconciliation". See POIReconciliationID |
Reconciliation response
Reconciliation response
{
"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"
}
]
}
]
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
Response | ✔ | Object | Object indicating the result of the login |
Result | ✔ | Enum | Indicates the result of the response. Possible values are "Success" and "Failure" |
ErrorCondition | String(0,256) | Indicates the reason an error occurred. Only present when Result is "Failure". See ErrorCondition for more information on possible values. | |
AdditionalResponse | String(0,1024) | Provides additional error information. Only present when Result is "Failure". See AdditionalResponse for more information on possible values. | |
ReconciliationType | ✔ | Enum | Mirrored from request |
POIReconciliationID | String(1,128) | Present if Result is "Success". The ReconciliationID of the period requested | |
TransactionTotals | Array(Object) | Present if Result is "Success". An array of totals grouped by card brand, then operator, then shift, then TotalsGroupID, then payment currency. | |
PaymentInstrumentType | ✔ | Enum | "Card" (card payment) or "Mobile" (phone/QR code payments) |
CardBrand | String(1,128) | A card brand used during this reconciliation period | |
OperatorID | String(1,128) | An operator id used during this reconciliation period | |
ShiftNumber | String(1,128) | A shift number used during the reconciliation period | |
TotalsGroupID | String(1,128) | A custom grouping of transactions as defined by the Sale System | |
PaymentCurrency | String(3,3) | Three character (ISO 4217 formatted) currency code. Set to "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
Card acquisition request
{
"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"
}
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
SaleData | ✔ | Object | Object Sale System information attached to this payment |
OperatorID | String(1,128) | Only required if different from Login Request | |
OperatorLanguage | String(2,8) | Set to "en" | |
ShiftNumber | String(1,128) | Only required if different from Login Request | |
CustomerLanguage | String(2,8) | Set to "en" for English | |
TokenRequestedType | ✔ | Enum | "Customer" |
SaleTransactionID | Object | ||
TransactionID | ✔ | String(1,128) | Unique reference for this sale ticket |
TimeStamp | ✔ | ISO8601 | 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 | Enum | "Attended", "SemiAttended", or "Unattended" | |
SaleCapabilities | Array(Enum) | 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(String) | Restricts the request to specified card brands. See AllowedPaymentBrand | |
ForceEntryMode | Enum | If present, restricts card presentment to the specified type. See ForceEntryMode |
Card acquisition response
Card acquisition response
{
"CardAcquisitionResponse": {
"Response": {
"Result": "xxx",
"ErrorCondition": "xxx",
"AdditionalResponse": "xxx"
},
"SaleData": {
"SaleTransactionID": {
"TransactionID": "xxx",
"TimeStamp": "xxx"
}
},
"POIData": {
"POITransactionID": {
"TransactionID": "xxx",
"TimeStamp": "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"
}
},
"PaymentToken": {
"TokenRequestedType": "xxx",
"TokenValue": "xxx",
"ExpiryDateTime": "xxx"
}
}
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
Response | ✔ | Object | Object indicating the result of the login |
Result | ✔ | Enum | Indicates the result of the response. Possible values are "Success" and "Failure" |
ErrorCondition | String(0,256) | Indicates the reason an error occurred. Only present when Result is "Failure". See ErrorCondition for more information on possible values. | |
AdditionalResponse | String(0,1024) | Provides additional error information. Only present when Result is "Failure". See AdditionalResponse for more information on possible values. | |
SaleData | ✔ | Object | |
SaleTransactionID | ✔ | Object | |
TransactionID | ✔ | String(1,128) | Mirrored from the request |
TimeStamp | ✔ | ISO8601 | Mirrored from the request |
SaleReferenceID | String(1,128) | Mirrored from the request | |
POIData | ✔ | Object | |
POITransactionID | ✔ | Object | |
TransactionID | ✔ | String(1,128) | A unique transaction id from the POI system |
TimeStamp | ✔ | ISO8601 | Time on the POI system, formatted as ISO8601 |
PaymentInstrumentData | Object | Object with represents card details for token or manually enter card details. | |
PaymentInstrumentType | Enum | Defaults to "Card". Indicates the card source for the payment. See PaymentInstrumentType | |
CardData | Object | ||
EntryMode | Enum | Only present if PaymentInstrumentType is "Card". "File" if a Payment Token is used, and "Keyed" for a Card Not Present transaction. | |
MaskedPAN | ✔ | String(1,64) | 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(1,128) | Token previously returned from the POI System in the payment, or card acquisition response |
Stored value
The stored value request/response is used for managed stored value cards.
Stored value request
Stored value request
{
"StoredValueRequest": {
"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"
},
"StoredValueData": [
{
"StoredValueProvider": "",
"StoredValueTransactionType":"Reserve | Activate | Load | Unload | Reverse | Duplicate",
"StoredValueAccountID": {
"StoredValueAccountType": "GiftCard | PhoneCard | Other",
"StoredValueProvider": "",
"OwnerName": "",
"ExpiryDate": "MMYY",
"EntryMode": "",
"IdentificationType": "",
"StoredValueID": ""
},
"OriginalPOITransaction": {
"SaleID": "xxx",
"POIID": "xxx",
"POITransactionID": {
"TransactionID": "xxx",
"TimeStamp": "xxx"
},
"ReuseCardDataFlag": true,
"ApprovalCode": "xxx",
"LastTransactionFlag": true
},
"ProductCode": "xxx",
"EanUpc": "xxx",
"ItemAmount": "xx.x",
"TotalFeesAmount": "xx.x",
"Currency": "",
}
]
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
SaleData | ✔ | Object | Sale System information attached to this payment |
OperatorID | String(1,128) | Only required if different from Login Request | |
OperatorLanguage | String(2,8) | Set to "en" | |
ShiftNumber | String(1,128) | Only required if different from Login Request | |
SaleReferenceID | String(1,128) | Mandatory for pre-authorisation and completion, otherwise optional. See SaleReferenceID | |
TokenRequestedType | Enum | If present, indicates which type of token should be created for this payment. See TokenRequestedType | |
SaleTransactionID | ✔ | Object | |
TransactionID | ✔ | String(1,128) | 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 | ✔ | ISO8601 | 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 | Enum | "Attended", "SemiAttended", or "Unattended" | |
SaleCapabilities | Array(Enum) | Advises the POI System of the Sale System capabilities. See SaleCapabilities | |
TotalsGroupId | String(1,256) | Groups transactions in a login session | |
StoredValueData | ✔ | Array(Object) | Data related to the stored value card. |
StoredValueProvider | String(1,256) | Identification of the provider of the stored value account. | |
StoredValueTransactionType | ✔ | Enum | Identification of operation to proceed on the stored value account or the stored value card |
StoredValueAccountID | Object | Present if the card presented was a gift card / stored value card | |
StoredValueAccountType | ✔ | Enum | Type of stored value account. GiftCard |
StoredValueProvider | String(1,256) | Identification of the provider of the stored value account. | |
OwnerName | String(1,256) | If available, the name of the owner of a stored value account. | |
ExpiryDate | String(4,4) | If present, the date after which the card cannot be used. Format is MMYY. | |
EntryMode | Enum | Indicates how the payment type was presented. | |
IdentificationType | ✔ | Enum | Type of account identification contained in StoredValueID. Values are PAN |
StoredValueID | ✔ | String(128) | Stored value account identification |
OriginalPOITransaction | Object | Identifies a previous POI transaction. Mandatory for Refund and Completion. See OriginalPOITransaction | |
SaleID | ✔ | String(1,128) | SaleID which performed the original transaction |
POIID | ✔ | String(1,128) | POIID which performed the original transaction |
POITransactionID | ✔ | Object | |
TransactionID | ✔ | String(1,128) | TransactionID from the original transaction |
TimeStamp | ✔ | ISO8601 | TimeStamp from the original transaction |
ProductCode | String(1,128) | 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(1,128) | A standard unique identifier for the product. Either the UPC, EAN, or ISBN. Required for products with a UPC, EAN, or ISBN | |
ItemAmount | Currency(0.01,999999.99) | Indicates the amount to be loaded onto the account. Exclusive of fees. | |
TotalFeesAmount | Decimal | Total of fees associated with the transaction | |
Currency | ✔ | String(3,3) | Three character (ISO 4217 formatted) currency code. Set to "AUD". |
Stored value response
Stored value response
{
"StoredValueResponse": {
"Response": {
"Result": "Success | Failure",
"ErrorCondition": "xxx",
"AdditionalResponse": "xxx"
},
"SaleData": {
"SaleTransactionID": {
"TransactionID": "xxx",
"TimeStamp": "xxx"
},
},
"POIData": {
"POITransactionID": {
"TransactionID": "xxx",
"TimeStamp": "xxx"
},
"POIReconciliationID": "xxx"
},
"StoredValueResult": [
{
"StoredValueTransactionType":"Reserve | Activate | Load | Unload | Reverse | Duplicate",
"ProductCode": "xxx",
"EanUpc": "xxx",
"ItemAmount": "xx.x",
"TotalFeesAmount": "xx.x",
"Currency": "",
"StoredValueAccountStatus": {
"StoredValueAccountID": {
"StoredValueAccountType": "GiftCard | PhoneCard | Other",
"StoredValueProvider": "",
"OwnerName": "",
"ExpiryDate": "MMYY",
"EntryMode": "",
"IdentificationType": "",
"StoredValueID": ""
},
"CurrentBalance": 0.00,
},
}
],
"PaymentReceipt": [
{
"DocumentQualifier": "xxx",
"RequiredSignatureFlag": true,
"OutputContent": {
"OutputFormat": "XHTML",
"OutputXHTML": "xxx"
}
}
]
}
}
Attributes | Requ. | Format | Description |
---|---|---|---|
Response | ✔ | Object | Object indicating the result of the login |