Greece — FAQ: Invoices & Cloud Terminal API

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

Delivery Note support is not available at the moment, but is coming soon.

You can find 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.

In document A, we assign a unique cbReceiptReference string, e.g. "XYZ".

In the credit note that references it, we set the same reference inside cbPreviousReceiptReference, for example:

{
  "cbPreviousReceiptReference": "XYZ"
}

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