Fiscalisation — Core Concepts (Global)

What lives here - Global formats/bit layouts for the three “cases” - ftChargeItemCase (charge item level) - ftPayItemCase (payment item level) - ftReceiptCase (fiscalisation level) - Shared payload fields and validation rules

What’s not here - Per-country mappings (e.g. GR myDATA, IT NI markers), PP lists, VAT indices, and long JSON samples — these live in the Business Tautorials pages.

• Overview
  
• Benefits
  
• POS Integrations
  
  • How to Fiscalize POS Payments
    
  • Fiscalisation Data Object
    
  • Fiscalisation Data Parameters
    
  • Country overlays (Greece etc.)
• Fiscalisation response and receipt handling
• E-commerce
  
• Account setup
  

• Get Support

• Item / payment / receipt bit layouts

  • ftChargeItemCase (line level)
  • ftPayItemCase (payment level)
  • ftReceiptCase (receipt level)

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. 2This information must be printed on the receipt and provided to the customer.

Ensuring that a POS payment is tax-compliant is straightforward:

• Your payment integration stays the same (Inter-app / Cloud / P2P).
• You add a single extra object to your sale request: fiscalisationData.
• This object contains:
  • The items sold (cbChargeItems)
  • The payments (cbPayItems)
  • Optional user / customer context (cbUser, cbCustomer)
  • The fiscal receipt type (ftReceiptCase) and any mandatory local data (ftReceiptCaseData)

The fiscalisationData shape is the same across all POS integrations (Inter-app, Cloud Terminal, P2P). By understanding what to put into this object, you can plug fiscalisation into any Viva POS flow.

Viva Fiscalisation:

1. Validates and signs the transaction against the relevant national scheme.
2. Returns the fiscalised receipt, including the signature / hash / QR data required by the tax authorities.
3. You print or show these details on the receipt and hand them to the customer.

Encoding & validation (applies everywhere)

• All ft…Case values are sent as decimal Int64, but constructed from a hex pattern (CCCC_vlll_gggg_NN S V). Convert hex → decimal before sending.
• Amount is in the smallest currency unit (e.g. €12.45 → 1245) for items, payments and totals.
  (The only exceptions are explicitly documented in country overlays, e.g. human-readable HashPayload amounts.)
• Times are ISO-8601 UTC (e.g. 2025-08-27T00:01:06Z).
• Currency codes are ISO-4217 numeric (e.g. EUR = 978).
• For Inter-app (app-to-app) integrations, the fiscalisationData object is Base64URL-encoded and passed via the deeplink URI payload.

The fiscalisationData object

At a high level, fiscalisationData groups 3 layers of information:

1. Line-level

   • cbChargeItems[] — what is being sold (goods / services / other lines).
     
   • cbPayItems[] — how the receipt is being paid.

2. Receipt-level

   • ftReceiptCase — what type of receipt/invoice it is.
     
   • ftReceiptCaseData — mandatory per-country extra data (e.g. Series / AA / MerchantVATID).
     
   • cbReceiptMoment, cbReceiptReference, optional cbPreviousReceiptReference, cbArea, cbReceiptAmount, currencyCode.

3. Context (optional but recommended)

   • cbUser — who is issuing the receipt (merchant / cashier).
     
   • cbCustomer — who the customer is (B2B/B2C, address, VAT, country).

Country-specific logic (e.g. Greece myDATA Document Type / Category / Characterisation Type or Italian NI/N2 codes) is derived from a combination of:

• ftReceiptCase
• ftChargeItemCase (especially Type of Service)
• cbCustomer data (B2B / B2C / EU / third country)
• Sometimes other flags in ftReceiptCaseData

Detailed mappings live in Regional Examples (e.g. Greece, Italy).

Country overlays for fiscalisationData

{
  "cbChargeItems": [
    {
      "amount": 2300,
      "description": "Product x",
      "position": 1,
      "moment": "2025-07-17T08:11:06Z",
      "quantity": 100,
      "vatRate": 2400,
      "vatAmount": 445,
      "ftChargeItemCase": 5139205309155246099, // supply of goods
      "currencyCode": 978
    }
  ],
  "cbPayItems": [
    {
      "amount": 2300,
      "description": "card-payment",
      "position": 1,
      "currencyCode": "978",
      "moment": "2025-07-17T08:11:06Z",
      "ftPayItemCase": 5139205309155246084 // card payment
    }
  ],
  "cbReceiptMoment": "2025-07-17T08:11:06Z",
  "cbReceiptReference": "receiptreference1",
  "cbArea": "table1",
  "ftReceiptCase": 5139205309155246081, // POS receipt 11.1
  "cbReceiptAmount": 2300,
  "currencyCode": "978",
  "ftReceiptCaseData": {
    "GR": {
      "MerchantVATID": "098000979",
      "Series": "A",
      "AA": 397717,
      "HashAlg": "sha256",
      "HashPayload": "098000979-A-397717-receiptreference1-2025-07-17T08:11:06Z-23.0"
    }
  }
}

fiscalisationData parameters (receipt level)

All time-related fields must be sent in ISO 8601 UTC format, e.g. 2025-08-27T00:01:06Z.

For country-specific rules (e.g. how ftReceiptCase maps to “Invoice vs Receipt” in Greece or Italy), see Country overlays / Regional Examples.

cbChargeItems (line items) — shared fields

These fields and types are the same regardless of country; only mappings (NN / S / V meaning) vary by country.

cbPayItems (payments) — shared fields

Fields are global; country overlays may extend them with local PP (payment type) lists or extra requirements.

cbUser — shared fields

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 — shared fields

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

Example

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

Receipt classification — shared concepts

A dedicated page documents the bit layout and examples:

• ftReceiptCase

Typical use cases:

• POS receipt
  
• Invoice / credit note
  
• Payment transfer / protocol payment
  
• Orders (non-fiscal slips)
  

Local schemes (e.g. GR myDATA, IT SDI) derive their own document types from ftReceiptCase plus:

• ftChargeItemCase (Type of Service)
• cbCustomer (B2B/B2C, domestic/EU/third country)
• Optional extra flags in ftReceiptCaseData.

For full country logic, see:

• Business Tautorials → Greece
  
• Business Tautorials → Italy
  
• …and so on for each onboarded country.

Fiscalisation response and receipt handling

When you fiscalize a transaction via a sale request, the response contains critical fiscalization data that ensures the transaction complies with the relevant fiscal regulations. Among the details returned, two key parameters(transmissionIndicator and signatures) stand out and should be carefully reviewed. It is important to note that these fiscalization details, should also be printed or displayed on the receipt according to instructions below. Including this information is a legal requirement in many fiscal jurisdictions.

Fiscalisation Response

ftState

Format

The hex format of the ftState parameter on fiscalization level is as follows.

CCCC_vlll_gggg_gggg

• CCCC = 4752 | The two ASCII letters that specify the ISO country code (https://en.wikipedia.org/wiki/ISO_3166-1) (e.g. GR = 4752)
  
• vlll = 2000 | This section is for versioning the tagging system (the current is the v2) (e.g. 2000)
  
• gggg_gggg = 0000_0000 | This item is used for flag. Flag can change the basic behavior of a given type
  

Example

4752_2000_0000_000

ftState Global tagging/flag values(gggg_gggg)

transmissionIndicator

This parameter reflects the status of the fiscal data’s transmission to the tax authority or fiscal system. It indicates whether the transaction was successfully reported, is pending transmission, or encountered an error. Monitoring this value is crucial for audit readiness and legal compliance, especially in jurisdictions where real-time or near-real-time reporting is mandatory.

Please note: The cash register must always create a URI and generate a QR code using the following steps and print it on the receipt:

1- Use the base URL supplied by Viva.
For demo: https://r-sb.ft.ms/
For production: https://r.ft.ms/
2- Generate a Base64URL-encoded SHA-256 of HashPayload string: MerchantVATID-Series-AA-cbReceiptReference-cbReceiptMoment-Amount (same as passed in the HashPayload field under ftReceiptCaseData)
- Example input string for SHA-256 hashing: 098000979-ABC-123456-ReceiptReferenceX123-2025-07-15T14:57:55Z-12.4
- Example Base64 representation of a hashed string: Y2M0NjI2ZjU1N2RlYjIwNmNjNmRmNmFjY2ZjNzRmNWMyYjE4NTJiODA4YjQ0MzI5NzU5ZjM0MDhlZGY3Y2YwYw
3- Append the encoded hash to the base URL to form the final URI. Generate a QR code from that URI and print it on the receipt.
Example URI for generating a QR code: https://r-sb.ft.ms/Y2M0NjI2ZjU1N2RlYjIwNmNjNmRmNmFjY2ZjNzRmNWMyYjE4NTJiODA4YjQ0MzI5NzU5ZjM0MDhlZGY3Y2YwYw

Please see the below table for more detailed scenarios.

ftSignatures

ftSignatureType

The format of the ftsignaturetype parameter on signature level, should be as follows.

CCCC_vlll_gggg_tsss

• CCCC = 4752 | The two ASCII letters that specify the ISO country code (https://en.wikipedia.org/wiki/ISO_3166-1) (e.g. GR = 4752)
  
• vlll = 2000 | This section is for versioning the tagging system (the current is the v2) (e.g. 2000)
  
• gggg = 0000 | This item is used for flag. Flag can change the basic behavior of a given type.
• tsss = 0000 | `t`flag stands for Type/Category. `sss` flag stands for SignatureCase.

Example

The corresponding decimal value of ftSignatureType(4752_2000_0000_0001) is 5139205309155246081.

t - Type/Category

sss - SignatureCase

gggg - Global Flags

Response Example

The following data sample is returned during session retrieval, whether through the Cloud REST API or the Local Terminal API, or as a Base64-encoded format in inter-app responses when using app-to-app integration.

{
  "signatures": [
    {
      "caption": "invoiceUid",
      "data": "FDF3F4414097B4786363FA8A70A98653CFC92B0C",
      "format": 1
    },
    {
      "caption": "invoiceMark",
      "data": "400001948544829",
      "format": 1
    },
    {
      "caption": "authenticationCode",
      "data": "D4824EB973D3E0E2A802FC0FF55B1283F22A8629",
      "format": 1
    },
    {
      "caption": "[www.fiskaltrust.gr]",
      "data": "https://receipts-sandbox.fiskaltrust.eu/8c0a4594-ab69-43bb-a7ef-ebc4bef51494/8abf2ada-afa8-4616-a07a-562dbe1ee211",
      "format": 3
    },
    {
      "caption": "Σημείωση: Με βάση την ΠΟΛ.1002/2014 (ΦΕΚ Β’ 3/2-1-2014), τα δεδομένα αυτά δεν επιδέχονται αλλοίωση.",
      "data": "112545020|27/03/2025|0|Item113|0|128",
      "format": 1
    },
    {
      "caption": "S A N D B O X",
      "data": "8c0a4594-ab69-43bb-a7ef-ebc4bef51494",
      "format": 1
    }
  ],
  "transmissionIndicator": 0
}

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!