Greece — FAQ: Invoices & Cloud Terminal API

1) How can I issue a Sales Invoice (1.1) that is simultaneously a Delivery Note?

You can find it 1.1 here

2) In the Referenced Credit Note (5.1) I cannot understand from the sample file how to declare the MARK that I am referencing.

Every fiscal document created through Viva Fiscalisation receives a unique reference — the value you set in cbReceiptReference.

To create a Referenced Credit Note (5.1), you do not declare a MARK or any AADE-specific field. Instead, you simply point to the original document’s cbReceiptReference.

Example:

The original document (e.g., a Sales Invoice) has:

{
  "cbReceiptReference": "XYZ-123"
}

In the Credit Note (5.1) that references it, you include:

{
  "cbPreviousReceiptReference": "XYZ-123"
}

That’s all that is needed to correctly link the two documents.

3) ISV API — what role does it play in the payments flow?

The ISV API is strictly used for onboarding new merchants and is not related to payments. In the payment use-case we use the ISV credentials to call the Cloud Terminal REST API.

ISV Sale Request:
See the endpoint here.

Unreferenced Refund:
See the endpoint here.

The Sale Request accepts ISV credentials — inside ISVDetails you place the merchantID of the merchant under you in the field terminalMerchantID. The unreferenced refund does not accept ISV details for now, so the call is performed using the merchant’s credentials.

4) Cloud Terminal API & fiscalisationData

In the Cloud Terminal API we separate:

• payment details (amount, currency, card, etc.), and
• fiscal details (document type, line items, VAT ID, hash, etc.).

Everything related to taxation / documents / myDATA must be placed exclusively inside the fiscalisationData object.

Indicatively, inside fiscalisationData you will find:

• cbChargeItems – amounts, VAT, descriptions
• cbPayItems – payment methods (Card, Cash, etc.)
  
• cbReceiptAmount, cbReceiptMoment, cbReceiptReference – total, datetime, reference
  
• ftReceiptCase, ftChargeItemCase, ftPayItemCase – decimal Int64
• ftReceiptCaseData.GR – AADE data (Merchant VAT ID, Series, AA, HashPayload, etc.)

If fiscalisationData, is missing or incorrect, the payment might succeed on the acquiring layer, but fiscalisation will fail.

5) Cloud Terminal — call flow(Search Devices, Actions, Sales Requests κ.λπ.)

Flow overview::
here

Step-by-step documentation::
here

6) Cash without POS usage — how is fiscalisation performed?

Exactly the same way as with card: in cbPayItems we use ftPayItemCase for cash, and the request still goes through the terminal (as middleware, without user interaction).

{
  "cbPayItems": [
    {
      "amount": 2300,
      "description": "cash",
      "position": 1,
      "currencyCode": "978",
      "moment": "2025-07-17T08:11:06Z",
      "ftPayItemCase": 5139205309155246081
    }
  ],
  "fiscalisationData": {
    "GR": {
      "MerchantVATID": "098000979",
      "Series": "A",
      "AA": 397717,
      "HashAlg": "sha256",
      "HashPayload": "098000979-A-397717-receiptreference1-2025-07-17T08:11:06Z-23.0"
    }
  }
}

7) Where do I find the “cashRegisterId” for a specific merchant?

This is not something the Viva provides. It is your own identifier for the cash register / ePOS / ERP, and you can put whatever you want as long as it makes sense in your system.

• Typically it is a cash register ID (π.χ. POS-01, STORE12-REG3).

8) What is the interappCallback field?

This interface is for all-in-one devices where the ePOS/ECR/ERP app runs on the same Android (and soon iOS) device as the Viva Terminal app. The interappCallback tells the Viva app where to return after the payment and/or fiscalisation completes.

9) Is there a list of supported values for the unit field inside cbChargeItems?

We do not enforce strict validation on this field – it is essentially free text (“unit of measure”).

10) About isvDetails

In the basic scenario, you only care about terminalMerchantId:

terminalMerchantId → the merchant ID of the merchant under you (the ISV).

merchantId, merchantSourceCode → used only in multi-merchant scenarios.

Multi-merchant functionality means the same terminal can switch between different merchants and accept payments on behalf of third parties (e.g., a ticketing agency collecting for many companies).

11) In the sourceCode field, do I need to put the sourceCode defined in my ISV? Or is it optional?

It belongs to the merchant’s account and is not mandatory — only needed if the merchant has multiple wallets (sub-accounts) or wants to tag transactions with different groupings, where the source changes per transaction. But in most cases, the source is assigned to different locations, and usually each location has its own terminal.

12) How do I issue receipts for Order Slip (8.6) — separate or aggregated?

For order-slip type orders (8.6) there are two flows:

1) Immediate fiscal receipt per order (without 8.6)
When the customer pays at the moment of ordering (cash or card), you may issue a direct fiscal receipt, without creating an 8.6.

2) Issuing 8.6 per order & final document(s) at the end
For each order you issue an 8.6, and at the end: - you issue one or more final documents, - with line items from the original 8.6 entries, - and a reference to the respective 8.6. Payments can be made using one or multiple cards/cash.

Are separate receipts allowed for each individual? Yes. You can issue multiple final documents referencing the same 8.6, as long as the total amounts fully match the original order slips.

Example

• 3 beers → 1× 8.6,
• 1 salad → 1× 8.6,
• Customers want separate bills.

By law:

• you issue 3 final documents for the beers (1 per person),
• and 1 final document for the salad, even if it is paid with 3 different cards.

To “split” the salad between 3 people, you send 3 line items each with amount / 3, because you cannot split one line item unless you represent it as multiple lines.

13) In documents 11.1 / 11.2, do I always receive Series and AA from the Viva API and my own values are ignored? And must each document type (e.g., 11.1 and 11.2) have a different Series, or is it enough that AA is unique within one Series?

No, it is not mandatory to always receive Series and AA from the Viva API – you may override them with your own values via ftReceiptCaseData. More details: here

Regarding Series:

AA must be unique within a specific Series.

The same Series can be reused for different document types (e.g., 11.1 and 11.2 do not need to have different Series).

14) In case of TRANSMISSION_FAILURE_1 or TRANSMISSION_FAILURE_2 during fiscalisation, will any of the above webhook events (especially the 1802 one) be triggered, or will no event be sent?

We do not send anything to webhooks at this moment, but it is coming soon.

15) Which endpoint and credentials should be used for performing a return/refund with fiscalisation?

Fiscal returns/refunds and refunds of their associated payments are supported through the Unreferenced refunds

Endpoint_Could

Endpoint_Local

Please note that unreferenced refunds are not supported through the ISV flow, therefore they must be executed using the merchant’s credentials. The Bearer token must be generated with the merchant’s client credentials, and the payload must not include any isvDetails object.

At this time, there is no alternative endpoint that supports fiscalisation of a return/refund with optional electronic payment refunds via the ISV credentials

16) Why is a cash return shown as a negative Cash pay item, while card returns use a “refund” flow (11.4 vs 5.¹⁄₅.2)?

This is expected behavior.

• In 11.4, the return is associated with an electronic payment refund (card refund), so the “refund” concept exists as part of the payment method flow.

• In 5.1 / 5.2, the return is represented as cash. With cash, there is no “refund transaction type” in the same sense as card payments, because cash is not electronically reversed.
  So the system represents the money being returned by using:

  • Cash as the payment type, and
  • a negative sign on the amount.

In short: Card returns = refund flow, Cash returns = negative cash amount (cash out).

17) Can I send a SALE with amount = 0 when I only want fiscalisation (0-value data)?

No. For the SALE request, the top-level amount must be greater than zero. If you send amount: 0, the request is rejected with: “Wrong request parameters: Amount value must be greater than zero”.

Important notes:
Even if you intend to send cbReceiptAmount = 0 (and line items with amount = 0) for fiscal data, the SALE endpoint still requires a positive payment amount.
For a valid SALE request, you should keep amounts consisten

- amount (top-level) > 0
- cbReceiptAmount = sum of cbChargeItems[].amount (and should match the paid amount)