Fusion Satellite

The Fusion Satellite API allows a Sale System running on the POI terminal to communicate with the DataMesh Satellite payment application on the same POI terminal using inter-app communication with Android intents.

Libraries

DataMesh have published a library to Maven Central which wraps the Satellite API. This is the recommended method of interacting with the Fusion Satellite API.

Description	Location
Library	on Maven Central
Library	on GitHub
Demo Application utilising the library	on GitHub	Tested on PAX (PAX 920)
Another POS on Pinpad Demo Application	on GitHub	Tested on PAX (PAX 920) and Ingenico (DX8000)

How to include the library

implementation "com.datameshgroup.fusion:fusion-sdk:1.3.4"

If you are using Android you will need to add Java 8 syntax desugaring. In your app's build.gradle

android {
	compileOptions {
		sourceCompatibility JavaVersion.VERSION_1_8
		targetCompatibility JavaVersion.VERSION_1_8
		coreLibraryDesugaringEnabled true
	}
}
dependencies {
	coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.1.5'
}

Device Specific Changes

If your Sale System on Pinpad uses the device(s) listed below, the following changes need to be included in your application:

Printer

If your Sale System on Pinpad only supports PAX:

• Modify the App Manifest file to add the following permission:
  <uses-permission android:name="com.pax.permission.PRINTER" />

If your Sale System on Pinpad supports Ingenico or

If your Sale System on Pinpad supports both Ingenico and PAX:

Since not all the required changes specific to your application may be listed below, please refer to the POS on Pinpad Demo Application code in GitHub. This POS on Pinpad Demo Application code in GitHub has been tested in both Ingenico (DX8000) and PAX (PAX 920)

Please only copy the code/files relevant to the device(s) that you support.(e.g. copy only the relevant Ingenico code/file(s) if you only support Ingenico)

• Add the relevant Library Files
• Add the relevant device specific files:
  • Ingenico
  • PAX
• Add the DeviceInterface.java file and its references to your code.
• Update your app's build.gradle

    flavorDimensions 'device'
    productFlavors {
        pax {
            dimension "device"
            applicationId = "you_application_id_here"
            buildConfigField 'boolean', 'DEVICE_PAX', 'true'
            buildConfigField 'boolean', 'DEVICE_IGO', 'false'
            buildConfigField 'String', 'VERSION_TYPE', "\"v1\""

        }
        ingenico {
            dimension "device"
            applicationId = "you_application_id_here"
            buildConfigField 'boolean', 'DEVICE_PAX', 'false'
            buildConfigField 'boolean', 'DEVICE_IGO', 'true'
            buildConfigField 'String', 'VERSION_TYPE', "\"v1\""
        }
    }

Sending messages

The Satellite API utilises an Android intent with request/response objects based on the Nexo SaleToPOIRequest and SaleToPOIResponse

Sample code for Sending a Payment Request

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

Method Name	GitHub File	GitHub Repository
sendPaymentRequest	ActivityPayment.java	pos-on-pinpad-demo

Intent request

The app uses intents to send and receive messages

Intent intent = new Intent(Message.INTENT_ACTION_SALETOPOI_REQUEST);

// All messages to and from the terminal are wrapped inside a Message object.
// Here request is a SaleToPOIRequest object.
Message message = new Message(request);

intent.putExtra(Message.INTENT_EXTRA_MESSAGE, message.toJson());
// name of this app, that get's treated as the POS label by the terminal.
intent.putExtra(Message.INTENT_EXTRA_APPLICATION_NAME, "DemoPOS");
intent.putExtra(Message.INTENT_EXTRA_APPLICATION_VERSION, "1.0.0");

// we are using 100 as the request code - but you can use anything you want.
startActivityForResult(intent, 100);

Intent response

In the same activity, add the following code.

@Override
protected void onActivityResult(int requestCode, int responseCode, Intent data){
    super.onActivityResult(requestCode, responseCode, data);
    if(data != null && data.hasExtra(Message.INTENT_EXTRA_MESSAGE)) {
        this.handleResponseIntent(data);
    }
}

void handleResponseIntent(Intent intent){
    // The response is sent as a Json and we will need to deserialize it.
    Message message = null;
    try{
        message = Message.fromJson(intent.getStringExtra(Message.INTENT_EXTRA_MESSAGE));
    } catch(Exception e){
        // json errors may occur,
        // if this is occuring, make sure you are using the latest fusion-sdk library
        return;
    }
    SaleToPOIResponse response = message.response;
    // we can now access the data.
}

Request/response object

SaleToPOIRequest

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

SaleToPOIResponse

{
  "SaleToPOIResponse": {
    "MessageHeader":{...},
    "LoginRequest":{...}
  }
}

All messages use JSON format with UTF-8 encoding.

Supported primitive data elements are:

1. String text string of variable length
2. Boolean true or false
3. 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.
4. 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 two objects:

1. A MessageHeader object.
2. A Payload object of variable types.

MessageHeader

MessageHeader

"MessageHeader":{
  "MessageClass":"",
  "MessageCategory":"",
  "MessageType":"",
  "ServiceID":""
}

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

Attributes	Requ.	Format	Description
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.

Payload

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

e.g. a payment will include a PaymentRequest/PaymentResponse.

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

Methods

Payment

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

Payment request

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"
            }
         ]
      }
   }
}

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.

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. Inlude this in the request if you want the Tip handled on your app. Otherwise, if you want to show the Tip Prompt via Satellite, do not include this parameter in the request.
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", "CashAdvance", "FirstReservation", or "Completion". 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

Payment response

{
   "SaleToPOIResponse":{
      "MessageHeader":{
         "MessageClass":"Service",
         "MessageCategory":"Payment",
         "MessageType":"Response",
         "ServiceID":"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",
				  "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"
               }
            }
         ]
      }
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"Payment"
MessageType	✔	String	"Response"
ServiceID	✔	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	Indicates the card type used. See PaymentBrand
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		Object	Payment receipt object which represents the receipt that needs to be printed
OutputFormat	✔	String	"XHTML"
OutputXHTML	✔	String	The payment receipt in XHTML format but coded in BASE64

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

{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "MessageClass":"Service",
         "MessageCategory":"TransactionStatus",
         "MessageType":"Request",
         "ServiceID":"xxx"
      },
      "TransactionStatusRequest":{
         "MessageReference":{
            "MessageCategory":"xxx",
            "ServiceID":"xxx"
         }
      }
   }
}

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.

TransactionStatusRequest

Attributes	Requ.	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.

Transaction status response

Transaction status response

{
   "SaleToPOIResponse":{
      "MessageHeader":{
         "MessageClass":"Service",
         "MessageCategory":"TransactionStatus",
         "MessageType":"Response",
         "ServiceID":"xxx"
      },
      "TransactionStatusResponse":{
         "Response":{
            "Result":"xxx",
            "ErrorCondition":"xxx",
            "AdditionalResponse":"xxx"
         },
         "MessageReference":{
            "MessageCategory":"xxx",
            "ServiceID":"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

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.
RepeatedMessageResponse		Object	Present if Result is "Success"
MessageHeader	✔	Object	MessageHeader of the requested payment
PaymentResponse	✔	Object	PaymentResponse of the requested payment

Void/Reversal

A successful payment transaction can be voided/reversed by sending a reversal request message.

warning

There are only specific cases wherein the reversal request message must be sent. In most cases, refund request message should be sent instead.

Please discuss first with the DataMesh Integrations team at integrations@datameshgroup.com if you plan to implement any void/reversal processing.

When the Sale System receives the successful payment response, the Sale System needs to store the TransactionID (Response.POIData.POITransactionID.TransactionID) since this will be used in the reversal request message.

Reversal request

The reversal message is used to perform void/reversal request.

Reversal request

{
	"SaleToPOIRequest": {
		"MessageHeader": {
			"MessageCategory": "Reversal",
			"MessageClass": "Service",
			"MessageType": "Request",
			"ProtocolVersion": "3.1-dmg",
			"ServiceID": "xxx"
		},
		"ReversalRequest": {
			"OriginalPOITransaction": {
				"ReuseCardDataFlag": true,
				"POIID": "xxx",
				"POITransactionID": {
					"TimeStamp": "xxx",
					"TransactionID": "xxx" //This should be the set to the TransactionID in the Original Successful Payment Response
				},
				"SaleID": "xxx"
			},
			"ReversalReason": "SignatureDeclined"// (e.g. CustCancel, MerchantCancel, Malfunction, Unable2Compl, SignatureDeclined, Unknown)
		}
	}
}

MessageHeader

Attributes	Requ.	Format	Description
MessageClass	✔	String	"Service"
MessageCategory	✔	String	"Reversal"
MessageType	✔	String	"Request"
ProtocolVersion	✔	String	"3.1-dmg"
ServiceID	✔	String	A unique value which will be mirrored in the response. See ServiceID.

ReversalRequest

Attributes	Requ.	Format	Description
OriginalPOITransaction	✔	Object	Identifies a previous POI transaction. See OriginalPOITransaction
SaleID	✔	String	SaleID which performed the original transaction
POIID	✔	String	POIID which performed 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.
POITransactionID	✔	Object
TransactionID	✔	String	TransactionID from the original transaction
TimeStamp	✔	String	TimeStamp from the original transaction
ReversalReason	✔	Object	Reason for cancelling the successful payment transaction. See ReversalReason

Reversal response

Reversal response

{
	"SaleToPOIResponse": {
		"MessageHeader": {
			"MessageCategory": "Reversal",
			"MessageClass": "Service",
			"MessageType": "Response",
			"POIID": "xxx",
			"ProtocolVersion": "3.1-dmg",
			"ServiceID": "xxx"
		},
		"ReversalResponse": {
			"POIData": {
				"POITransactionID": {
					"TimeStamp": "xxx",
					"TransactionID": "xxxx"
				}
			},
			"PaymentReceipt": [
				{
					"DocumentQualifier": "SaleReceipt",
					"OutputContent": {
						"OutputFormat": "XHTML",
						"OutputXHTML": "xxx"
					},
					"RequiredSignatureFlag": false
				},
				{
					"DocumentQualifier": "CashierReceipt",
					"OutputContent": {
						"OutputFormat": "XHTML",
						"OutputXHTML": "xxx"
					},
					"RequiredSignatureFlag": false
				}
			],
			"Response": {
				"Result": "Success"
			}
		}
	}
}

MessageHeader

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

ReversalResponse

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.
POIData	✔	Object
POITransactionID	✔	Object
TransactionID	✔	String	A unique transaction id from the POI system
TimeStamp	✔	String	Time on the POI system, formatted as ISO8601
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		Object	Payment receipt object which represents the receipt that needs to be printed
OutputFormat	✔	String	"XHTML"
OutputXHTML	✔	String	The payment receipt in XHTML format but coded in BASE64