fiskaltrust PosSystem API (2.1)

Download OpenAPI specification:Download

fiskaltrust: hello@fiskaltrust.eu License: This documentation and samples are released under the EUPL license.

This API provides a variety of different functionalities for POS systems and is the central entry point to the fiskaltrust.Middleware. It can be used to fiscalize (or sign) receipts, execute payments via different payment providers, digitally print receipts (e.g. via the Receipt Bundle), and to export data from the Middleware.

API design principles

While the POSSystem API was designed to be easily usable via HTTP calls and JSON the call patterns follow a processual principle. We believe that by giving POS Systems a way to handle core processes in a stateful way as if they are a statemachine, that we can always ensure that the processes run as frictionless as possible. Each call that is handled by the POS System API is safe to be replayed and idempotent.

Authentication

The POSSystem API can only be used with the access data of a CashBox. These credentials can be found on the fiskaltrust.Portal in the CashBox Configuration page.You will need both CashBoxId and AccessToken to use this API.

Versioning

This API uses semantic versioning, meaning only major version changes contain breaking changes. Non-breaking changes (like returning additional data without changing the original model) will not increase the major version.

The latest version is used if no version is specified (like in the samples in this collection).
Users can specify versions by explicitly stating it in the URL once more versions are released.

Headers:

x-operation-id: The operation id is meant to be a idempotency key that let's the caller of the API endpoints safely retry calls. In case of timeouts, network interruptions this gives the ability to safely retry the process. While the request on the server side is still in progress calling the endpoint again with the same operation id does return a 422 Unprocessable Content. As soon as the request is finished whatever the initial request has finished with will be returned to the caller whenever the endpoint is called with the same body and the same operation-id.

e.g. Calling /sign with x-operation-id ea4279ee-8684-412f-b8eb-32b5dea52811. The operation fails with a timeout. The caller handles the exception by performing the exact same operation again. The backend notices that this operation-id has been used in another transaction already and checks the state. If the state is finished it returnes the original response body

SynchronAPI

synchronous call pattern

caller / watcher description

successfull

timeout / retry

failed

Executes a blocking echo call end-to-end

This method can be used to perform a basic health and communcation check. It is also used for reseting the Middleware Instance (echo(null)

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) Example: af60144d-5c1b-4b56-9706-1e80c9ed1705 operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal #TODO
x-possystem-id	any (x-possystem-id) identifies the calling possystem #TODO

Request Body schema: application/json

object

Responses

Callbacks

Request samples

Payload

Content type

application/json

{ }

Response samples

200
201
400
401
500

Content type

application/json

{ }

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

exectue a cart call end-to-end

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
x-possystem-id	any (x-possystem-id) identifies the calling possystem #TODO

Request Body schema: application/json

object

Responses

Callbacks

Request samples

Payload

Content type

application/json

{ }

Response samples

200
201

Content type

application/json

{"ftJourneyID": "00000000-0000-0000-0000-000000000000",
"DocumentURL": "http://example.com"
}

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

get content of a journey

get content of a journey, without updateing the submitted state

Authorizations:

(CashBoxIdCashBoxAccessToken)

path Parameters

JourneyId

required

string <uuid>

Responses

Response samples

200
400
401
500

Content type

application/json

{ }

updates an ongoing journey

execute a journey update call end-to-end

Authorizations:

(CashBoxIdCashBoxAccessToken)

path Parameters

JourneyId

required

string <uuid>

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
X-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
x-possystem-id	any (x-possystem-id) identifies the calling possystem #TODO

Request Body schema: application/json

object

Responses

Callbacks

Request samples

Payload

Content type

application/json

{ }

Response samples

400
401
500

Content type

application/problem+json

{"type": "http://example.com",
"status": 100,
"title": "string",
"detail": "string",
"instance": "string",
"code": "string",
"errors": [{"detail": "string",
"pointer": "string",
"parameter": "string",
"header": "string",
"code": "string"
}
]
}

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

close ongoing journey

Authorizations:

(CashBoxIdCashBoxAccessToken)

path Parameters

JourneyId

required

string <uuid>

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
X-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
x-possystem-id	any (x-possystem-id) identifies the calling possystem #TODO

Responses

Callbacks

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

exectue a order call end-to-end

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
x-possystem-id	any (x-possystem-id) identifies the calling possystem #TODO
x-journey-id	any (x-journey-id) identifies ongoing cart journey #TODO

Request Body schema: application/json

object

Responses

Callbacks

Request samples

Payload

Content type

application/json

{ }

Response samples

200
201

Content type

application/json

{ }

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

stops ongoing order call

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
x-possystem-id	any (x-possystem-id) identifies the calling possystem #TODO
x-journey-id	any (x-journey-id) identifies ongoing cart journey #TODO

Responses

Callbacks

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

execute a sign call end-to-end

This method can be used to sign different types of receipts according to local fiscalization regulations. After signing the receipt according to the fiscal law, this method synchronously returns the data that need to be printed onto the receipt. The format of the receipt request is documented in the Middleware API docs, and the exact behavior of the method is determined by the cases sent within the properties (e.g. ftReceiptCase, ftChargeItemCase and ftPayItemCase.

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) Example: 00000000-0000-0000-0000-000000000000 operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal #TODO
x-possystem-id	any (x-possystem-id) identifies the calling possystem #TODO
x-journey-id	any (x-journey-id) identifies ongoing cart journey #TODO

Request Body schema:
application/json

cbTerminalID	string <= 1023 characters Default: "undefined" The unique identification of the input-station/terminal within a cash-register/pos-system identified by `ftCashBoxID`.
cbReceiptReference required	string <= 1023 characters Default: "undefined" Reference number send by the cash register. This value must be a unique string/receipt number related to the calling cash register. This string/receipt number is a unique primary key of the dataset of the cash register.
cbReceiptMoment required	string <date-time> moment at which the receipt was create by the cash register, must be provided in UTC.
required	Array of objects (ChargeItem) list of line items related to services and products
required	Array of objects (PayItem) list of line items related to payments
ftCashBoxID	string <uuid> Default: "00000000-0000-0000-0000-000000000000" identification of the cash register
ftPosSystemID	string <uuid> Default: "00000000-0000-0000-0000-000000000000" identification of the used software of the cash register
ftReceiptCase	integer <uint64> Default: 0 Type of business according to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO! this is relevant for fiskaltrust middleware processing and is a country specific mapping. as fallback when not specified, a cash register business case at the point-of-sale is used.
	(string or null) or object optional gives additional details for defined type of business related to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO!
ftQueueID	string or null <uuid> Default: null optional routing instruction to identify a specific queue behind a load balancer or in other usecases
cbPreviousReceiptReference	string or null <= 1023 characters Default: null optional Reference `cbReceiptReference` of the previous receipt. Used to connect multiple requests for a single Business Case.
	(integer or null) or (number or null) Default: null optional total receipt amount, including value added taxes (=gross receipt amount) given to avoid calculation and rounding differences. systems which are using net amounts as central calculation should alsways use this property. if not provided, the sum of `Amount` in all provided `ftChargeItems` is used as total receipt amount. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
	(string or null) or object Default: null optional Identification of the user, who creates the receipt.
	(string or null) or object Default: null optional Identification of the area/section/field, in which the receipt is created. e.g. Table number of a restaurant business; a department of a commercial establishment; the vehicle of a taxi company
	(string or null) or object Default: null optional Identification of the consumer, for whom the receipt is created. e.g. Email address, phone number, personal tax number
	(string or null) or object Default: null optional Settlement identification where this receipt will be added. e.g. shift number or day of operation
Currency	string (CurrencyEnum) Default: "EUR" Enum: "EUR" "CHF" "CZK" "HUF" "BAM" "DKK" "RON" "NOK" "PLN" "RSD" "SEK" "UAH" "USD" "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYN" "BZD" "CAD" "CDF" "CHE" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUP" "CVE" "DJF" "DOP" "DZD" "EGP" "ERN" "ETB" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HTG" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRU" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PYG" "QAR" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SGD" "SHP" "SLE" "SLL" "SOS" "SRD" "SSP" "STN" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UGX" "USN" "UYI" "UYU" "UYW" "UZS" "VED" "VES" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL" used as currency code for money numbers. along ISO 4217 (https://en.wikipedia.org/wiki/ISO_4217)
DecimalPrecisionMultiplier	integer <int32> (DecimalPrecisionMultiplierEnum) Default: 1 Enum: 1 100 10000 1000000 100000000 is used as multiplier for decimal numbers. when value 1 is used, revlevant numbers are interpreted as floating-point numbers. for all other values, relevant numbers are interpreted as integer and need to be devided by the Multiplier to get the decimal representation.

Responses

Callbacks

Request samples

Payload

Content type

application/json

Example

most simple ReceiptRequest examplte, which uses unknown tagging as a fallback

long description cbTerminalId comes from Header ftReceiptCase fallback to 0xCCCC_2000_0000_0000 ftChargeItemCase fallback to 0xCCCC_2000_0000_0000 ftPayItemCase fallback to 0xCCCC_20000_0000_0000 with line breaks

{"cbReceiptReference": "1234",
"cbReceiptMoment": "2023-11-24T15:22:07Z",
"cbChargeItems": [{"Quantity": 1,
"Description": "Beer 0.3l",
"Amount": 4.6,
"VATRate": 20
},
{"Quantity": 1,
"Description": "Coffee",
"Amount": 3.6,
"VATRate": 20
}
],
"cbPayItems": [{"Description": "Cash",
"Amount": 7.2
}
]
}

Response samples

200
201
400
401
500

Content type

application/json

{"ftQueueID": "00000000-0000-0000-0000-000000000000",
"ftQueueItemID": "00000000-0000-0000-0000-000000000000",
"ftQueueRow": 0,
"ftCashBoxIdentification": "undefined",
"ftReceiptIdentification": "ft0#",
"ftReceiptMoment": "2020-06-29T17:45:40.505Z",
"ftSignatures": [{"ftSignatureItemID": null,
"ftSignatureFormat": 0,
"ftSignatureType": 0,
"Caption": null,
"Data": "string"
}
],
"ftState": 0,
"ftStateData": "string",
"ftCashBoxID": "00000000-0000-0000-0000-000000000000",
"cbTerminalID": "undefined",
"cbReceiptReference": "undefined",
"ftReceiptHeader": ["string"
],
"ftChargeItems": [{"ftChargeItemID": null,
"Quantity": 1,
"Description": null,
"Amount": 0,
"VATRate": 0,
"ftChargeItemCase": 0,
"ftChargeItemCaseData": "string",
"VATAmount": null,
"Moment": "2020-06-29T17:45:40.505Z",
"Position": 0,
"AccountNumber": null,
"CostCenter": null,
"ProductGroup": null,
"ProductNumber": null,
"ProductBarcode": null,
"Unit": null,
"UnitQuantity": null,
"UnitPrice": null,
"Currency": "EUR",
"DecimalPrecisionMultiplier": 1
}
],
"ftChargeLines": ["string"
],
"ftPayItems": [{"ftPayItemID": null,
"Quantity": 1,
"Description": null,
"Amount": 0,
"ftPayItemCase": 0,
"ftPayItemCaseData": "string",
"Moment": "2020-06-29T17:45:40.505Z",
"Position": 0,
"AccountNumber": null,
"CostCenter": null,
"MoneyGroup": null,
"MoneyNumber": null,
"MoneyBarcode": null,
"Currency": "EUR",
"DecimalPrecisionMultiplier": 1
}
],
"ftPayLines": ["string"
],
"ftReceiptFooter": ["string"
]
}

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

execute a issue call end-to-end

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal #TODO
x-possystem-id	any (x-possystem-id) identifies the calling possystem #TODO
x-journey-id	any (x-journey-id) identifies ongoing cart journey #TODO

Request Body schema: application/json

One of

required	object (ReceiptRequest_1) The cash register transfers the data of an entire receipt request to the fiskaltrust.Middleware using the ReceiptRequest data structure.
required	object (ReceiptResponse_1) The fiskaltrust.Middleware sends back the processed data to the cash register through the receipt response.

Responses

Callbacks

Request samples

Payload

Content type

application/json

Example

IssueRequest

{"ReceiptRequest": {"ftCashBoxID": "string",
"ftQueueID": "string",
"ftPosSystemId": "string",
"cbTerminalID": "string",
"cbReceiptReference": "string",
"cbReceiptMoment": "2019-08-24T14:15:22Z",
"cbChargeItems": [{"position": 0,
"quantity": 0.1,
"description": "string",
"amount": 0.1,
"vatRate": 0.1,
"ftChargeItemCase": 0,
"ftChargeItemCaseData": "string",
"vatAmount": 0.1,
"accountNumber": "string",
"costCenter": "string",
"productGroup": "string",
"productNumber": "string",
"productBarcode": "string",
"unit": "string",
"unitQuantity": 0.1,
"unitPrice": 0.1,
"moment": "2019-08-24T14:15:22Z"
}
],
"cbPayItems": [{"position": 0,
"quantity": 0.1,
"description": "string",
"amount": 0.1,
"ftPayItemCase": 0,
"ftPayItemCaseData": "string",
"accountNumber": "string",
"costCenter": "string",
"moneyGroup": "string",
"moneyNumber": "string",
"moment": "2019-08-24T14:15:22Z"
}
],
"ftReceiptCase": 0,
"ftReceiptCaseData": "string",
"cbReceiptAmount": 0.1,
"cbUser": "string",
"cbArea": "string",
"cbCustomer": "string",
"cbSettlement": "string",
"cbPreviousReceiptReference": "string"
},
"ReceiptResponse": {"ftCashBoxID": "string",
"ftQueueID": "string",
"ftQueueItemID": "string",
"ftQueueRow": 0,
"cbTerminalID": "string",
"cbReceiptReference": "string",
"ftCashBoxIdentification": "string",
"ftReceiptIdentification": "string",
"ftReceiptMoment": "2019-08-24T14:15:22Z",
"ftReceiptHeader": ["string"
],
"ftChargeItems": [{"position": 0,
"quantity": 0.1,
"description": "string",
"amount": 0.1,
"vatRate": 0.1,
"ftChargeItemCase": 0,
"ftChargeItemCaseData": "string",
"vatAmount": 0.1,
"accountNumber": "string",
"costCenter": "string",
"productGroup": "string",
"productNumber": "string",
"productBarcode": "string",
"unit": "string",
"unitQuantity": 0.1,
"unitPrice": 0.1,
"moment": "2019-08-24T14:15:22Z"
}
],
"ftChargeLines": ["string"
],
"ftPayItems": [{"position": 0,
"quantity": 0.1,
"description": "string",
"amount": 0.1,
"ftPayItemCase": 0,
"ftPayItemCaseData": "string",
"accountNumber": "string",
"costCenter": "string",
"moneyGroup": "string",
"moneyNumber": "string",
"moment": "2019-08-24T14:15:22Z"
}
],
"ftPayLines": ["string"
],
"ftSignatures": [{"ftSignatureFormat": 0,
"ftSignatureType": 0,
"caption": "string",
"data": "string"
}
],
"ftReceiptFooter": ["string"
],
"ftState": 0,
"ftStateData": "string"
}
}

Response samples

200
201
400
401
500

Content type

application/json

{"ftQueueID": "fb6ee7af-f98e-4d5a-891b-ff24d7313836",
"ftQueueItemID": "92273d5f-5d3a-4415-bfc8-f7895ceaecf6",
"DocumentURL": "http://example.com",
"DocumentContentType": "string"
}

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

get content of an issued receipt

get content of an issued receipt in requested format, without updateing the submitted state

Authorizations:

(CashBoxIdCashBoxAccessToken)

path Parameters

QueueId required	string <uuid>
QueueItemId required	string <uuid>

Responses

Response samples

200
400
401
500

Content type

image/png

No sample

updates an issued and/or submitted receipt

execute a update call end-to-end

Authorizations:

(CashBoxIdCashBoxAccessToken)

path Parameters

QueueId required	string <uuid>
QueueItemId required	string <uuid>

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
X-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
x-possystem-id	any (x-possystem-id) identifies the calling possystem #TODO

Request Body schema: application/json

Action

required

string (IssueUpdateActionEnum)

accept

Responses

Callbacks

Request samples

Payload

Content type

application/json

Example

accept

{"Action": "accept"
}

Response samples

400
401
500

Content type

application/problem+json

{"type": "http://example.com",
"status": 100,
"title": "string",
"detail": "string",
"instance": "string",
"code": "string",
"errors": [{"detail": "string",
"pointer": "string",
"parameter": "string",
"header": "string",
"code": "string"
}
]
}

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

link visualization via qr code

get image of qr code for digital receipt url

Authorizations:

(CashBoxIdCashBoxAccessToken)

path Parameters

QueueId required	string <uuid>
QueueItemId required	string <uuid>

Responses

Response samples

400
401
404
500

Content type

application/problem+json

{"type": "http://example.com",
"status": 100,
"title": "string",
"detail": "string",
"instance": "string",
"code": "string",
"errors": [{"detail": "string",
"pointer": "string",
"parameter": "string",
"header": "string",
"code": "string"
}
]
}

gives the information, if the receipt was delivered, at leasted once

TBD

Authorizations:

(CashBoxIdCashBoxAccessToken)

path Parameters

QueueId required	string <uuid>
QueueItemId required	string <uuid>

Responses

Response samples

200
400
401
404
500

Content type

application/json

{ }

exectue a pay call end-to-end

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
x-possystem-id	any (x-possystem-id) identifies the calling possystem #TODO
x-journey-id	any (x-journey-id) identifies ongoing cart journey #TODO

Request Body schema: application/json

Protocol required	string (PaymentProtocolEnum) Default: "use_auto" Enum: "use_first" "use_all" "use_auto" "use_none" "bluecode" "hobex_zvt" "hobex_restapi" "hobex_softpos_posit" "gp_softpos_gptom" "gp_mpas" "gp_zvt" "payone_softpos_wpi" "payone_serverapi" "payone_fistdata" "worldline_wpi_1_3" "worldline_wpi_2" a list of supported protocols use_first can be used to use first detected payment protocol for the specific cashboxid/terminalid combination use_all triggers all available payment protocols for the specific cashboxid/terminalid combination and uses first successfull use_auto triggers a automaticaly selected, single payment protocol, best match for given PayItemCase use_none asks the customer, to select one
Action required	string (PaymentActionEnum) Enum: "payment" "cancel" "refund" "pre_authorization" "other" a list of supported actions not each protocol supports each action
required	object (PayItem) represents a item related to a payment
AcceptUnderPayment	boolean Default: false
AcceptOverPayment	boolean Default: true
cbTerminalID	string <= 1023 characters Default: "undefined" The unique identification of the input-station/terminal within a cash-register/pos-system identified by `ftCashBoxID`.
ftCashBoxID	string <uuid> Default: "00000000-0000-0000-0000-000000000000" identification of the cash register
ftPosSystemID	string <uuid> Default: "00000000-0000-0000-0000-000000000000" identification of the used software of the cash register

Responses

Callbacks

Request samples

Payload

Content type

application/json

Example

payment

request a payment amount is EUR 1.50 chooses a payment-device assigned to cbTerminalId by itself

{"Action": "payment",
"Protocol": "use_auto",
"cbPayItem": {"Description": "Card",
"Amount": 1.5
},
"cbTerminalId": 1
}

Response samples

200
201

Content type

application/json

{"Protocol": "use_first",
"ftQueueID": "00000000-0000-0000-0000-000000000000",
"ftPayItems": [{"ftPayItemID": null,
"Quantity": 1,
"Description": null,
"Amount": 0,
"ftPayItemCase": 0,
"ftPayItemCaseData": "string",
"Moment": "2020-06-29T17:45:40.505Z",
"Position": 0,
"AccountNumber": null,
"CostCenter": null,
"MoneyGroup": null,
"MoneyNumber": null,
"MoneyBarcode": null,
"Currency": "EUR",
"DecimalPrecisionMultiplier": 1
}
]
}

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

stops ongoing pay call

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
x-possystem-id	any (x-possystem-id) identifies the calling possystem #TODO
x-journey-id	any (x-journey-id) identifies ongoing cart journey #TODO

Responses

Callbacks

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

gets a single entry of a specific

Authorizations:

(CashBoxIdCashBoxAccessToken)

path Parameters

StorageType required	string (StorageTypeEnum) Enum: "OperationItem" "OperationStateJournal" "PayItem" "ChargeItem" "QueueItem" "IssueItem" "ActionJournal" "ReceiptJournal"
Id required	string <uuid>

Responses

Response samples

200

Content type

application/json

Example

OperationItem

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"Method": "string",
"Path": "string",
"Header": { },
"Request": { },
"Response": { },
"LastState": "done",
"StorageType": "OperationItem"
}

echo

health check

cart

omnichannel journey

starts a cart request

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-finalized	any (x-operation-callback-finalized) single callback setting for current operation, executed once the operation is in final state, `done` or `failed`
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in PaymentRequest, if given

Request Body schema: application/json

object

Responses

Callbacks

Request samples

Payload

Content type

application/json

{ }

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

stops a ongoing cart request

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-finalized	any (x-operation-callback-finalized) single callback setting for current operation, executed once the operation is in final state, `done` or `failed`
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in PaymentRequest, if given

Responses

Callbacks

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

get state of cart request

get state of pay request

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

Response samples

200

Content type

application/json

[{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string",
"PayItemID": null
}
]

get result of a pay request and purges state from queue/processor

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

Response samples

200

Content type

application/json

{"ftJourneyID": "00000000-0000-0000-0000-000000000000",
"DocumentURL": "http://example.com"
}

blocks for a maxiumum timeout in second (default is 15) and comes back with 200 if payment done and 204 if payment not done

TBD

Authorizations:

(CashBoxIdCashBoxAccessToken)

path Parameters

JourneyId

required

string <uuid>

query Parameters

Timeout

number <int>

Default: 15

Responses

Response samples

200

Content type

application/json

{ }

order

execute orders

starts a order request

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-finalized	any (x-operation-callback-finalized) single callback setting for current operation, executed once the operation is in final state, `done` or `failed`
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in PaymentRequest, if given

Request Body schema: application/json

object

Responses

Callbacks

Request samples

Payload

Content type

application/json

{ }

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

stops a ongoing pay request

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-finalized	any (x-operation-callback-finalized) single callback setting for current operation, executed once the operation is in final state, `done` or `failed`
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in PaymentRequest, if given

Responses

Callbacks

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

get state of order request

get state of pay request

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

Response samples

200

Content type

application/json

[{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string",
"PayItemID": null
}
]

get result of a pay request and purges state from queue/processor

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

Response samples

200

Content type

application/json

{ }

pay

execute payments

starts a pay request

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-finalized	any (x-operation-callback-finalized) single callback setting for current operation, executed once the operation is in final state, `done` or `failed`
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in PaymentRequest, if given

Request Body schema: application/json

Protocol required	string (PaymentProtocolEnum) Default: "use_auto" Enum: "use_first" "use_all" "use_auto" "use_none" "bluecode" "hobex_zvt" "hobex_restapi" "hobex_softpos_posit" "gp_softpos_gptom" "gp_mpas" "gp_zvt" "payone_softpos_wpi" "payone_serverapi" "payone_fistdata" "worldline_wpi_1_3" "worldline_wpi_2" a list of supported protocols use_first can be used to use first detected payment protocol for the specific cashboxid/terminalid combination use_all triggers all available payment protocols for the specific cashboxid/terminalid combination and uses first successfull use_auto triggers a automaticaly selected, single payment protocol, best match for given PayItemCase use_none asks the customer, to select one
Action required	string (PaymentActionEnum) Enum: "payment" "cancel" "refund" "pre_authorization" "other" a list of supported actions not each protocol supports each action
required	object (PayItem) represents a item related to a payment
AcceptUnderPayment	boolean Default: false
AcceptOverPayment	boolean Default: true
cbTerminalID	string <= 1023 characters Default: "undefined" The unique identification of the input-station/terminal within a cash-register/pos-system identified by `ftCashBoxID`.
ftCashBoxID	string <uuid> Default: "00000000-0000-0000-0000-000000000000" identification of the cash register
ftPosSystemID	string <uuid> Default: "00000000-0000-0000-0000-000000000000" identification of the used software of the cash register

Responses

Callbacks

Request samples

Payload

Content type

application/json

Example

payment

request a payment amount is EUR 1.50 chooses a payment-device assigned to cbTerminalId by itself

{"Action": "payment",
"Protocol": "use_auto",
"cbPayItem": {"Description": "Card",
"Amount": 1.5
},
"cbTerminalId": 1
}

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

stops a ongoing pay request

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-finalized	any (x-operation-callback-finalized) single callback setting for current operation, executed once the operation is in final state, `done` or `failed`
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in PaymentRequest, if given

Responses

Callbacks

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

get state of pay request

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

Response samples

200

Content type

application/json

[{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string",
"PayItemID": null
}
]

get result of a pay request and purges state from queue/processor

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

Response samples

200

Content type

application/json

Example

payment

response to PayRequestHobexPaymentMinimum_1

{"Protocol": "hobex_restapi",
"ftQueueId": "00000000-0000-0000-0000-xxxxxxxxxxxx",
"ftPayItems": [{"ftPayItemId": "00000000-0000-0000-0000-xxxxxxxxxxxx",
"Description": "Card",
"Amount": 1.5,
"ftPayItemCase": 14757170079003050000,
"ftPayItemCaseData": {"Receipt": ["Line1",
"Line2",
"Line3",
"Line4"
],
"Provider": {"Protocol": "hobex_restapi",
"Action": "payment",
"ProtocolRequest": {"transaction": {"transactionType": 1,
"transactionId": "20181009140821075",
"tid": "3510224",
"currency": "EUR",
"reference": "123",
"amount": 1.5,
"language": "DE"
}
},
"ProtocolResponse": {"transactionId": "20181009140821075",
"originalTransactionId": "",
"tid": "3510224",
"receipt": "632030",
"approvalCode": "00884601",
"reference": "123",
"transactionDate": "2018-10-09T14:07:00.9436463+02:00",
"cardNumber": "XXXXXXXXXXXX5401",
"cardExpiry": "1220",
"brand": "Maestro",
"cardIssuer": "MAESTRO",
"transactionType": "SELL",
"currency": "EUR",
"amount": 1.5,
"responseCode": "0",
"responseText": "OK",
"cvm": 3
}
}
},
"Moment": "2020-06-29T17:45:40.505Z"
}
]
}

sign

finalize receipts

successfull

timeout / retry

failed

callback usage

starts a sign request

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-finalized	any (x-operation-callback-finalized) single callback setting for current operation, executed once the operation is in final state, `done` or `failed`
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
x-possystem-id	any (x-possystem-id) identifies the calling possystem #TODO

Request Body schema: application/json

cbTerminalID	string <= 1023 characters Default: "undefined" The unique identification of the input-station/terminal within a cash-register/pos-system identified by `ftCashBoxID`.
cbReceiptReference required	string <= 1023 characters Default: "undefined" Reference number send by the cash register. This value must be a unique string/receipt number related to the calling cash register. This string/receipt number is a unique primary key of the dataset of the cash register.
cbReceiptMoment required	string <date-time> moment at which the receipt was create by the cash register, must be provided in UTC.
required	Array of objects (ChargeItem) list of line items related to services and products
required	Array of objects (PayItem) list of line items related to payments
ftCashBoxID	string <uuid> Default: "00000000-0000-0000-0000-000000000000" identification of the cash register
ftPosSystemID	string <uuid> Default: "00000000-0000-0000-0000-000000000000" identification of the used software of the cash register
ftReceiptCase	integer <uint64> Default: 0 Type of business according to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO! this is relevant for fiskaltrust middleware processing and is a country specific mapping. as fallback when not specified, a cash register business case at the point-of-sale is used.
	(string or null) or object optional gives additional details for defined type of business related to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO!
ftQueueID	string or null <uuid> Default: null optional routing instruction to identify a specific queue behind a load balancer or in other usecases
cbPreviousReceiptReference	string or null <= 1023 characters Default: null optional Reference `cbReceiptReference` of the previous receipt. Used to connect multiple requests for a single Business Case.
	(integer or null) or (number or null) Default: null optional total receipt amount, including value added taxes (=gross receipt amount) given to avoid calculation and rounding differences. systems which are using net amounts as central calculation should alsways use this property. if not provided, the sum of `Amount` in all provided `ftChargeItems` is used as total receipt amount. uses `DecimalPresissionMultiplier` as discriminator between int64 and double
	(string or null) or object Default: null optional Identification of the user, who creates the receipt.
	(string or null) or object Default: null optional Identification of the area/section/field, in which the receipt is created. e.g. Table number of a restaurant business; a department of a commercial establishment; the vehicle of a taxi company
	(string or null) or object Default: null optional Identification of the consumer, for whom the receipt is created. e.g. Email address, phone number, personal tax number
	(string or null) or object Default: null optional Settlement identification where this receipt will be added. e.g. shift number or day of operation
Currency	string (CurrencyEnum) Default: "EUR" Enum: "EUR" "CHF" "CZK" "HUF" "BAM" "DKK" "RON" "NOK" "PLN" "RSD" "SEK" "UAH" "USD" "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYN" "BZD" "CAD" "CDF" "CHE" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUP" "CVE" "DJF" "DOP" "DZD" "EGP" "ERN" "ETB" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HTG" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRU" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PYG" "QAR" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SGD" "SHP" "SLE" "SLL" "SOS" "SRD" "SSP" "STN" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UGX" "USN" "UYI" "UYU" "UYW" "UZS" "VED" "VES" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL" used as currency code for money numbers. along ISO 4217 (https://en.wikipedia.org/wiki/ISO_4217)
DecimalPrecisionMultiplier	integer <int32> (DecimalPrecisionMultiplierEnum) Default: 1 Enum: 1 100 10000 1000000 100000000 is used as multiplier for decimal numbers. when value 1 is used, revlevant numbers are interpreted as floating-point numbers. for all other values, relevant numbers are interpreted as integer and need to be devided by the Multiplier to get the decimal representation.

Responses

Callbacks

Request samples

Payload

Content type

application/json

{"cbTerminalID": "undefined",
"cbReceiptReference": "undefined",
"cbReceiptMoment": "2020-06-29T17:45:40.505Z",
"cbChargeItems": [{"Quantity": 1,
"Description": null,
"Amount": 0,
"VATRate": 0,
"ftChargeItemCase": 0,
"ftChargeItemCaseData": "string",
"VATAmount": null,
"Moment": "2020-06-29T17:45:40.505Z",
"Position": 0,
"AccountNumber": null,
"CostCenter": null,
"ProductGroup": null,
"ProductNumber": null,
"ProductBarcode": null,
"Unit": null,
"UnitQuantity": null,
"UnitPrice": null,
"Currency": "EUR",
"DecimalPrecisionMultiplier": 1
}
],
"cbPayItems": [{"Quantity": 1,
"Description": null,
"Amount": 0,
"ftPayItemCase": 0,
"ftPayItemCaseData": "string",
"Moment": "2020-06-29T17:45:40.505Z",
"Position": 0,
"AccountNumber": null,
"CostCenter": null,
"MoneyGroup": null,
"MoneyNumber": null,
"MoneyBarcode": null,
"Currency": "EUR",
"DecimalPrecisionMultiplier": 1
}
],
"ftCashBoxID": "00000000-0000-0000-0000-000000000000",
"ftPosSystemID": "00000000-0000-0000-0000-000000000000",
"ftReceiptCase": 0,
"ftReceiptCaseData": "string",
"ftQueueID": null,
"cbPreviousReceiptReference": null,
"cbReceiptAmount": null,
"cbUser": null,
"cbArea": null,
"cbCustomer": null,
"cbSettlement": null,
"Currency": "EUR",
"DecimalPrecisionMultiplier": 1
}

Response samples

400
401
500

Content type

application/problem+json

{"type": "http://example.com",
"status": 100,
"title": "string",
"detail": "string",
"instance": "string",
"code": "string",
"errors": [{"detail": "string",
"pointer": "string",
"parameter": "string",
"header": "string",
"code": "string"
}
]
}

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

get state of sign request

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

Response samples

200
400
401
500

Content type

application/json

[{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string",
"QueueItemID": null
}
]

get result of sign request and purges it from queue

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

Response samples

200
400
401
500

Content type

application/json

{"ftQueueID": "00000000-0000-0000-0000-000000000000",
"ftQueueItemID": "00000000-0000-0000-0000-000000000000",
"ftQueueRow": 0,
"ftCashBoxIdentification": "undefined",
"ftReceiptIdentification": "ft0#",
"ftReceiptMoment": "2020-06-29T17:45:40.505Z",
"ftSignatures": [{"ftSignatureItemID": null,
"ftSignatureFormat": 0,
"ftSignatureType": 0,
"Caption": null,
"Data": "string"
}
],
"ftState": 0,
"ftStateData": "string",
"ftCashBoxID": "00000000-0000-0000-0000-000000000000",
"cbTerminalID": "undefined",
"cbReceiptReference": "undefined",
"ftReceiptHeader": ["string"
],
"ftChargeItems": [{"ftChargeItemID": null,
"Quantity": 1,
"Description": null,
"Amount": 0,
"VATRate": 0,
"ftChargeItemCase": 0,
"ftChargeItemCaseData": "string",
"VATAmount": null,
"Moment": "2020-06-29T17:45:40.505Z",
"Position": 0,
"AccountNumber": null,
"CostCenter": null,
"ProductGroup": null,
"ProductNumber": null,
"ProductBarcode": null,
"Unit": null,
"UnitQuantity": null,
"UnitPrice": null,
"Currency": "EUR",
"DecimalPrecisionMultiplier": 1
}
],
"ftChargeLines": ["string"
],
"ftPayItems": [{"ftPayItemID": null,
"Quantity": 1,
"Description": null,
"Amount": 0,
"ftPayItemCase": 0,
"ftPayItemCaseData": "string",
"Moment": "2020-06-29T17:45:40.505Z",
"Position": 0,
"AccountNumber": null,
"CostCenter": null,
"MoneyGroup": null,
"MoneyNumber": null,
"MoneyBarcode": null,
"Currency": "EUR",
"DecimalPrecisionMultiplier": 1
}
],
"ftPayLines": ["string"
],
"ftReceiptFooter": ["string"
]
}

issue

distribute receipts

starts an issue request

execute a issue call end-to-end publish a digital receipt

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-finalized	any (x-operation-callback-finalized) single callback setting for current operation, executed once the operation is in final state, `done` or `failed`
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given
x-possystem-id	any (x-possystem-id) identifies the calling possystem #TODO

Request Body schema: application/json

One of

required	object (ReceiptRequest_1) The cash register transfers the data of an entire receipt request to the fiskaltrust.Middleware using the ReceiptRequest data structure.
required	object (ReceiptResponse_1) The fiskaltrust.Middleware sends back the processed data to the cash register through the receipt response.

Responses

Callbacks

Request samples

Payload

Content type

application/json

Example

IssueRequest

{"ReceiptRequest": {"ftCashBoxID": "string",
"ftQueueID": "string",
"ftPosSystemId": "string",
"cbTerminalID": "string",
"cbReceiptReference": "string",
"cbReceiptMoment": "2019-08-24T14:15:22Z",
"cbChargeItems": [{"position": 0,
"quantity": 0.1,
"description": "string",
"amount": 0.1,
"vatRate": 0.1,
"ftChargeItemCase": 0,
"ftChargeItemCaseData": "string",
"vatAmount": 0.1,
"accountNumber": "string",
"costCenter": "string",
"productGroup": "string",
"productNumber": "string",
"productBarcode": "string",
"unit": "string",
"unitQuantity": 0.1,
"unitPrice": 0.1,
"moment": "2019-08-24T14:15:22Z"
}
],
"cbPayItems": [{"position": 0,
"quantity": 0.1,
"description": "string",
"amount": 0.1,
"ftPayItemCase": 0,
"ftPayItemCaseData": "string",
"accountNumber": "string",
"costCenter": "string",
"moneyGroup": "string",
"moneyNumber": "string",
"moment": "2019-08-24T14:15:22Z"
}
],
"ftReceiptCase": 0,
"ftReceiptCaseData": "string",
"cbReceiptAmount": 0.1,
"cbUser": "string",
"cbArea": "string",
"cbCustomer": "string",
"cbSettlement": "string",
"cbPreviousReceiptReference": "string"
},
"ReceiptResponse": {"ftCashBoxID": "string",
"ftQueueID": "string",
"ftQueueItemID": "string",
"ftQueueRow": 0,
"cbTerminalID": "string",
"cbReceiptReference": "string",
"ftCashBoxIdentification": "string",
"ftReceiptIdentification": "string",
"ftReceiptMoment": "2019-08-24T14:15:22Z",
"ftReceiptHeader": ["string"
],
"ftChargeItems": [{"position": 0,
"quantity": 0.1,
"description": "string",
"amount": 0.1,
"vatRate": 0.1,
"ftChargeItemCase": 0,
"ftChargeItemCaseData": "string",
"vatAmount": 0.1,
"accountNumber": "string",
"costCenter": "string",
"productGroup": "string",
"productNumber": "string",
"productBarcode": "string",
"unit": "string",
"unitQuantity": 0.1,
"unitPrice": 0.1,
"moment": "2019-08-24T14:15:22Z"
}
],
"ftChargeLines": ["string"
],
"ftPayItems": [{"position": 0,
"quantity": 0.1,
"description": "string",
"amount": 0.1,
"ftPayItemCase": 0,
"ftPayItemCaseData": "string",
"accountNumber": "string",
"costCenter": "string",
"moneyGroup": "string",
"moneyNumber": "string",
"moment": "2019-08-24T14:15:22Z"
}
],
"ftPayLines": ["string"
],
"ftSignatures": [{"ftSignatureFormat": 0,
"ftSignatureType": 0,
"caption": "string",
"data": "string"
}
],
"ftReceiptFooter": ["string"
],
"ftState": 0,
"ftStateData": "string"
}
}

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

updates an issue request

execute a issue call end-to-end

Authorizations:

(CashBoxIdCashBoxAccessToken)

path Parameters

QueueId required	string <uuid>
QueueItemId required	string <uuid>

header Parameters

x-operation-id	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-operation-callback-finalized	any (x-operation-callback-finalized) single callback setting for current operation, executed once the operation is in final state, `done` or `failed`
x-operation-callback-state	any (x-operation-callback-state) single state callback setting for current operation, executed each time when a status change occures
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Request Body schema: application/json

Action

required

string (IssueUpdateActionEnum)

accept

Responses

Callbacks

Request samples

Payload

Content type

application/json

Example

accept

{"Action": "accept"
}

Callback payload samples

Callback

POST: OperationCallbackStateUrl

Content type

application/json

{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string"
}

get state of issue request

get state of sign request

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-terminal-id	any (x-terminal-id) terminal identification

Responses

Response samples

200

Content type

application/json

[{"OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
"QueueID": null,
"State": "done",
"StateMessage": null,
"StateData": "string",
"QueueItemID": null
}
]

get result of issue request and purges the state from queue/processor

get result of issue request and purges it from queue/processor

Authorizations:

(CashBoxIdCashBoxAccessToken)

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

Response samples

200

Content type

application/json

{"ftQueueID": "fb6ee7af-f98e-4d5a-891b-ff24d7313836",
"ftQueueItemID": "92273d5f-5d3a-4415-bfc8-f7895ceaecf6",
"DocumentURL": "http://example.com",
"DocumentContentType": "string"
}

blocks for a maxiumum timeout in second (default is 15) and comes back with 200 if delivered and 204 if not deliverd

TBD

Authorizations:

(CashBoxIdCashBoxAccessToken)

path Parameters

QueueId required	string <uuid>
QueueItemId required	string <uuid>

query Parameters

Timeout

number <int>

Default: 15

Responses

Response samples

200

Content type

application/json

{ }

blocks for a maxiumum timeout in second (default is 15) and comes back with 200 if delivered and 204 if not deliverd

TBD TEST

Authorizations:

(CashBoxIdCashBoxAccessToken)

path Parameters

QueueId required	string <uuid>
QueueItemId required	string <uuid>

query Parameters

Timeout

number <int>

Default: 15

Responses

Response samples

200

Content type

application/json

{ }

journal

export data

get a single journal entry by id

Authorizations:

(CashBoxIdCashBoxAccessToken)

path Parameters

QueueId required	string <uuid>
StorageType required	string (StorageTypeEnum) Enum: "OperationItem" "OperationStateJournal" "PayItem" "ChargeItem" "QueueItem" "IssueItem" "ActionJournal" "ReceiptJournal"
Id required	string <uuid>

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

/PeekJournalRange/{QueueId}/{StorageType}

Authorizations:

(CashBoxIdCashBoxAccessToken)

path Parameters

QueueId required	string <uuid>
StorageType required	string (StorageTypeEnum) Enum: "OperationItem" "OperationStateJournal" "PayItem" "ChargeItem" "QueueItem" "IssueItem" "ActionJournal" "ReceiptJournal"

header Parameters

x-operation-id required	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

configuration

configuration handling and management tools for cash registers

/pair

header Parameters

x-operation-id	any (x-operation-id) operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.
x-operation-lifetime	any (x-operation-lifetime) operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.
x-terminal-id	any (x-terminal-id) identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Request Body schema: application/json

use to get credentials for initial setup

Pin	string <= 1023 characters

Responses

Request samples

Payload

Content type

application/json

{"Pin": "string"
}

Response samples

200

Content type

application/json

{"CashBoxID": "604a88e9-9153-4ab6-9da8-5c8e2b6a2f6b",
"AccessToken": "string"
}

/rebuild

Authorizations:

(CashBoxIdCashBoxAccessToken)

fiskaltrust PosSystem API (2.1)

API design principles

Authentication

Versioning

SynchronAPI

synchronous call pattern

successfull

timeout / retry

failed

Executes a blocking echo call end-to-end

Authorizations:

header Parameters

Request Body schema: application/json

Responses

Callbacks

Request samples

Response samples

Callback payload samples

exectue a cart call end-to-end

Authorizations:

header Parameters

Request Body schema: application/json

Responses

Callbacks

Request samples

Response samples

Callback payload samples

get content of a journey

Authorizations:

path Parameters

Responses

Response samples

updates an ongoing journey

Authorizations:

path Parameters

header Parameters

Request Body schema: application/json

Responses

Callbacks

Request samples

Response samples

Callback payload samples

close ongoing journey

Authorizations:

path Parameters

header Parameters

Responses

Callbacks

Callback payload samples

exectue a order call end-to-end

Authorizations:

header Parameters

Request Body schema: application/json

Responses

Callbacks

Request samples

Response samples

Callback payload samples

stops ongoing order call

Authorizations:

header Parameters

Responses

Callbacks

Callback payload samples

execute a sign call end-to-end

Authorizations:

header Parameters

Request Body schema: application/jsonapplication/yamlapplication/json

Responses

Callbacks

Request samples

Response samples

Callback payload samples

execute a issue call end-to-end

Authorizations:

header Parameters

Request Body schema: application/json

Responses

Callbacks

Request samples

Request Body schema:
application/json