Navigation:

Fiscalisation

Helps POS software vendors comply with fiscalization laws and VAT reporting for B2C, B2B and B2G sales across Europe via a single, lightweight app.

Overview
Benefits
POS Integrations
Understanding ftreceiptcase
Examples of Usage
- Json Object for Cloud REST API and Local Terminal API integrations
- Base64 encoded format for interapp integration
E-commerce
Account setup
Get Support

Overview

Viva Fiscal API is designed to help businesses comply with fiscalization laws, especially in countries with strict regulations on tax reporting and cash register security. It acts as an intermediary between a company’s point-of-sale (POS) system and government tax authorities, ensuring that all transactions are accurately recorded, securely signed, and transmitted in compliance with legal requirements.

Viva Fiscalisation is available for the below countries,

Benefits

Legal Compliance – Many countries, such as Germany and Austria, enforce strict fiscal laws requiring businesses to securely record transactions. The Viva Fiscal API ensures businesses meet these regulations seamlessly.
Security & Integrity – Protects against tax fraud by ensuring all sales data is securely stored and transmitted in an immutable format.
Automation & Efficiency – Reduces manual errors and administrative burdens by automating tax reporting.
Seamless Integration – Enables businesses to integrate fiscal compliance into their existing POS systems with minimal effort.
Handle Government-Mandated Requirements – Some countries require certified fiscalization solutions for all POS systems.

POS Integrations

Viva offers Auto Fiscalization functionality within its POS integrations, providing an electronic fiscalization service that allows businesses to record, process, and store transactions digitally. This ensures transparency, accuracy, and compliance without complex procedures.

Fiscalization is available through:

Local Terminal API – Local ECR integration
InterApp Integration – Terminal/SoftPos Interapp integration
Cloud Terminal API – POS integration via Cloud Terminal API

Merchants and ISV partners do not need to allocate resources for fiscalization integration, as all transactions are automatically fiscalized during payments.

Partners working with other PSPs can also use Viva’s standalone Fiscal API to transmit data to regulators and receive valid receipt information.

The fiscalisation feature is currently available exclusively on our SoftPOS for Android. Please use this link to download the demo version of the Viva Terminal app with fiscalisation enabled and try it out in demo environment.

How to Fiscalize POS Payments

Ensuring that a payment is tax-compliant is quite straightforward. Your integration remains the same, with just one additional object added to your sale requests. This object(fiscalisationData) contains essential data, including the items sold, the payment amount for each item, and the corresponding VAT details. You can find the object structure and its parameters here.

The fiscalisationData is same across all types of POS integrations. By understanding what to include in your requests, you can seamlessly integrate fiscalisation into Viva’s any POS integration. Viva Fiscalisation handles the compliance process by signing the transaction with the relevant authorities. It then returns the receipt details, including the required signature for tax authorities. This information must be printed on the receipt and provided to the customer.

Fiscalisation Data Object

The table below presents the parameter details for the fiscalizationData. The fiscalization data contains the core details required for tax compliance.

Fiscalisation Data Parameters

The fiscalisationData object contains the below parameters.

Value	Description	Example	Mandatory field
cbChargeItems	An array of objects, each representing an individual item sold, including details such as description, quantity, price, and VAT. For more details about cbChargeItems parameter, please click here.	[{“amount”:40,“description”:“description1”,“position”:1,“quantity”:100,“unit”:“pcs”,“unitPrice”:40,“vatAmount”:1,“vatRate”:24,“currencyCode”:“978”,“moment”:“2025-04-24T22:09:32.521Z”,“ftChargeItemCaseData”:{“taxable”:true},“ftChargeItemCase”:5139205309155246083}]	✅
cbPayItems	An array of objects specifying the payment details, including payment method, amount, and references. For more details about cbPayItems parameter, please click here.	[{“amount”:40,“description”:“Card”,“position”:1,“currencyCode”:“978”,“moment”:“2025-04-24T22:09:32.521Z”,“ftPayItemCase”:5139205309155246085}]	✅
cbUser	The data object representing the identification of the user who creates the receipt. For more details about cbUser parameter, please click here.	{“merchantName”:“Merchant”,“cashier”:{“name”:“JohnDoe”,“id”:10}}	❌
cbCustomer	The data object representing the identification of the business customer for whom the receipt is created. For more details about cbCustomer parameter, please click here.	{“customerVATId”:“EL999999999”,“customerCountry”:“GRC”,“customerName”:“ProfessionalServicesLTD”,“customerStreet”:“AmarousiouChalandriou18-20”,“customerZip”:“15125”,“customerCity”:“Athens”}	❌
cbReceiptMoment	The time of receipt creation. Must be provided in UTC	2025-04-24T22:09:32.521Z	✅
cbReceiptReference	The reference number sent by the cash register. Ideally, this should be a unique receipt identifier provided by the cash register, enabling the return value to be stored in the cash register’s dataset.	Unique reference of the receipt	✅
ftReceiptCase	This field defines the receipt type, determines if the receipt has to be secured accordingly to the national law, and establishes the way to calculate the correct values for each national counter. For more details about ftReceiptCase parameter, please click here.	5139205309155246081	✅
currencyCode	The numeric code of the transaction’s currency as defined in ISO 4217	978	✅

Example

The order includes one product, Coffee Latte, with grand total amount of 4 euro (1 item Coffee Latte x 4 euro ). The fiscalisationData sample is as below:

{
    "cbChargeItems": [
        {
            "amount": 400,
            "description": "Coffee Latte",
            "position": 1,
            "quantity": 100,
            "unit": "pcs",
            "unitPrice": 400,
            "vatAmount": 96,
            "vatRate": 24,
            "currencyCode": "978",
            "moment": "{{$isoTimestamp}}",
            "ftChargeItemCaseData": {
                "taxable": true
            },
            "ftChargeItemCase": 5139205309155246083
        }
    ],
    "cbPayItems": [
        {
            "amount": 400,
            "description": "Card",
            "position": 1,
            "currencyCode": "978",
            "moment": "{{$isoTimestamp}}",
            "ftPayItemCase": 5139205309155246085
        }
    ],
    "cbUser": {
        "merchantName": "Merchant",
        "cashier": {
            "name": "John Doe",
            "id": 10
        }
    },
     "cbCustomer":
     {
         "customerVATId": "EL999999",
         "customerCountry": "GRC",
         "customerName": "Professional Services LTD",
         "customerStreet": "Street 18-20",
         "customerZip": "99999",
         "customerCity": "Athens"
     },    
    "cbReceiptMoment": "{{$isoTimestamp}}",
    "cbReceiptReference": "Unique reference of the receipt",
    "ftReceiptCase": 5139205309155246081,
    "currencyCode": "978"
}

cbChargeItems Array

Inside the fiscalisationData object, the cbChargeItems array holds the product/item details that the invoice includes.

Field name	Description	Sample data	Mandatory field	Visualized on receipt
amount	Gross total price of service(s). The gross individual price, net total price, and net individual price, have to be calculated using the amount and VAT rate/amount	400	✅	yes
quantity	Amount or volume (number) of service(s) or items of the entry	1	✅	yes
description	Name, description of customary indication, or type of the service or item	Kaffee	✅	yes
vatRate	VAT rate as percentage	20	✅	yes
ftChargeItemCase	Type of service or item according to the reference table in the appendix. For more details about ftChargeItemCase parameter, please click here.	5139205309155246083	❌	no
Moment	Time of service (UTC format)	2023-08-01T07:47:53.68Z	❌	no
vatAmount	Can be used to calculate the net amount to avoid rounding errors	80	❌	yes
ftChargeItemCaseData	Additional data about the service, currently accepted only in JSON format	{"taxable": true}	❌	currently not*
accountNumber	Account number for transfer into bookkeeping	1234	❌	no
costCenter	Indicator for transfer into cost accounting (type, center, and payer)	1	❌	no
productGroup	This value allows the customer the logical grouping of products	Kaffee	❌	no
productNumber	Value used to identify the product	123	❌	no
productBarcode	Product’s barcode	16514646137	❌	currently not*
unit	Unit of measurement	pcs	❌	no
unitQuantity	Quantity of the service(s) of receipt entry, displayed in indicated units	-	❌	no
unitPrice	Gross price per indicated unit	400	❌	no

ftChargeItemCase Parameter

It’s important to note that the value and usage of ftChargeItemCase parameter can vary from country to country. To understand the specific implementation and requirements for each country, please refer to the links provided below.

Example

The order includes one product, Coffee Latte, with grand total amount of 4 euro (1 item Coffee Latte x 4 euro ). The cbChargeItems sample is as below:

"cbChargeItems":
[
    {
        "amount": 400,
        "description": "Coffee Latte",
        "position": 1,
        "quantity": 100,
        "unit": "pcs",
        "unitPrice": 400,
        "vatAmount": 96,
        "vatRate": 24,
        "currencyCode": "978",
        "moment": "2025-04-24T13:13:28.545Z",
        "ftChargeItemCaseData":
        {
            "taxable": true
        },
        "ftChargeItemCase": 5139205309155246083
    }
]

cbPayItems Array

cbPayItems array holds the payment details that the invoice includes.

Field Name	Description	Sample Data	Mandatory Field
amount	Total amount of payment	400	✅
quantity	Number of payments. This value will be set to 1 in most of the cases. It can be greater than 1 e.g. when paying with multiple vouchers of the same value.	1	✅
description	Name or description of payment	Card	✅
ftPayItemCase	Type of payment according to the reference table in the appendix. It is used in order to determine the processing logic. For more details about ftPayItemCase parameter, please click here.	5139205309155246085	✅
moment	Time of payment. Must be provided in UTC, e.g. 2020-06-29T17:45:40.505Z.	2025-04-24T13:13:28.545Z	❌
position	Line number or position number on the receipt. Used to preserve the order of lines on the receipt.	1	❌
accountNumber	Account number for transfer into bookkeeping	String	❌
costCenter	Indicator for transfer into cost accounting (type, center and payer)	String	❌
moneyGroup	This value allows the logical grouping of payment types.	String	❌
moneyNumber	This value identifies the payment type.	String	❌
currencyCode	Used as currency code for money numbers in ISO 4217	978	✅

ftPayItemCase Parameter

It’s important to note that the value and usage of ftPayItemCase parameter can vary from country to country. To understand the specific implementation and requirements for each country, please refer to the links provided below.

Example

The order includes one product, Coffee Latte, with grand total amount of 4 euro (1 item Coffee Latte x 4 euro ). The cbPayItems sample is as below:

"cbPayItems": [
    {
        "amount": 400,
        "description": "Card",
        "position": 1,
        "currencyCode": "978",
        "moment": "2025-04-24T13:13:28.545Z",
        "ftPayItemCase": 5139205309155246085
    }
]

cbUser Object

cbUser object indicates the user, who creates the receipt. Although all string values are supported, we suggest using data structures serialized into JSON format.

Example

The order includes two products, one Coffee Latte and two Coffee Cappuccino, with grand total amount of 20 euro (1 item Coffee Latte x 10 euro + 2 Coffees Cappuccino x 5 euro). The payments array, will be the below:

"cbUser": {
    "merchantName": "Merchant",
    "cashier": {
        "name": "John Doe",
        "id": 10
    }
}

cbCustomer Object

cbCustomer object is used when the receipt is for a business customer.

Field Name	Description	Sample Data	Mandatory Field
customerName	Name of beneficiary customer.	John Dohn's Company	❌
customerStreet	Street and house number of the beneficiary customer.	York Road	❌
customerZip	Zip of the beneficiary customer.	1234	❌
customerCity	City of the beneficiary customer.	Athens	❌
customerCountry	Country of the beneficiary customer. [ISO 3166 ALPHA-3 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3).	GRC	❌
customerVATId	VAT-ID of the beneficiary customer.	EL999999	❌

Example

"cbUser": {
    "merchantName": "Merchant",
    "cashier": {
        "name": "John Doe",
        "id": 10
    }
}

Understanding ftReceiptCase

It’s important to note that the value and usage of ftReceiptCase parameter can vary from country to country. To understand the specific implementation and requirements for each country, please refer to the links provided below.

Examples of Usage

fiscalisationData for Cloud REST API and Local Terminal API integrations

For Cloud REST API and P2P(LOCAL Terminal API) integrations, please add fiscalisationData JSON object to the request body. This aproach is valid for both standard and ISV integrations.

JSON Format

    "fiscalisationData": {
        "cbChargeItems": [
            {
                "amount": 1,
                "description": "description 1",
                "position": 1,
                "quantity": 100,
                "unit": "pcs",
                "unitPrice": 1,
                "vatAmount": 1,
                "vatRate": 24,
                "currencyCode": "978",
                "moment": "2025-04-22T13:53:32.205Z",
                "ftChargeItemCaseData": {
                    "taxable": true
                },
                "ftChargeItemCase": 5139205309155246083
            }
        ],
        "cbPayItems": [
            {
                "amount": 1,
                "description": "Card",
                "position": 1,
                "currencyCode": "978",
                "moment": "2025-04-22T13:53:32.205Z",
                "ftPayItemCase": 5139205309155246085
            }
        ],
        "cbUser": {
            "merchantName": "Merchant",
            "cashier": {
                "name": "John Doe",
                "id": 10
            }
        },
        "cbReceiptMoment": "2025-04-22T13:53:32.205Z",
        "cbReceiptReference": "Unique reference of the receipt",
        "ftReceiptCase": 5139205309155246085,
        "currencyCode": "978"
    }

fiscalisationData for Interapp(app2app) Integration

For Interapp(app2app) integration, you should encode fiscalisationData JSON object as base64 format and pass it as uri parameter

Base64 format

ewogICAgImNiQ2hhcmdlSXRlbXMiOiBbCiAgICAgICAgewogICAgICAgICAgICAiYW1vdW50IjogMSwKICAgICAgICAgICAgImRlc2NyaXB0aW9uIjogImRlc2NyaXB0aW9uIDEiLAogICAgICAgICAgICAicG9zaXRpb24iOiAxLAogICAgICAgICAgICAicXVhbnRpdHkiOiAxMDAsCiAgICAgICAgICAgICJ1bml0IjogInBjcyIsCiAgICAgICAgICAgICJ1bml0UHJpY2UiOiAxLAogICAgICAgICAgICAidmF0QW1vdW50IjogMSwKICAgICAgICAgICAgInZhdFJhdGUiOiAyNCwKICAgICAgICAgICAgImN1cnJlbmN5Q29kZSI6ICI5NzgiLAogICAgICAgICAgICAibW9tZW50IjogIjIwMjUtMDQtMjJUMTM6NTM6MzIuMjA1WiIsCiAgICAgICAgICAgICJmdENoYXJnZUl0ZW1DYXNlRGF0YSI6IHsKICAgICAgICAgICAgICAgICJ0YXhhYmxlIjogdHJ1ZQogICAgICAgICAgICB9LAogICAgICAgICAgICAiZnRDaGFyZ2VJdGVtQ2FzZSI6IDUxMzkyMDUzMDkxNTUyNDYwODMKICAgICAgICB9CiAgICBdLAogICAgImNiUGF5SXRlbXMiOiBbCiAgICAgICAgewogICAgICAgICAgICAiYW1vdW50IjogMSwKICAgICAgICAgICAgImRlc2NyaXB0aW9uIjogIkNhcmQiLAogICAgICAgICAgICAicG9zaXRpb24iOiAxLAogICAgICAgICAgICAiY3VycmVuY3lDb2RlIjogIjk3OCIsCiAgICAgICAgICAgICJtb21lbnQiOiAiMjAyNS0wNC0yMlQxMzo1MzozMi4yMDVaIiwKICAgICAgICAgICAgImZ0UGF5SXRlbUNhc2UiOiA1MTM5MjA1MzA5MTU1MjQ2MDg1CiAgICAgICAgfQogICAgXSwKICAgICJjYlVzZXIiOiB7CiAgICAgICAgIm1lcmNoYW50TmFtZSI6ICJNZXJjaGFudCIsCiAgICAgICAgImNhc2hpZXIiOiB7CiAgICAgICAgICAgICJuYW1lIjogIkpvaG4gRG9lIiwKICAgICAgICAgICAgImlkIjogMTAKICAgICAgICB9CiAgICB9LAogICAgImNiUmVjZWlwdE1vbWVudCI6ICIyMDI1LTA0LTIyVDEzOjUzOjMyLjIwNVoiLAogICAgImNiUmVjZWlwdFJlZmVyZW5jZSI6ICJVbmlxdWUgcmVmZXJlbmNlIG9mIHRoZSByZWNlaXB0IiwKICAgICJmdFJlY2VpcHRDYXNlIjogNTEzOTIwNTMwOTE1NTI0NjA4NSwKICAgICJjdXJyZW5jeUNvZGUiOiAiOTc4Igp9

E-commerce

While the Fiscal API is not yet available for web payments, it will be launching soon.

Account Setup

To activate fiscalization for your integration, please contact your sales representative.

Get Support

If you would like to integrate with Viva, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!