Germany

Fiscalisation for Germany

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
  
  • How to Fiscalize POS Payments
    
  • Fiscalisation Data Object
    
  • Fiscalisation Data Parameters
    
• 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.

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.

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.

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": 2400,
            "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.

ftChargeItemCase Parameter for Germany

The ftChargeItemCase: in the ‘cbChargeItems’ object defines the type of service or item in the line item block and thus how Viva processes the individual receipts with regards to receipt generation. The data type is Int64 and contains a country specific code which is a value following the ISO-3166-1-ALPHA-2 standard, converted from ASCII into hex and used as byte 8 and 7.

Format

The format of the `ftChargeItemCase` parameter on line item level, should be as below.

Example for lineItem ftChargeItemCase : 4919338167972134913

Calculation: After you identify the type of service value (Eg: The value 4445000000000001 in hexadecimal format in the below table) you should convert it to its decimal equivalent(Eg: 4919338167972134913) and then include it in the request data.

A helpful online tool for your converting tests is [this](https://www.rapidtables.com/convert/number/hex-to-decimal.html).

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": 2400,
        "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.

ftPayItemCase Parameter for Germany

The ftPayItemCase in the ‘cbPayItems’ object indicates the type of payment within the pay items block and defines how the Viva Fiscalisation processes the individual payment in terms of the receipt. The data type is Int64 and contains a country specific code which is a value following the ISO-3166-1-ALPHA-2 standard, converted from ASCII into hex and used as byte 8 and 7.

Format

The format of the `ftPayItemCase` parameter on payments item level, should be as below.

Example for payments ftPayItemCase : 4919338167972134913

Calculation: After you identify the type of payment value (Eg: The value 4445000000000001 in hexadecimal format in the below table) you should convert it to its decimal equivalent(Eg: 4919338167972134913) and then include it in the request data.

A helpful online tool for your converting tests is [this](https://www.rapidtables.com/convert/number/hex-to-decimal.html).

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

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

cbCustomer Object

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

Example

     "cbCustomer":
     {
         "customerVATId": "EL999999",
         "customerCountry": "GRC",
         "customerName": "Professional Services LTD",
         "customerStreet": "Street 18-20",
         "customerZip": "99999",
         "customerCity": "Athens"
     }

Understanding ftReceiptCase for Germany

The ftReceiptCase in the ‘main body’ indicates the receipt type and defines how it should be processed by the Viva Fiscalisation. The data type is Int64 and contains the country specific code, which is a value following the ISO-3166-1-ALPHA-2 standard converted from ASCII into hex and used as byte 8 and 7. For definitions regarding national laws, please refer to each country seperately.

For Germany (DE), the country code is 4445. Thus, the value of an unknown ftReceiptCase in Germany is 4445000000000000.

Example for POS receipt : 4445000000000001

The value 4445000000000001 is in hexadecimal format and needs to be converted to its decimal equivalent, which is 4919338167972134913. Therefore, the value to be included in the request body should be 4919338167972134913.

A helpful online tool for your converting tests is [this](https://www.rapidtables.com/convert/number/hex-to-decimal.html).

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": 2400,
                "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!