☰

Navigation:

Greece

Fiscalisation for Greece

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

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

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:

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

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
position Line number or position number on the receipt. Used to preserve the order of lines on the receipt. 1 ✅ yes
description Name, description of customary indication, or type of the service or item Kaffee ✅ yes
vatRate Represents the value-added tax (VAT) rate, where the last two digits represent the decimal component. For example, a value of 2400 corresponds to a VAT rate of 24.00%, and 850 corresponds to 8.50%. This fixed-point representation avoids floating-point precision issues. 2000 ✅ 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
currencyCode Used as currency code for money numbers in ISO 4217 978 ✅
ftChargeItemCase Parameter for Greece

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 charge item level, should be as follows.

CCCC_vlll_gggg_NNSV

Example

4752_2000_0001_0013

The 4752200000010013 is hex and should be converted to decimal number (5139205309155311635). So, the value that should be passed through in the body request.

A helpful online tool for your converting tests is this.

Flag (gggg)

Value Description
0001 IsVoid
Marks ChargeItem as Void previous position. Quantity and amount are inverted, related to original item.
0002 IsReturn/IsRefund
Marks ChargeItem as Return of good or service. Quantity and amount are inverted, related to original item.
0004 Discount
Marks ChargeItem as Discount/Extra for previous position. Positive (+) amount is extra. Negative (-) amount is discount.
0008 Downpayment
Marks ChargeItem as a downpayment. Positive (+) amount is creation of downpayment. Negative (-) amount is reduction of downpayment.
0010 Returnable
Marks ChargeItem as returnable. Positive (+) amount/quantity is handout. Negative (-) amount/quantity is reverse.
0020 TakeAway
Marks ChargeItem as TakeAway item to prove special VAT application.
8000 ShowInPayments
Visualize the item after Total Amount. This inverts amount and does not include it into the visualized total amount on the receipt.

NN - Nature of VAT

Value Description
00 Usual VAT applies
10
11
12
13
14
15		 Not Taxable

10 = exports
11 = intra-community supplies
12 = transfers to San Marino
13 = transactions assimilated to export supplies
14 = following declarations of intent
15 = other operations which do not contribute to the formation of the ceiling
20 Not Subject

20 = not subject to VAT pursuant to articles from 7 to 7-septies of Presidential Decree 633⁄72.
40 Margin scheme

40 = margin scheme - VAT not shown on invoice.
50 Reverse charge

50 = reverse charge - disposal of scrap and other salvage materials.
60 VAT paid in other EU country

60 = paid in another EU country.
70 VAT distribution
80 Excluded

80 = excluded pursuant to art. 15 of Presidential Decree 633⁄72.

S - Type of Service

Value Description
0 Unknown type of service
1 Delivery (supply of goods)
2 Other service (supply of service)
3 Tip

- For owner use V=0 to 7, related to total amount.
- For Employee use V=8, Not Taxable (as of 1.1.2022, this is calculated with 5%).
4 Voucher

-For Single-Use-Voucher use V=0 to 7.
- For Multi-Use-Voucher use V=8, Not Taxable
- Voucher Sale is a positive (+) amount.
- Voucher Redeem is a negative (-) amount.
5 Catalog service
6 Not own sales / Agency business
7 Own Consumption
8 Grant

- For Unreal Grant use V=0 to 7.
- For Real Grant use V=8.
9 Receivable

- Receivable creation is negative (-) amount.
- Receivable reduction is positive (+) amount.
A Cash Transfer

- Cash Transfer to till is positive (+) amount.
- Cash Transfer from till is negative (-) amount.
- Only useable with V=8, Not Taxable.

V - VAT

You may find more information about the VAT rules and rates that applied to EU here.

Value Description
0 Unknown type of service for GR
1 Discounted-1 VAT rate
2 Discounted 2 VAT rate
3 Normal VAT rate
4 Super reduced 1 VAT rate
5 Super reduced 2 VAT rate
6 Parking VAT rate
7 Zero VAT rate
8 Not Taxable

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.

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 ✅
currencyCode Used as currency code for money numbers in ISO 4217 978 ✅
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 ❌
ftPayItemCase Parameter for Greece

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 payment item level, should be as follows.

CCCC_vlll_gggg_xxPP

Example

4752_2000_0001_0004

The 4752200000010004 is hex and should be converted to decimal number (5139205309155311620). So, the value that should be passed through in the body request.

A helpful online tool for your converting tests is this.

Flag (gggg)

Value Description
0001 IsVoid
Marks PayItem as Void previous position. Amounts and quantities are inverted. Used when the exchange of money has not yet been executed.
0002 IsReturn/IsRefund
Marks PayItem as a return of goods or services. Amounts and quantities are inverted. Used when the exchange of money has already been executed.
0004 (reserved)
0008 Downpayment
+ Amount reduces downpayment, - Amount creates downpayment.
0010 IsForeignCurrency
Amount is in EUR at the moment of acceptance. Requires foreignCurrencySymbol and foreignCurrencyAmount.
0020 IsChange
Usually contains a negative amount (-). Can be inverted when IsVoid.
0040 IsTip
Must be a negative amount (-) to flow out of payment method. ShowInChargeItems flag can visualize the tip separately.
0080 IsDigital/IsElectronic
Electronic money, digital money.
0100 IsInterface/AmountVerified
Verified by interface, automated amount transfer.
8000 ShowInChargeItems
Visualizes the item before the total amount, inverting it to be included in the receipt total.

Payment Type (PP)

Value Description
00 Unknown payment type for GR
Handled like a cash payment in national currency.
01 Cash payment
Cash
02 NonCash
Cash
03 Crossed cheque
Cash
04 Debit card payment
Cash
05 Credit card payment
Cash
06 Voucher payment (coupon) - voucher by money value
Cash
07 Online payment
Noncash
08 Loyalty program Customer card payment
09 Accounts receivable
0A SEPA transfer
0B Other Bank transfer
0C Transfer to Cashbook / Vault / Owner / Employee
+ Amount contributes to cashbox/vault, - Amount lowers the amount.
0D Internal / Material consumption
0E Grant
0F Ticket Restaurant / (Sodexo, Edenred, etc.)
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.
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

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

Understanding ftReceiptCase for Greece

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 Greece (GR), the country code is 4752. Thus, the value of an unknown ftReceiptCase in Greece is 4752000000000000.
Format

The format of the ftReceiptCase parameter on fiscalization level, should be as follows.

CCCC_vlll_gggg_txcc

Example

4752_2000_0002_0001

The 4752200000010004 is hex and should be converted to decimal number (5139205309155377153). So, the value that should be passed through in the body request.

A helpful online tool for your converting tests is this.

Flag (gggg)

Value Description
0001 Process as Late Signing Receipt
The cash register lost connection to the queue and processed receipts without communicating with the queue. All processed receipts marked with the hint “Security mechanism not reachable” need to be sent to the queue with this marker.
0002 Training Receipt
0004 IsVoid
Marks Receipt as Void to previous one. Mark line items also as IsVoid to signal clear data.
0008 Process as Handwritten Receipt
During a power outage, the Cash register will not work, and the merchant hands out handwritten receipts. These handwritten receipts need to be sent to the Security Mechanism by using this flag.
0010 IssuerIsSmallBusiness
Businesses below a country-specific size in revenue need not declare VAT.
With this marker, the receipt shows no VAT, all prices are gross, and a country-specific hint must be printed.
0020 ReceiverIsBusiness
Specific data need to be placed onto the receipt.
0040 ReceiverIsKnown
Characteristics related to VAT taxes are given. For example, Name, Address, VAT-ID, other local info.
0080 IsSaleInForeignCountry
0100 IsReturn/IsRefund
Marks Receipt as Return of good or service.
0800 Group by Position-Number / 100
100 = first position, 101 first subitem, 102 second subitem.
The sum of all charge items within a position must count toward the total receipt amount.
If the quantity and amount are 0.00, the quantity and amount will not be visualized for this line on the digital receipt, independent if main or subitem.
8000 ReceiptRequest
If you don’t receive a response, try this flag first before taking any other action.
This will return a stored result, for example, in case of a timeout when cash register calls queue.

t - Receipt Type

ValueCategoryDescription
0ReceiptA basic receipt that is generated as part of a POS sale. A receipt usually serves as proof of payment. The receipt is used after the transaction is done (if goods are received). This is the usual process that is done at a POS.
1InvoiceAn invoice is generated for those cases where payment isn't handled immediately.
2DailyOperationsThis category contains receipt cases that the Middleware requires for various downstream processes (e.g. book keeping)
3LogLogs can be used for storing / securing events that need are needed for additional processing or downstream processes. (e.g. log for cash drawer opened)
4LifecycleThese operations are used for changing the overall state of the Middleware. Depending on the local regulations these receipts are handed over as part of a notification (e.g. FinanzOnline)

txcc - ReceiptCase

Value Category
0000 Unknown type for country-code "GR"
0001 POS receipt

Represents the main kind of receipt processed by a POS system. Creates a turnover and/or a change in the amount of cash in the till or similar operations.
0002 Payment transfer receipt type
0003 Point-Of-Sale receipt without fiscalization
Obligation or with exeption on fiscalization regulation.
0004 E-Commerce receipt type
0005 Delivery Note
1000 Unknown invoice type
1001 B2C invoice type
1002 B2B invoice type
1003 B2G invoice type
2000 Zero Receipt
2001 (reserved) One Receipt
2010 Shift Closing Receipt
2011 Daily Closing Receipt
2012 Monthly Closing Receipt
2013 Yearly Closing Receipt
3000 Protocol (unspecified type)
3001 Protocol (technical event)
3002 Protocol (audit event / accounting event)
3003 Internal usage / Material consumption
3004 Order
3010 Copy Receipt / Print existing Receipt
4001 Queue-Start-Receipt (Initial operations receipt)
4002 Queue-Stop-Receipt (Out of operations receipt)
4011 Initiate SCU-switch
4012 Finish SCU-switch

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.

    "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

ewogICAgImNiQ2hhcmdlSXRlbXMiOiBbCiAgICAgICAgewogICAgICAgICAgICAiYW1vdW50IjogMSwKICAgICAgICAgICAgImRlc2NyaXB0aW9uIjogImRlc2NyaXB0aW9uIDEiLAogICAgICAgICAgICAicG9zaXRpb24iOiAxLAogICAgICAgICAgICAicXVhbnRpdHkiOiAxMDAsCiAgICAgICAgICAgICJ1bml0IjogInBjcyIsCiAgICAgICAgICAgICJ1bml0UHJpY2UiOiAxLAogICAgICAgICAgICAidmF0QW1vdW50IjogMSwKICAgICAgICAgICAgInZhdFJhdGUiOiAyNCwKICAgICAgICAgICAgImN1cnJlbmN5Q29kZSI6ICI5NzgiLAogICAgICAgICAgICAibW9tZW50IjogIjIwMjUtMDQtMjJUMTM6NTM6MzIuMjA1WiIsCiAgICAgICAgICAgICJmdENoYXJnZUl0ZW1DYXNlRGF0YSI6IHsKICAgICAgICAgICAgICAgICJ0YXhhYmxlIjogdHJ1ZQogICAgICAgICAgICB9LAogICAgICAgICAgICAiZnRDaGFyZ2VJdGVtQ2FzZSI6IDUxMzkyMDUzMDkxNTUyNDYwODMKICAgICAgICB9CiAgICBdLAogICAgImNiUGF5SXRlbXMiOiBbCiAgICAgICAgewogICAgICAgICAgICAiYW1vdW50IjogMSwKICAgICAgICAgICAgImRlc2NyaXB0aW9uIjogIkNhcmQiLAogICAgICAgICAgICAicG9zaXRpb24iOiAxLAogICAgICAgICAgICAiY3VycmVuY3lDb2RlIjogIjk3OCIsCiAgICAgICAgICAgICJtb21lbnQiOiAiMjAyNS0wNC0yMlQxMzo1MzozMi4yMDVaIiwKICAgICAgICAgICAgImZ0UGF5SXRlbUNhc2UiOiA1MTM5MjA1MzA5MTU1MjQ2MDg1CiAgICAgICAgfQogICAgXSwKICAgICJjYlVzZXIiOiB7CiAgICAgICAgIm1lcmNoYW50TmFtZSI6ICJNZXJjaGFudCIsCiAgICAgICAgImNhc2hpZXIiOiB7CiAgICAgICAgICAgICJuYW1lIjogIkpvaG4gRG9lIiwKICAgICAgICAgICAgImlkIjogMTAKICAgICAgICB9CiAgICB9LAogICAgImNiUmVjZWlwdE1vbWVudCI6ICIyMDI1LTA0LTIyVDEzOjUzOjMyLjIwNVoiLAogICAgImNiUmVjZWlwdFJlZmVyZW5jZSI6ICJVbmlxdWUgcmVmZXJlbmNlIG9mIHRoZSByZWNlaXB0IiwKICAgICJmdFJlY2VpcHRDYXNlIjogNTEzOTIwNTMwOTE1NTI0NjA4NSwKICAgICJjdXJyZW5jeUNvZGUiOiAiOTc4Igp9

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


Field Description Example
ftState The country-specific code is made of the country’s code value following the ISO-3166-1-ALPHA-2 standard, converted from ASCII into hex. For Greece (GR) this is 0x4752, which results in 4752_2000_0000_0000 as the value for the “ready” status.

The table below describes it supported statuses for the ftState field following the Greek implementation. The ftState from this reference table and the general part of this documentation can be combined through the logic operator “OR”. For example 4752_2000_0000_0010 (monthly report due) and 4752_2000_0000_0008 combined through OR results in 4752_2000_0000_0018. For more details please see this section.		 5139205309155246080
ftReceiptIdentification The number of the receipt, which was assigned by the Viva Fiscalisation ft5#0-5
ftCashBoxIdentification Cash register identification number. fiskaltrust1
transmissionIndicator Reflects the status of the fiscal data’s transmission to the tax authority or fiscal system. For more detail please see this section. 0
ftSignatures The cryptographic signatures applied to the transaction data. For more detail please see this section. array of objects

ftState

Format

The format of the ftState parameter on fiscalization level, should be as follows.

CCCC_vlll_gggg_gggg

Example

4752_2000_0000_000

ftState Global tagging/flag values(gggg_gggg)
Value Description
0000_0000 Ready status.
0000_0001 Security Mechanism is out Out of Operation
Queue is not started or already stopped.
0000_0002 SCU (Signature Creation Unit) temporary out of service
For at least one receipt, it was not possible to receive the signature from an allocated SCU, therefore the security mechanism has been put into "signature creation device out of service" mode. Regardless of whether an allocated SCU is available again or not, the mode remains in place until a ZeroReceipt cleans up the state and takes the market specific action required.
0000_0008 Deferred Queue Mode / Late Signing Mode is active
When the cash register doesn’t reach the queue, it queues up the receipt requests while continuing to do business. Also, with a major failure of the cash register or a power outage, handwritten paper receipts are queued up while continuing to do business. After getting back to a full functional state, these queued-up ReceiptRequests are sent to the queue, having the original cbReceiptMoment of the business case and ReceiptCase tagged/flagged with 0001 (Deferred Queue / Late Signing) or 0008 (Handwritten).
A result of this is a marker within the ftState, which can be resolved via ZeroReceipt. The reason for the marker is a mismatch between processed time along the receipt chain and a manual event to clean up the state and maybe notify 3rd parties of an outage.
0000_0040 Message Pending
Middleware/Queue is a headless background service, but there are situations where communication with the cashier/operator or the cash register is necessary. For example, if the last daily closing was missed or if a special condition related to the signature creation unit or service happened. This is the moment when the message pending flag is set by the middleware, which should be signalled to the cashier by the POS system. By executing a ZeroReceipt, the cashier can read the message or instruction on the printed or displayed receipt.
Related to local regulations, this receipt may be stored/archived with/for bookkeeping purposes; if this is the case, this is also visualized.
0000_0100 DailyClosing due
When the first cbReceiptMoment used since the last DailyClosing and the current/latest cbReceiptMoment in the ReceiptRequest have a date-gap of more than two days (for example, the first since the last daily closing is 24/08 and the current is 26/08), then this state indicates, a Daily Closing should be done.
DailyClosing is an essential part of the security mechanism and also executes additional market-specific cleanup tasks. Therefore, each queue should do a DailyClsoing to clear persistent changes in business data and also changes in the business period.
EEEE_EEEE Error
Something went wrong while processing the last request. QueueItem exists but didn’t reach the state of a ReceiptItem and didn’t consume a ftReceiptNumber within the chain. Error reason is shown within the responded ftSignatureItems.
This happens, for example, if the ReceiptCase is not recognized or is wrong.
FFFF_FFFF Fail
Something went wrong while processing the last request, and nothing persisted within the Queue. Fail reason is shown within the responded ftSignatureItems.
This happens, for example, when the flag ReceiptRequest is used after a communication outage, and no properly processed item is found.

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.

Parameter Value Description
transmissionIndicator 0 Succesfully fiscalised transaction. Please use the signature object and create your receipt/invoice accordingly.
transmissionIndicator 1 TRANSMISSION_FAILURE_1: Please mark the transaction as TRANSMISSION_FAILURE_1 and print "TRANSMISSION_FAILURE_1" on the sale receipt/invoice
transmissionIndicator 2 or it is either missing or not present in the response. TRANSMISSION_FAILURE_2: AADE myDATA is unreachable. Please mark the transaction as TRANSMISSION_FAILURE_2 and print "TRANSMISSION_FAILURE_2" on the sale receipt/invoice

Please see the below table for more detailed scenarios.

Scenario Local network connection disruption Viva Terminal app/device unresponsive Internet connection disruption Viva.com cloud infrastructure unreachable AADE myDATA cloud infrastructure unreachable
Payment + Fiscalisation integration APIs Reachable Unreachable Reachable Reachable Reachable
Fiscalisation outcome Fiscalisation temporarily unavailable.
TRANSMISSION_FAILURE_1

Viva informs POS via API response that fiscalisation cannot proceed due to a TRANSMISSION_FAILURE_1 error.
According to myDATA reporting regulations, POS should mark the sale as TRANSMISSION_FAILURE_1 and print this message on the sales receipt/invoice. No follow-up receipt/invoice needs to be generated.
Simultaneously, Viva polls continuously the Viva infrastructure endpoint and when the connection is restored, it automatically transmits the contents of the receipt/invoice, marked with TRANSMISSION_FAILURE_1 designator to AADE myDATA.
Lastly, the fiscalised response is also returned to the POS for safekeeping.
Fiscalisation outcome (Alternate scenario) Fiscalisation temporarily unavailable.
TRANSMISSION_FAILURE_2

Viva informs POS via API response that fiscalisation cannot proceed due to a TRANSMISSION_FAILURE_2 error.
According to myDATA reporting regulations, POS should mark the sale as TRANSMISSION_FAILURE_2 and print this message on the sales receipt/invoice. No follow-up receipt/invoice needs to be generated.
Simultaneously, Viva polls continuously the AADE myDATA infrastructure endpoint and when the connection is restored, it automatically transmits the contents of the receipt/invoice, marked with TRANSMISSION_FAILURE_2 designator to AADE myDATA.
Lastly, the fiscalised response is also returned to the POS for safekeeping.
Electronic payment outcome Electronic payments possible (offline mode) Electronic payments not possible Electronic payments possible (offline mode) Electronic payments possible (offline mode) Electronic payments possible (online mode)

ftSignatures

These are cryptographic signatures applied to the transaction data. They serve as proof of authenticity and integrity showing that the fiscalized data has not been tampered with. Signatures include a unique hash or token generated based on the transaction’s content and a secure private key, aligning with the digital security requirements set by fiscal authorities.

Parameter Value Description
ftSignatures.caption Example values
-invoiceUid
-invoiceMark
-authenticationCode
-[www.viva.com]
-Σημείωση: Με βάση την ΠΟΛ.1002/2014 (ΦΕΚ Β’ 3/2-1-2014), τα δεδομένα αυτά δεν επιδέχονται αλλοίωση. 		The caption that needs to be printed above the signature data
ftSignatures.data Sample values
-322C0863893A5EB62F4865D26129075BBDF46BD3
-https://receipts-sandbox.viva.com/8c0a4594
-112545020|27/03/2025|0|Item113|0|128		 The signature data that needs to be printed under the relevant caption according to the mentioned format.
ftSignatures.ftSignatureFormat 0: Unknown / no format defined
1: Text
2: Link
3: QR-Code (2D Code)
4: Code128 (Barcode)
5: OCR-A (optical character recognition, possible for Base32 data)
6: PDF417-(2D Code)
7: DATAMATRIX-(2D Code)
8: AZTEC-(2D Code)
9: EAN-8 (Barcode)
A: EAN-13 (bar code)
B: UPC-A (bar code)
C: Code39 (bar code, Base32 compatible)
 Specifies the format that you need to use when printing the signature data. For example, if format is 3, the data value should be presented as QR code.
ftSignatures.ftSignatureType Sample values
-4154000000000000:
-
-112545020|27/03/2025|0|Item113|0|128		 The descimal corresponding of signature data that needs to be printed under the relevant caption according to the mentioned format. The ftSignatureType indicates the type and origin of the signature. The data type is Int64 and can contain a country-specific code, a value following the ISO-3166-1-ALPHA-2 standard, converted from ASCII into hex and used as byte 8 and 7. For more details please see the next section

ftSignatureType
Format

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

CCCC_vlll_gggg_tsss

Example

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

t - Type/Category

Value Description
0 Uncategorized, Normal use (notification)
1 Information (notification), low priority
2 Alert (notification), high priority
3 Failure (notification), high priority

sss - SignatureCase

Value Description Caption
TBD TBD TBD

gggg - Global Flags

Value Description
0001 Archiving required.
Signatures marked with this flag are known to be archived related to market specific bookkeeping requirements. In case of offline usage or pure open-source usage, receipts/artefacts having this flag need to be handled as bookkeeping/accounting-relevant item.
0010 Printing/Visualization is optional
0020 Do not print/visualize
0040 Printed receipt only
0080 Digital receipt only

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!