Skip to main content

Fusion App

Fusion App is a DataMesh middleware that is installed in the PC as the Sale System.

Fusion App wraps the Fusion Cloud API and handles many of the interactions between the Sale System and the POI terminal (web socket, security, pairing, error handling, UI etc).

There are two ways on how the Fusion App communicates with the POI terminal:

  • Cloud - Fusion App communicates with the POI terminal via a Websocket connected to the DataMesh Unify switch.

  • USB Connection

    • Base USB Connection - Fusion App communicates with the POI terminal through a USB cable connected to the POI terminal’s Base/Dock device. The POI terminal must be paired with its Base/Dock device.
    • Terminal USB Connection - Fusion App communicates with the POI terminal through a USB cable connected directly to the POI terminal.

There are two methods for processing a payment using Fusion App:

  • Events mode - the Sale System sends a HTTP POST to a local endpoint, and if valid receives 202 ACCEPTED. The Sale System polls Fusion App, processing events received until the payment response is returned.
  • Blocking - the Sale System sends a HTTP POST to a local endpoint, and waits for a response. If successful (200 OK) the response will contain the payment response details.

In both methods, in case of an error (timeout, system crash etc), the Sale System sends a HTTP GET request to request the status of the payment.

success

When possible, events mode should always be used over blocking mode as it enables more flexible transaction event handling.

Reference code​

DescriptionLocation
Demo Application implementing the Fusion Appon GitHub

Getting started with Fusion App​

Install Fusion App​

info

The latest dev release Fusion App installer can be downloaded from this link.

  • Run the installer and select the Development install type.

    (For installation in Production environment, select Production.)

  • Wait for the installation to complete and click Finish

Configure Fusion App​

  • Launch Fusion App from the icon in the system tray.

  • The Status tab displays the terminal pairing status.

  • You can pair a terminal by clicking on the Pair with terminal button.

  • Before selecting the pairing mode to be used, please make sure that the connection required for the specific pairing mode has been set-up.

Pairing ModeDescription
USB (Base)Fusion App communicates with the POI terminal through a USB cable connected to the POI terminal’s Base/Dock device. The POI terminal must be paired with its Base/Dock device.
USB (Terminal)Fusion App communicates with the POI terminal through a USB cable connected directly to the POI terminal.
CloudFusion App communicates with the POI terminal via a Websocket connected to the DataMesh Unify switch.

If the version of Fusion App that you're using doesn't display a prompt to select the pairing mode, Fusion App will use Cloud as the default pairing mode.

  • The main pairing dialog will then ask you to scan the pairing QR Code using the DataMesh terminal.

  • When the Fusion App has been paired with a terminal, the paired terminal's POI ID will be displayed. Only when necessary, you can unpair from the terminal by clicking on the Unpair from terminal option.

    • USB (Base)

    • USB (Terminal)

    • Cloud

  • The Util tab will allow you to:

    • update the POS Name (which is used during QR Code Pairing).
      • If the Fusion App has been paired with a terminal before the POS name was updated, you'll need to unpair from the terminal and then, pair with the terminal again to use the updated POS name.
    • perform a login
    • access log files

DataMesh may ask for log files to diagnose issues during development.

Send your first payment request​

  • Download and install Postman
  • Import the Fusion App postman script:
    • In Postman, select Menu(☰) → File → Import...
    • Browse to %PROGRAMFILES(X86)%\DataMeshGroup\FusionApp\FusionApp.postman_collection.json and import
  • Select Collections → Payments (blocking) → Payment, and click Send

Next steps​

Perform a purchase (events mode)​

To perform a purchase with events mode, the Sale System will need to POST a Payment request JSON payload to the http://localhost:4242/fusion/v1/payments endpoint.

  • Construct a Payment request JSON payload including all required fields
  • Create a globally unique UUIDv4 SessionId. This will be used to uniquely identify the payment and perform error recovery.
  • POST the JSON payload to http://localhost:4242/fusion/v1/payments/{{SessionId}}events=true
    • Set the Content-Type header to application/json
    • Set the X-Application-Name header to the name of your Sale System
    • Set the X-Software-Version header to the software version of your Sale System
    • Set the message body to the Payment request JSON payload
  • Await the POST result (this should take under 5 seconds).
    • On 4xx the request was invalid and the payment could not be processed
    • On 5xx an error occured, the Sale System should enter error handling
    • On 202 ACCEPTED, the Sale System should GET the payment result
  • Call GET http://localhost:4242/fusion/v1/payments/{{SessionId}}/events using the SessionId from the POST payment to get the next event in the payment (this could take as long as 5 minutes). Fusion App will return a SaleToPOIResponse containing the Payment response, or a SaleToPOIRequest containing the Print request
  • If the Sale System does not receive a POST result (i.e. timeout, socket dropped, system crash etc) implement error handling outlined in error handling

Perform a purchase (blocking mode)​

To perform a purchase, the Sale System will need to POST a Payment request JSON payload to the http://localhost:4242/fusion/v1/payments endpoint.

  • Construct a Payment request JSON payload including all required fields
  • Create a globally unique UUIDv4 SessionId. This will be used to uniquely identify the payment and perform error recovery.
  • POST the JSON payload to http://localhost:4242/fusion/v1/payments/{{SessionId}}
    • Set the Content-Type header to application/json
    • Set the X-Application-Name header to the name of your Sale System
    • Set the X-Software-Version header to the software version of your Sale System
    • Set the message body to the Payment request JSON payload
  • Await the POST result (this could take as long as 5 minutes). Fusion App will return a Payment response in the message body
  • If the Sale System does not receive a POST result (i.e. timeout, socket dropped, system crash etc) implement error handling outlined in error handling

Perform a cash out (events mode)​

To perform a cash out with events mode, the Sale System will need to POST a Payment request JSON payload to the http://localhost:4242/fusion/v1/payments endpoint.

  • Construct a Payment request JSON payload including all required fields
  • Create a globally unique UUIDv4 SessionId. This will be used to uniquely identify the payment and perform error recovery.
  • POST the JSON payload to http://localhost:4242/fusion/v1/payments/{{SessionId}}events=true
    • Set the Content-Type header to application/json
    • Set the X-Application-Name header to the name of your Sale System
    • Set the X-Software-Version header to the software version of your Sale System
    • Set the message body to the Payment request JSON payload
  • Await the POST result (this should take under 5 seconds).
    • On 4xx the request was invalid and the payment could not be processed
    • On 5xx an error occured, the Sale System should enter error handling
    • On 202 ACCEPTED, the Sale System should GET the payment result
  • Call GET http://localhost:4242/fusion/v1/payments/{{SessionId}}/events using the SessionId from the POST payment to get the next event in the payment (this could take as long as 5 minutes). Fusion App will return a SaleToPOIResponse containing the Payment response, or a SaleToPOIRequest containing the Print request
  • If the Sale System does not receive a POST result (i.e. timeout, socket dropped, system crash etc) implement error handling outlined in error handling

Perform a cash out (blocking mode)​

To perform a cash out, the Sale System will need to POST a Payment request JSON payload to the http://localhost:4242/fusion/v1/payments endpoint.

  • Construct a Payment request JSON payload including all required fields
  • Create a globally unique UUIDv4 SessionId. This will be used to uniquely identify the payment and perform error recovery.
  • POST the JSON payload to http://localhost:4242/fusion/v1/payments/{{SessionId}}
    • Set the Content-Type header to application/json
    • Set the X-Application-Name header to the name of your Sale System
    • Set the X-Software-Version header to the software version of your Sale System
    • Set the message body to the Payment request JSON payload
  • Await the POST result (this could take as long as 5 minutes). Fusion App will return a Payment response in the message body
  • If the Sale System does not receive a POST result (i.e. timeout, socket dropped, system crash etc) implement error handling outlined in error handling

Perform a refund (events mode)​

To perform a refund with events mode, the Sale System will need to POST a Payment request JSON payload to the http://localhost:4242/fusion/v1/payments endpoint.

tip

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

  • Construct a Payment request JSON payload including all required fields
  • Create a globally unique UUIDv4 SessionId. This will be used to uniquely identify the payment and perform error recovery.
  • POST the JSON payload to http://localhost:4242/fusion/v1/payments/{{SessionId}}?events=true
    • Set the Content-Type header to application/json
    • Set the X-Application-Name header to the name of your Sale System
    • Set the X-Software-Version header to the software version of your Sale System
    • Set the message body to the Payment request JSON payload
  • Await the POST result (this should take under 5 seconds).
    • On 4xx the request was invalid and the payment could not be processed
    • On 5xx an error occured, the Sale System should enter error handling
    • On 202 ACCEPTED, the Sale System should GET the payment result
  • Call GET http://localhost:4242/fusion/v1/payments/{{SessionId}}/events using the SessionId from the POST payment to get the next event in the payment (this could take as long as 5 minutes). Fusion App will return a SaleToPOIResponse containing the Payment response, or a SaleToPOIRequest containing the Print request
  • If the Sale System does not receive a POST result (i.e. timeout, socket dropped, system crash etc) implement error handling outlined in error handling

Perform a refund (blocking mode)​

To perform a purchase the Sale System will need to POST a Payment request JSON payload to the http://localhost:4242/fusion/v1/payments) endpoint.

tip

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

  • Construct a Payment request JSON payload including all required fields
  • Create a globally unique UUIDv4 SessionId. This will be used to uniquely identify the payment and perform error recovery.
  • POST the JSON payload to http://localhost:4242/fusion/v1/payments/{{SessionId}}
    • Set the Content-Type header to application/json
    • Set the X-Application-Name header to the name of your Sale System
    • Set the X-Software-Version header to the software version of your Sale System
    • Set the message body to the Payment request JSON payload
  • Await the POST result (this could take as long as 5 minutes). Fusion App will return a Payment response in the message body
  • If the Sale System does not receive a POST result (i.e. timeout, socket dropped, system crash etc) implement error handling outlined in error handling

Activate a gift card (events mode)​

info

Only one card can be activated per request. To activate multiple cards, the Sale System must send multiple activation requests sequentially.

To perform a gift card activation with events mode, the Sale System will need to POST a Stored value request JSON payload to the http://localhost:4242/fusion/v1/storedvalue endpoint.

tip

ItemAmount indicates the value to activate the card with. e.g. for a $100 giftcard with $5.95 activation fee ItemAmount will be $100, and TotalFeesAmount will be $5.95

  • Based on the gift card type, read the "activation barcode", and/or UPC
    • Third-party physical - scan the "activation barcode"
    • Closed-loop physical - scan the "activation barcode"
    • Digital account reservation - record product UPC selected by the cashier
  • Construct a Stored value request JSON payload including all required fields
  • Create a globally unique UUIDv4 SessionId. This will be used to uniquely identify the transaction and perform error recovery.
  • POST the JSON payload to http://localhost:4242/fusion/v1/storedvalue/{{SessionId}}events=true
    • Set the Content-Type header to application/json
    • Set the X-Application-Name header to the name of your Sale System
    • Set the X-Software-Version header to the software version of your Sale System
    • Set the message body to the stored value request JSON payload
  • Await the POST result (this should take under 5 seconds).
    • On 4xx the request was invalid and the payment could not be processed
    • On 5xx an error occured, the Sale System should enter error handling
    • On 202 ACCEPTED, the Sale System should GET the payment result
  • Call GET http://localhost:4242/fusion/v1/storedvalue/{{SessionId}}/events using the SessionId from the POST to get the next event in the transaction (this could take as long as 5 minutes). Fusion App will return a SaleToPOIResponse containing the stored value response, or a SaleToPOIRequest containing the Print request
  • If the Sale System does not receive a POST result (i.e. timeout, socket dropped, system crash etc) implement error handling outlined in error handling

Deactivate a gift card (events mode)​

To perform a gift card deactivation with events mode, the Sale System will need to POST a Stored value request JSON payload to the http://localhost:4242/fusion/v1/storedvalue endpoint.

tip

To perform a deactivation, the Sale System will need to recall the POITransactionID from the original activation.

  • Construct a Stored value request JSON payload including all required fields
  • Create a globally unique UUIDv4 SessionId. This will be used to uniquely identify the transaction and perform error recovery.
  • POST the JSON payload to http://localhost:4242/fusion/v1/storedvalue/{{SessionId}}events=true
    • Set the Content-Type header to application/json
    • Set the X-Application-Name header to the name of your Sale System
    • Set the X-Software-Version header to the software version of your Sale System
    • Set the message body to the stored value request JSON payload
  • Await the POST result (this should take under 5 seconds).
    • On 4xx the request was invalid and the payment could not be processed
    • On 5xx an error occured, the Sale System should enter error handling
    • On 202 ACCEPTED, the Sale System should GET the payment result
  • Call GET http://localhost:4242/fusion/v1/storedvalue/{{SessionId}}/events using the SessionId from the POST to get the next event in the transaction (this could take as long as 5 minutes). Fusion App will return a SaleToPOIResponse containing the stored value response, or a SaleToPOIRequest containing the Print request
  • If the Sale System does not receive a POST result (i.e. timeout, socket dropped, system crash etc) implement error handling outlined in error handling

Perform a balance inquiry (events mode)​

To perform a balance inquiry with events mode, the Sale System will need to POST a balance inquiry request JSON payload to the http://localhost:4242/fusion/v1/balanceinquiry endpoint.

  • Construct a balance inquiry request JSON payload including all required fields
    • Note the BalanceInquiryRequest object can be left empty
  • Create a globally unique UUIDv4 SessionId. This will be used to uniquely identify the transaction and perform error recovery.
  • POST the JSON payload to http://localhost:4242/fusion/v1/balanceinquiry/{{SessionId}}events=true
    • Set the Content-Type header to application/json
    • Set the X-Application-Name header to the name of your Sale System
    • Set the X-Software-Version header to the software version of your Sale System
    • Set the message body to the balance inquiry request JSON payload
  • Await the POST result (this should take under 5 seconds).
    • On 4xx the request was invalid and the request could not be processed
    • On 5xx an error occured, the Sale System should enter error handling
    • On 202 ACCEPTED, the Sale System should GET the result
  • Call GET http://localhost:4242/fusion/v1/balanceinquiry/{{SessionId}}/events using the SessionId from the POST to get the next event in the transaction (this could take as long as 5 minutes). Fusion App will return a SaleToPOIResponse containing the balance inquiry response
  • If the Sale System does not receive a POST result (i.e. timeout, socket dropped, system crash etc) implement error handling outlined in error handling

Methods​

Status​

The status endpoint returns the current Fusion App status.

Endpoint

GET http://localhost:4242/fusion/v1/status

Headers

ParameterValue
Content-Typeapplication/json
Acceptapplication/json
X-Application-NameThe name of your Sale System
X-Software-VersionThe software version of your Sale System

Request Body

Empty.

Response Body

A JSON payload representing the Fusion App status.

{
    "Version": "3.0.1.0", //Formatted version number of the Fusion App
    "TerminalPaired": false, //True if a terminal has been paired, false otherwise
    "Status": "Ready" //Status of the Fusion App
}

UI​

The ui endpoint enables the Sale System to launch the Fusion App main UI so the operator can pair the Fusion App to a terminal and unpair the Fusion App from the terminal.

tip

This is important when the task bar/system tray is hidden and the operator cannot access the main Fusion App icon, while the Sale System is running.

Endpoint POST http://localhost:4242/fusion/v1/ui?launchCommand=

Query Parameters

ParameterValue
LaunchCommandSet to "pairing" to launch directly to the pairing UI

Headers

ParameterValue
Content-Typeapplication/json
Acceptapplication/json
X-Application-NameThe name of your Sale System
X-Software-VersionThe software version of your Sale System

Request Body

Empty.

Response Body

Empty.

Login​

The Login endpoint is a useful method for validating connectivity with DataMesh without sending a financial request. The Sale System is not required to implement this functionality.

Endpoint POST http://localhost:4242/fusion/v1/login/{{SessionId}}

Query Parameters

ParameterValue
SessionIdA globally unique UUIDv4 which identifies this request

Headers

ParameterValue
Content-Typeapplication/json
Acceptapplication/json
X-Application-NameThe name of your Sale System
X-Software-VersionThe software version of your Sale System

Request Body

Empty.

Response Body

A JSON payload based on 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"
		}
	}
}

Response HTTP Status Codes

CodeDescriptionRequired action
200OKFusion App processed the request. Check LoginResponse.Response.Result for the result of the login request
4xxBad RequestFusion App was unable to process the request. Check the required headers and try again.
5xxErrorFusion App was unable to process the request. Try again.

Payments​

The Payments endpoint is used to perform purchase, purchase + cash out, cash out only, and refund requests.

Endpoints

NameEndpointDescription
Request (blocking mode)POST http://localhost:4242/fusion/v1/payments/{{SessionId}}Initate a payment in blocking mode
Request (events mode)POST http://localhost:4242/fusion/v1/payments/{{SessionId}}?events=trueInitate a payment in events mode
Error handlingGET http://localhost:4242/fusion/v1/payments/{{SessionId}}Called by the Sale System to enter error handling
Get eventsGET http://localhost:4242/fusion/v1/payments/{{SessionId}}/eventsGet events for the request. See Payment events

Query Parameters

ParameterValue
SessionIdA globally unique UUIDv4 which identifies this request
EventsSet to true to enable events mode, false otherwise

Headers

ParameterValue
Content-Typeapplication/json
Acceptapplication/json
X-Application-NameThe name of your Sale System
X-Software-VersionThe software version of your Sale System

Request Body

A JSON payload based on Payment request

Payment request

{
    "PaymentRequest": {
        "SaleData": {
            "SaleTransactionID": {
                "TransactionID": "X_SALE_ID",
                "TimeStamp": "X_ISO8601_FORMAT"
            }
        },
        "PaymentTransaction": {
            "AmountsReq": {
                "Currency": "AUD",
                "RequestedAmount": 10.42
            },
           "SaleItem":[
               {
                  "ItemID":"0",
                  "ProductCode":"X_PRODUCT_CODE",
                  "UnitOfMeasure":"Other",
                  "Quantity":"1",
                  "UnitPrice":"10.42",
                  "ItemAmount":"10.42",
                  "ProductLabel":"Big Kahuna Burger"
               }
            ]            
        },
        "PaymentData": {
            "PaymentType": "Normal"
        }
    }
}

Response Body

info

A response body is only returned when using blocking mode.

A JSON payload based on 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"
			}
		},
		"AllowedProductCodes": [
			"1",
			"2",
			"3"
		],
		"PaymentReceipt": [
			{
				"DocumentQualifier": "xxx",
				"RequiredSignatureFlag": true,
				"OutputContent": {
					"OutputFormat": "XHTML",
					"OutputXHTML": "xxx"
				}
			}
		]
	}
}

Response HTTP Status Codes

CodeDescriptionRequired action
200OKFusion App processed the request. Check PaymentResponse.Response.Result for the result of the payment request
202AcceptedFusion App processed the request in events mode. Call the payment events endpoint for the payment result
4xxBad RequestFusion App was unable to process the request. Check the required headers and request body and try again.
5xxErrorFusion App was unable to process the request. The Sale System should perform error handling to retrieve the payment result.

Payment events​

The Payment events endpoint is used to request the events associated with an ongoing payment session.

tip

Use the SessionId used in the POST to initiate the payment.

The SessionId is only valid during the lifetime of the payment (i.e. when a payment is initiated until PaymentResponse is returned to the Sale System). If 404 is returned, the Sale System should enter error handling.

Endpoint GET http://localhost:4242/fusion/v1/payments/{{SessionId}}/events

Query Parameters

ParameterValue
SessionIdA globally unique UUIDv4 which identifies this request

Headers

ParameterValue
Content-Typeapplication/json
Acceptapplication/json
X-Application-NameThe name of your Sale System
X-Software-VersionThe software version of your Sale System

Request Body

Empty.

Response Body

A JSON payload containing either a SaleToPOIRequest or SaleToPOIResponse.

Print request

{
	"SaleToPOIRequest": {
		"MessageHeader": {
			"MessageClass": "Device",
			"MessageCategory": "Print",
			"MessageType": "Request",
			"ServiceID": "xxxx"
		},
		"PrintRequest": {
			"PrintOutput": {
				"DocumentQualifier": "Cashier | Customer",
				"IntegratedPrintFlag": "true|false",
				"RequiredSignatureFlag": "true|false",
				"OutputContent": {
					"OutputFormat": "XHTML",
					"OutputXHTML": "xxx"
				}
			}
		}
	}
}

Payment response

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

Response HTTP Status Codes

CodeDescriptionRequired action
200OKFusion App processed the request. If a print request, check SaleToPOIRequest.PrintRequest and process the print. If a payment response, check SaleToPOIResponse.PaymentResponse.Response.Result for the result of the payment request
404Not foundFusion App was unable to find the session. The Sale System should perform error handling to retrieve the payment result.
5xxErrorFusion App was unable to process the request. The Sale System should perform error handling to retrieve the payment result.

Balance inquiry​

The balance inquiry endpoint is used to request the balance of an account.

Endpoints

NameEndpointDescription
Request (blocking mode)POST http://localhost:4242/fusion/v1/balanceinquiry/{{SessionId}}Initate a balance inquiry in blocking mode
Request (events mode)POST http://localhost:4242/fusion/v1/balanceinquiry/{{SessionId}}?events=trueInitate a balance inquiry in events mode
Error handlingGET http://localhost:4242/fusion/v1/balanceinquiry/{{SessionId}}Called by the Sale System to enter error handling
Get eventsGET http://localhost:4242/fusion/v1/balanceinquiry/{{SessionId}}/eventsGet events for the request. See balance inquiry events

Query Parameters

ParameterValue
SessionIdA globally unique UUIDv4 which identifies this request
EventsSet to true to enable events mode, false otherwise

Headers

ParameterValue
Content-Typeapplication/json
Acceptapplication/json
X-Application-NameThe name of your Sale System
X-Software-VersionThe software version of your Sale System

Request Body

A JSON payload based on balance inquiry request

Balance inquiry request

{
    "BalanceInquiryRequest": {
    }
}

note

The BalanceInquiryRequest node is intentionally empty.

Response Body

info

A response body is only returned when using blocking mode.

A JSON payload based on 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"
			},

		}
	}
}

Response HTTP Status Codes

CodeDescriptionRequired action
200OKFusion App processed the request. Check BalanceInquiryResponse.Response.Result for the result of the request.
202AcceptedFusion App processed the request in events mode. Call the balance inquiry events endpoint for the result.
4xxBad RequestFusion App was unable to process the request. Check the required headers and request body and try again.
5xxErrorFusion App was unable to process the request. The Sale System should perform error handling to retrieve the result.

Balance inquiry events​

The balance inquiry events endpoint is used to request the events associated with an ongoing balance inquiry session.

tip

Use the SessionId used in the POST to initiate the transaction.

The SessionId is only valid during the lifetime of the transaction (i.e. when a transaction is initiated until BalanceInquiryResponse is returned to the Sale System). If 404 is returned, the Sale System should enter error handling.

Endpoint GET http://localhost:4242/fusion/v1/balanceinquiry/{{SessionId}}/events

Query Parameters

ParameterValue
SessionIdA globally unique UUIDv4 which identifies this request

Headers

ParameterValue
Content-Typeapplication/json
Acceptapplication/json
X-Application-NameThe name of your Sale System
X-Software-VersionThe software version of your Sale System

Request Body

Empty.

Response Body

A JSON payload containing either a SaleToPOIRequest or SaleToPOIResponse.

Print request

{
	"SaleToPOIRequest": {
		"MessageHeader": {
			"MessageClass": "Device",
			"MessageCategory": "Print",
			"MessageType": "Request",
			"ServiceID": "xxxx"
		},
		"PrintRequest": {
			"PrintOutput": {
				"DocumentQualifier": "Cashier | Customer",
				"IntegratedPrintFlag": "true|false",
				"RequiredSignatureFlag": "true|false",
				"OutputContent": {
					"OutputFormat": "XHTML",
					"OutputXHTML": "xxx"
				}
			}
		}
	}
}

Balance inquiry response

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

				}
			}
	}
}

Response HTTP Status Codes

CodeDescriptionRequired action
200OKFusion App processed the request. If a print request, check SaleToPOIRequest.PrintRequest and process the print. If a payment response, check SaleToPOIResponse.BalanceInquiryResponse.Response.Result for the result of the transaction.
404Not foundFusion App was unable to find the session. The Sale System should perform error handling to retrieve the transaction result.
5xxErrorFusion App was unable to process the request. The Sale System should perform error handling to retrieve the transaction result.

Stored value​

The stored value endpoint is used to activate or deactivate a gift card.

Endpoints

NameEndpointDescription
Request (blocking mode)POST http://localhost:4242/fusion/v1/storedvalue/{{SessionId}}Initate a stored value request in blocking mode
Request (events mode)POST http://localhost:4242/fusion/v1/storedvalue/{{SessionId}}?events=trueInitate a stored value request in events mode
Error handlingGET http://localhost:4242/fusion/v1/storedvalue/{{SessionId}}Called by the Sale System to enter error handling
Get eventsGET http://localhost:4242/fusion/v1/storedvalue/{{SessionId}}/eventsGet events for the request. See stored value events

Query Parameters

ParameterValue
SessionIdA globally unique UUIDv4 which identifies this request
EventsSet to true to enable events mode, false otherwise

Headers

ParameterValue
Content-Typeapplication/json
Acceptapplication/json
X-Application-NameThe name of your Sale System
X-Software-VersionThe software version of your Sale System

Request Body

A JSON payload based on 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": "",

		}
		]		
	}
}

Response Body

info

A response body is only returned when using blocking mode.

A JSON payload based on 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"
				}
			}
		]
	}
}

Response HTTP Status Codes

CodeDescriptionRequired action
200OKFusion App processed the request. Check StoredValueResponse.Response.Result for the result of the request.
202AcceptedFusion App processed the request in events mode. Call the stored value events endpoint for the result.
4xxBad RequestFusion App was unable to process the request. Check the required headers and request body and try again.
5xxErrorFusion App was unable to process the request. The Sale System should perform error handling to retrieve the result.

Stored value events​

The stored value events endpoint is used to request the events associated with an ongoing stored value session.

tip

Use the SessionId used in the POST to initiate the transaction.

The SessionId is only valid during the lifetime of the transaction (i.e. when a transaction is initiated until StoredValueResponse is returned to the Sale System). If 404 is returned, the Sale System should enter error handling.

Endpoint GET http://localhost:4242/fusion/v1/storedvalue/{{SessionId}}/events

Query Parameters

ParameterValue
SessionIdA globally unique UUIDv4 which identifies this request

Headers

ParameterValue
Content-Typeapplication/json
Acceptapplication/json
X-Application-NameThe name of your Sale System
X-Software-VersionThe software version of your Sale System

Request Body

Empty.

Response Body

A JSON payload containing either a SaleToPOIRequest or SaleToPOIResponse.

Print request

{
	"SaleToPOIRequest": {
		"MessageHeader": {
			"MessageClass": "Device",
			"MessageCategory": "Print",
			"MessageType": "Request",
			"ServiceID": "xxxx"
		},
		"PrintRequest": {
			"PrintOutput": {
				"DocumentQualifier": "Cashier | Customer",
				"IntegratedPrintFlag": "true|false",
				"RequiredSignatureFlag": "true|false",
				"OutputContent": {
					"OutputFormat": "XHTML",
					"OutputXHTML": "xxx"
				}
			}
		}
	}
}

Stored value response

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

Response HTTP Status Codes

CodeDescriptionRequired action
200OKFusion App processed the request. If a print request, check SaleToPOIRequest.PrintRequest and process the print. If a payment response, check SaleToPOIResponse.StoredValueResponse.Response.Result for the result of the transaction.
404Not foundFusion App was unable to find the session. The Sale System should perform error handling to retrieve the transaction result.
5xxErrorFusion App was unable to process the request. The Sale System should perform error handling to retrieve the transaction result.

Error handling​

When the Sale System POSTs a payment, balance inquiry, or stored value request, it will eventually receive a matching payment, balance inquiry, or stored value response, or via the ~/events endpoint in events mode.

info

The Sale System hard timeout should be set to 300 seconds before entering error handling.

The Sale System may attempt to cancel the transaction at any point prior to the 300 second timeout by sending a POST ~/fusion/v1/payments/{{SessionId}}/abort. As the abort request may not be successful (e.g. the POI Terminal is temporarily offline) the Sale System must continue to wait for the full timeout before entering error recovery.

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

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

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

To perform error handling the Sale System should send a GET request to the error handling endpoint using the SessionId of the failed request. Fusion App will return a response containing the result of the payment.

info

The Sale System timeout for the error handling endpoint GET request should be set to 95 seconds.

Base Uri http://localhost:4242/fusion/v1/

Request endpointError handling endpointResponse content
POST ~payments/{{SessionId}}GET ~payments/{{SessionId}}PaymentResponse
POST ~balanceinquiry/{{SessionId}}GET ~balanceinquiry/{{SessionId}}BalanceInquiryResponse
POST ~storedvalue/{{SessionId}}GET ~storedvalue/{{SessionId}}StoredValueResponse