Skip to main content
API docs by Redocly

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.

Operations and header 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 and body will block until the operation is finished is.
Example - 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 immediately; otherwise it returns when finished.

POS System identification and header x-possystem-id

Each POS system variant must be registered in the fiskaltrust portal and gets assigned a unique POS System ID. This POS System ID needs to be sent in the header of each request to the POS System API where required. By this, the Middleware can identify the caller and apply specific logic if needed. For further detials see the header parameter x-possystem-id in the components section or in the individual endpoint documentation.

General datatype restrictions if not mentioned separately

  • All string properties have a maximum length of 1023 characters unless mentioned otherwise.
  • All date-time properties are in UTC and use the ISO 8601 format. Example: 2026-01-30T13:30:27Z

/echo

Health check

/echo - health check

This method can be used to perform a basic health and communcation check.

Special Case for a cloud cashbox - Force reset of cached config: If the cashbox is a cloud based cashbox (= using the URLs as defined in the servers section above), the special case can be triggered to force a reset of the cached configuration. The point is that the cloud based cashboxes do cache their configuration for about 1h. When changing the configuration in the portal (and do a rebuild), this change is not immediately visible to the cashbox. The new configuration will be picked up latest after the caches expire which will happen after 1h where the cashbox was not used. To be sure a reset can be enforced via the /echo request by setting the message field in the body of this request to null.

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
string <uuid>
Example: 3ff388ce-96e4-4f19-9f19-b24ef38ec2b6

Operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communication issues or communication network switch. Calls or messages with same OperationId schould end up in only one action.

x-possystem-id
required
string

Identifies the calling possystem.
For development and dev-testing purposes when using the fiskaltrust sandbox environment, you can use "000000000000-0000-0000-0000-000000000000" as value.
For production usage and release tests you have to use a valid possystem id issued by fiskaltrust by adding/registering a "POS System" in the fiskaltrust portal. Further details about POS System registration can be found in the fiskaltrust PosCreator documentation described in the section about PosDealer onboarding.

Request Body schema: application/json
Message
string

The message to be echoed back. Special case for cloud cashboxes - set to null to force reset of cached config.

Responses

Request samples

Content type
application/json
{
  • "Message": "Hello fiskaltrust!"
}

Response samples

Content type
application/json
{
  • "Message": "string"
}

/pay

Execute payments

/pay - payment handling

Allows to execute payment actions like payment, cancel or refund via connected/configured payment providers

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
string <uuid>
Example: 3ff388ce-96e4-4f19-9f19-b24ef38ec2b6

Operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communication issues or communication network switch. Calls or messages with same OperationId schould end up in only one action.

x-possystem-id
required
string

Identifies the calling possystem.
For development and dev-testing purposes when using the fiskaltrust sandbox environment, you can use "000000000000-0000-0000-0000-000000000000" as value.
For production usage and release tests you have to use a valid possystem id issued by fiskaltrust by adding/registering a "POS System" in the fiskaltrust portal. Further details about POS System registration can be found in the fiskaltrust PosCreator documentation described in the section about PosDealer onboarding.

Request Body schema: application/json
One of
Protocol
required
string (PaymentProtocolEnum)
Enum: "use_auto" "gp_softpos_gptom" "gp_mpas" "payone_softpos_wpi" "hobex_softpos_posit" "viva_eft_pos_instore" "hobexecr" "softpayio" "shift4" "test"

a list of supported protocols

  • use_auto triggers a automaticaly selected, single payment protocol, best match for given PayItemCase; it depends on the target device which ones are available/configured and used
  • gp_softpos_gptom ... GP tom SoftPOS app (from Global Payments; actions: payment)
  • gp_mpas ... Global Payments via dedicaited payment terminal (like PAX A920 Pro from Global Payments; actions: payment)
  • payone_softpos_wpi ... PayOne SoftPOS app (actions: payment)
  • hobex_softpos_posit ... Hobex POSit SoftPOS payment app (actions: payment)
    Not supported as enum values but supported via device configuraiton and using protocol "use_auto":
  • viva_eft_pos_instore ... Viva Wallet SoftPOS app (actions: payment, refund, cancel)
  • hobexecr ... Hobex ecr protocol via dedicated payment terminal (like Sunmi P2 Pro from Hobex; actions: payment)
  • softpayio ... Softpay.io SoftPOS app (actions: payment)
  • shift4 ... Shift4 SoftPOS app (actions: payment, refund, cancel)
  • test ... Dummy Payment Provider, only available when developer mode is activated in InStore app (actions: payment, refund, cancel)
Action
required
any

Execute a new payment transaction

Value: "payment"
required
object (PayItemRequest)

The payment request item

cbTerminalID
string
Default: "undefined"

Allows to identify a specific target device/terminal or group that should process the request.
See cbTerminalID settings documentation for the InStore App about further details how to use this property.
Example: If you use just a signgle device / terminal in a site the cbTerminalID can be ignored (= undefined)
Example: If you use multiple devices the idea is to assign a unique cbTerminalID per device / terminal and use this property to address a specific device / terminal.

Responses

Request samples

Content type
application/json
Example

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

{
  • "Action": "payment",
  • "Protocol": "use_auto",
  • "cbPayItem": {
    },
  • "cbTerminalId": 1
}

Response samples

Content type
application/json

response to PayRequestUseAuto

{
  • "Protocol": "use_auto",
  • "ftQueueId": "00000000-0000-0000-0000-xxxxxxxxxxxx",
  • "ftPayItems": [
    ]
}

/sign

Sign receipts

/sign - fiscalize (sign) a receipt

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 (see ftReceiptCase, ftChargeItemCase and ftPayItemCase).

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
string <uuid>
Example: 3ff388ce-96e4-4f19-9f19-b24ef38ec2b6

Operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communication issues or communication network switch. Calls or messages with same OperationId schould end up in only one action.

x-possystem-id
required
string

Identifies the calling possystem.
For development and dev-testing purposes when using the fiskaltrust sandbox environment, you can use "000000000000-0000-0000-0000-000000000000" as value.
For production usage and release tests you have to use a valid possystem id issued by fiskaltrust by adding/registering a "POS System" in the fiskaltrust portal. Further details about POS System registration can be found in the fiskaltrust PosCreator documentation described in the section about PosDealer onboarding.

Request Body schema: application/json
One of
cbReceiptReference
required
string

Reference number created by the caller. 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 has been created by the cash register; must be provided in UTC.

required
Array of objects (ChargeItemBasic)

List of charge items related to services and products (e.g. sold products).

required
Array of objects (PayItemResponse)

List of line items related to payments; when using the /pay endpoint for payment the ftPayItems from the payment response can be used without alteration.

ftReceiptCase
integer <uint64>

Type of business according to fiskaltrust reference. 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.

cbPreviousReceiptReference
string

Reference cbReceiptReference of the previous receipt. Used to connect multiple requests for a single Business Case.

Responses

Request samples

Content type
application/json
Example

As no case values are given in this example, the following fallbacks are used:

  • ftReceiptCase fallback to 0xCCCC_2000_0000_0000
  • ftChargeItemCase fallback to 0xCCCC_2000_0000_0000
  • ftPayItemCase fallback to 0xCCCC_20000_0000_0000
{
  • "cbReceiptReference": "1234",
  • "cbReceiptMoment": "2023-11-24T15:22:07Z",
  • "cbChargeItems": [
    ],
  • "cbPayItems": [
    ]
}

Response samples

Content type
application/json
{
  • "ftQueueID": "fb6ee7af-f98e-4d5a-891b-ff24d7313836",
  • "ftQueueItemID": "92273d5f-5d3a-4415-bfc8-f7895ceaecf6",
  • "ftQueueRow": 0,
  • "ftCashBoxIdentification": "string",
  • "ftReceiptIdentification": "ft2BC#685",
  • "ftReceiptMoment": "2020-06-29T17:45:40.505Z",
  • "ftSignatures": [
    ],
  • "ftState": 0,
  • "ftStateData": { },
  • "ftCashBoxID": "c449dc9e-d1c1-487a-8aed-2f76c570a18c",
  • "cbTerminalID": "string",
  • "cbReceiptReference": "string",
  • "ftReceiptHeader": [
    ],
  • "ftChargeItems": [
    ],
  • "ftChargeLines": [
    ],
  • "ftPayItems": [
    ],
  • "ftPayLines": [
    ],
  • "ftReceiptFooter": [
    ]
}

/issue

Distribute receipts (digitally or printed)

/issue - receipt delivery

issue (= create) a new receipt that can be retrieved digitally (or printed via the InStore App)

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
string <uuid>
Example: 3ff388ce-96e4-4f19-9f19-b24ef38ec2b6

Operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communication issues or communication network switch. Calls or messages with same OperationId schould end up in only one action.

x-possystem-id
required
string

Identifies the calling possystem.
For development and dev-testing purposes when using the fiskaltrust sandbox environment, you can use "000000000000-0000-0000-0000-000000000000" as value.
For production usage and release tests you have to use a valid possystem id issued by fiskaltrust by adding/registering a "POS System" in the fiskaltrust portal. Further details about POS System registration can be found in the fiskaltrust PosCreator documentation described in the section about PosDealer onboarding.

Request Body schema: application/json
required
object (ReceiptRequest)

The cash register transfers the data of an entire receipt request to the fiskaltrust.Middleware using the ReceiptRequest data structure.
The field fiskaltrust receipt case (ftReceiptCase) is of the highest importance for the correct processing of the receipt. This field defines the receipt type, determines if the receipt has to be secured accordingly to the national law, and establishes the method to calculate the correct values for each national counter.

required
object (ReceiptResponse)

fiskaltrust.Middleware sends back the processed data to the cash register through the receipt response. The data included in the request, such as header, service, pay items, and footer, will not be sent back. The returned data is added to the receipt as supplement to the data of the receipt request.

Responses

Request samples

Content type
application/json

This example shows how to issue a receipt by providing both the original ReceiptRequest and the ReceiptResponse received from the /sign endpoint. This is used to register receipts that were already signed by fiskaltrust.Middleware.

{
  • "ReceiptRequest": {
    },
  • "ReceiptResponse": {
    }
}

Response samples

Content type
application/json
{}

/issue/{QueueId}/{QueueItemId} - get receipt data

get content of an issued receipt in requested format (png, pdf, json), without updateing the submitted state

Authorizations:
(CashBoxIdCashBoxAccessToken)
path Parameters
QueueId
required
string <uuid>
QueueItemId
required
string <uuid>

Responses

Response samples

Content type
No sample

/issue/{QueueId}/{QueueItemId}/link/qrcode - receipt web link as qr code

get qr code for digital receipt url to show it on your pos system display similar to the InStore App
example:

Authorizations:
(CashBoxIdCashBoxAccessToken)
path Parameters
QueueId
required
string <uuid>
QueueItemId
required
string <uuid>

Responses

Response samples

Content type
image/png
iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6CAYA-this-is-not-a-valid-png-and-just-here-as-a-sample-but-in-real-reasponses-a-valid-one-is-returned-AAA+8c9mZt2rV

/issue/{QueueId}/{QueueItemId}/delivered - query delivery status

check if the issued receipt was delivered to the customer at least once (e.g. printed or sent via email/SMS)

Authorizations:
(CashBoxIdCashBoxAccessToken)
path Parameters
QueueId
required
string <uuid>
QueueItemId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "state": "Printed",
  • "message": "Receipt was printed at 01/30/2026 00:03:57. DeliveryMethod: customeraccepted"
}

/journal

Export data

/journal - export operation data

Authorizations:
(CashBoxIdCashBoxAccessToken)
path Parameters
Id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "cbOperationItemID": "36d02d55-8ae3-4779-80f1-700c92e17671",
  • "ftQueueID": "fb6ee7af-f98e-4d5a-891b-ff24d7313836",
  • "Method": "POST",
  • "Path": "/sign",
  • "RequestHeaders": { },
  • "Request": "string",
  • "Response": "string",
  • "ResponseCode": 0,
  • "LastState": "done",
  • "TimeStamp": "2019-08-24T14:15:22Z",
  • "ftOperationItemMoment": "2019-08-24T14:15:22Z"
}