Spain

Fiscalisation for Spain

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 fiscalization data. The fiscalization data object comprises three main components.

  1. Fiscalisation Data Parameters: Contains the core details required for tax compliance.

  2. LineItems Array: An array of objects, each representing an individual item sold, including details such as description, quantity, price, and VAT.

  3. Payment Array: An array of objects specifying the payment details, including payment method, amount, and references.

The fiscalisationData object consists of the below parts:

Fiscalisation Data Parameters

The fiscalisationData object contains the below parameters.

Value
Description
Example
Max Length
Required
processingIndicator
You can find all possible values of the Receipt Processing Indicator under each country’s Receipt Processing Indicator section
5139205309155246081
50 characters
customerVatNumber
The Vat Number to which the invoice is linked to
EL036098541
50 characters

Required only if the receipt is about B2B services/items
customerName
The customer’s name
Professional Services LTD
50 characters

Required only if the receipt is about B2B services/items
customerCountryCode
The country code of where the Vat Number is registered to.
GR
50 characters

Required only if the receipt is about B2B services/items
customerStreet
The customer’s street.
Amarousiou Chalandriou 18-20
50 characters

Required only if the receipt is about B2B services/items
customerCity
The customer’s city
Athens
50 characters

Required only if the receipt is about B2B services/items
customerZip
The customer’s zip code
15125
50 characters

Required only if the receipt is about B2B services/items
receiptDateTime
The receipt’s date & time
2025-02-03T09:32:41.604Z
The value of this constant is equivalent to 23:59:59.9999999 UTC, December 31, 9999 in the Gregorian calendar
receiptUniqueReference
A reference identification key for this specific receipt
fiscal-12345678
100 characters
lineItems
Array of Objects. Please see the next sections for more details.
payments
Array of Objects. Please see the next sections for more details.
Example

The order includes two products, one Coffee Latte and two Coffee Cappuccino, with grand total amount of 20 euro (1 item Coffee Latte x 10 euro + 2 Coffees Cappuccino x 5 euro). The payments array, will be the below:

{
   "processingIndicator":"5139205309155246081",
   "customerVatNumber":"EL036098541",
   "customerName":"Professional Services LTD",
   "customerCountryCode":"GR",
   "customerStreet":"Amarousiou Chalandriou 18-20",
   "customerCity":"Athens",
   "customerZip":"15125",
   "receiptDateTime":"2025-02-03T09:32:41.604Z",
   "receiptUniqueReference":"fiscal-12345678",
   "lineItems": [{...}],  //array of objects
   "payments": [{...}]   //array of objects
}

LineItems Array

Inside the fiscalisationData object, the LineItems array holds the product/item details that the invoice includes.

Value
Description
Example
Max Length
Required
amount
The amount with VAT of each item/product
1000 = 10 euro
4 integers where tha last two linked with the decimals
description
The description of the item/product
Coffee Latte
100 characters
position
The position on the receipt
1
An integer
productBarcode
The product barcode content passed through from the cashier system
1234567890123
50 characters
productNumber
The product number passed through from the cashier system
15709
50 characters
quantity
The quantity of this specific product item
2
An integer
vatAmount
The VAT amount that applied to this specific product
240
100 characters
vatRate
The VAT rate that applied to this specific product
2400 (as value, not 24% in percentange)
4 characters
processingIndicator
You can find all possible values of the LineItem Processing Indicator under each country’s LineItem Processing Indicator section
5139205309125846083
50 characters
Example

The order includes two products, one Coffee Latte and two Coffee Cappuccino, with grand total amount of 20 euro (1 item Coffee Latte x 10 euro + 2 Coffees Cappuccino x 5 euro). The line item array, will be the below:

"lineItems":[
      {
         "amount":1000,
         "description":"Coffee Latte",
         "position":1,
         "productBarcode":"1234567890123",
         "productNumber":15709,
         "quantity":1,
         "vatAmount":240,
         "vatRate":2400,
         "processingIndicator":"5139205309155246083"
      },
      {
         "amount":500,
         "description":"Coffee Cappuccino",
         "position":2,
         "productBarcode":"1234567890200",
         "productNumber":15710,
         "quantity":2,
         "vatAmount":120,
         "vatRate":2400,
         "processingIndicator":"5139205309125846083"
      }
   ]

Payments Array

Inside the fiscalisationData object, the payments array holds the payment details for the items in the order.

Value
Description
Example
Max Length
Required
amount
The grand total amount of the payment
2000 = 20 euro
4 integers where tha last two linked with the decimals
dateTime
The payment’s date and time
2025-02-03T09:32:41.604Z
The value of this constant is equivalent to 23:59:59.9999999 UTC, December 31, 9999 in the Gregorian calendar
description
A short description for this receipt
Order XXXX, Cashier 1, Central Store
50 characters
position
The position on the receipt for details
1
An integer
processingIndicator
You can find all possible values of the Payments Processing Indicator under each country’s Payments Processing Indicator section
5139205309155246083
50 characters
Example

The order includes two products, one Coffee Latte and two Coffee Cappuccino, with grand total amount of 20 euro (1 item Coffee Latte x 10 euro + 2 Coffees Cappuccino x 5 euro). The payments array, will be the below:

"payments":[
  {
      "amount":2000,
      "dateTime":"2025-02-03T09:32:41.604Z",
      "description":"Payment via card",
      "position":1,
      "processingIndicator":"5139205309155246083"
  }
]

Understanding processingIndicators for Spain

As you might have already noticed, the FiscalisationData object contains a parameter called processingIndicator. This parameter exists in the main object, inside lineItems object, and payments object.

Receipt processingIndicator: The ProcessingIndicator 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.

LineItems processingIndicator: The ProcessingIndicator in the ‘lineItems’ 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.

Payments processingIndicator: The ProcessingIndicator in the ‘payments’ 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.

Receipt ProcessingIndicator for Spain

For Spain (ES), the country code is 4553. Thus, the value of an unknown processing indicator in Germany is 4553000000000000.

Example for POS receipt processing indicator: 4553000000000001

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

CCCC_vlll_gggg_txcc

Example

4553_2000_0001_0004

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

t - Receipt Type

Value Category Description
0 Receipt A 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.
1 Invoice An invoice is generated for those cases where payment isn’t handled immediately.
2 DailyOperations This category contains receipt cases that the Middleware requires for various downstream processes (e.g. book keeping)
3 Log Logs can be used for storing / securing events that need are needed for additional processing or downstream processes. (e.g. log for cash drawer opened)
4 Lifecycle These 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 Description
0000 Unknown type for country-code “ES”

This receipt case is handled like a “pos-receipt” ( 0001 ). See below:
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.

Use the ftChargeItems and ftPayItems to hand over details about goods, services and payments for processing. The ftChargeItems and ftPayItems should contain the full final state of the receipt.
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

Used for communication test and functional test of the Viva fiscalisation. The request is only valid when the charge items block (ftChargeItems) and the pay items block (ftPayItems) in the ftReceiptRequest are empty arrays.
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

Flag (gggg)

Value Description Middleware version
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 maker.
0002 Training Receipt
0004 IsVoid

Marks Receipt as Void to previous one. Mark lineitems 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, Adress, 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 chargeitems 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 our 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 cashregister calls queue.

LineItems ProcessingIndicator for Spain

Format

The format of the processingIndicator parameter on line item level, should be the below.

CCCC_vlll_gggg_NNSV

Example

4553_2000_0000_0013

In this example, the generated number 4553200000000013 for LuneItem processing indicator is hex and should be converted to decimal number (4995371596056100883). So the value that should be passed through in the body request is 4995371596056100883.

A helpful online tool for your converting tests is this.

V - VAT

Value Description
0 Unknown type of service for ES
With the help of the VAT-rates table saved within Viva fiscalisation.
1 Discounted-1 VAT rate
(as of 1.1.2022, this is 10%).
2 Discounted 2 VAT rate
(as of 1.1.2022, this is calculated with 5%).
3 Normal VAT rate
(as of 1.1.2022, this is calculated with 22%).
4 Super reduced 1 VAT rate
5 Super reduced 2 VAT rate
6 Parking VAT rate
Reversal of tax liability.
7 Zero VAT rate
In the data, a VAT-rate can be indicated.
8 Not Taxable
For processing, see ( 4553000000000001)

S - Type of Service

Value Description
0 Unknown type of service
With the help of the VAT-rates table saved within Viva fiscalisation.
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.
IsVoid can be applied to reverse amounts.
Avoid to use this for Multi-Use-Voucher, use PayItem instead, with ShowInChargeItems flag. For Single-Use-Voucher, apply the ShowInPayItems flag to visualize it similar to payment and to keep the total amount unreduced.
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
Receiveable creation is negative (-) amount
Receiveable reduction is positive (+) amount.
IsVoid can be applied to reverse amounts.
Avoid to use this, use PayItem instead.
A Cash Transfer
Cash Transfer to till is positive (+) amount
Cash Transfer from till is negative (-) amount.
Only useable with V=8, Not Taxable.
IsVoid can be applied to reverse amounts

NN - Nature of VAT

Value Description Spec. for Spanish reg.
00 usual VAT applies
20 Not Subject
2x can be used to specify more country specific details.
*NS (N2) marker mandatory
[20] not subject by aticles 7 and 14
[21] not subject, location rules
30 Exempt
3x
*ES (N4) marker mandatory
[30] Exempt by article 20
[31] Exempt by article 21
[32] Exempt by article 22
[33] Exempt by article 23 and 24
[34] Exempt by article 25
[35] Exempt, other cases
50 Reverse charge
5x
*AL (N6) marker mandatory
[50] reverse charge

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
IsVoid or IsReturn/IsRefund will invert this behavior.
0008 Downpayment
Marks ChargeItem as a downpayment.
Positive (+) amount is the creation of downpayment.
Negative (-) amount is reduction of downpayment.
IsVoid or IsReturn/IsRefund will invert this behavior.
0010 Returnable
Marks ChargeItem as a returnable.
Positive (+) amount/quantity is handout.
Negative (-) amount/quantity is reverse.
IsVoid or IsReturn/IsRefund will invert this behavior.
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 the amount into the visualized total amount on the receipt.

Payments ProcessingIndicator for Spain

Format

The format of the processingIndicator parameter on payment item level, should be the below.

CCCC_vlll_gggg_xxPP

Example

4553_2000_0001_0004

In this example, the generated number 4553200000000004 for payment processing indicator is hex and should be converted to decimal number (4995371596056100868). So the value that should be passed through in the body request is 4995371596056100868.

A helpful online tool for your converting tests is this.

Payment Type (PP)

Value Description
00 Unknown payment type for ES
This is 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
Positive (+) amount contributes to cashbox/vault. This higher the amount in cashbox/vault.
Negative (-) amount lowers the amount in cashbox/vault.
0D Internal / Material consumption
0E Grant
0F Ticket Restaurant / (Sodexo, edenred, usw.)

Flag (gggg)

Value Description
0001 IsVoid
Marks PayItem as Void previous position. Quantity and amount are inverted, related to original item.
IsVoid is used in cases where the exchange of money has not been executed yet.
0002 IsReturn/IsRefund
Marks PayItem as Return of good or service. Quantity and amount are inverted, related to original item.
IsReturn/IsRefund is used in cases where the exchange of money has been executed already.
0004 (reserved)
0008 Downpayment
Marks PayItem as a downpayment.
Positive (+) amount is reduction of downpayment.
Negative (-) amount is creation of downpayment.
0010 IsForeignCurrency
Amount is still in EUR, at the moment of acceptance. ftPayItemData requires two data elements with “foreignCurrencySymbol” and “foreignCurrencyAmount” to persist data for daily closing and later bookkeeping transactions
0020 IsChange
Usually contains a negative (-) amount.
(IsVoid => can be inverted)
0040 IsTip
Must be a negative (-) amount to flow out of payment method.
ShowInChargeItems flag can be used to raise the total amount by the tip amount, to have a more convenient visualization.
0080 IsDigital/IsElectronic
Electronic money, digital money
0100 IsInterface/AmountVerified
Was verified by interface, automated amount transfer
8000 ShowInChargeItems
Visualize the item before Total Amount. This inverts amount and does include the amount into the visualized total amount on the receipt.

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":{
   "lineItems":[
      {
         "amount":1000,
         "description":"Coffee Latte",
         "position":1,
         "productBarcode":"1234567890123",
         "productNumber":15709,
         "quantity":1,
         "vatAmount":240,
         "vatRate":2400,
         "processingIndicator":"5139205309155246083"
      },
      {
         "amount":500,
         "description":"Coffee Cappuccino",
         "position":2,
         "productBarcode":"1234567890200",
         "productNumber":15710,
         "quantity":2,
         "vatAmount":120,
         "vatRate":2400,
         "processingIndicator":"5139205309125846083"
      }
   ],
   "payments":[
      {
         "amount":2000,
         "dateTime":"2025-02-03T09:32:41.604Z",
         "description":"Payment via card",
         "position":1,
         "processingIndicator":"5139205309155246083"
      }
   ],
   "processingIndicator":"5139205309155246081",
   "customerVatNumber":"EL036098541",
   "customerName":"Professional Services LTD",
   "customerCountryCode":"GR",
   "customerStreet":"Amarousiou Chalandriou 18-20",
   "customerCity":"Athens",
   "customerZip":"15125",
   "receiptDateTime":"2025-02-03T09:32:41.604Z",
   "receiptUniqueReference":"fiscal-12345678"
}

fiscalisationData for Interapp(app2app) Integration

For Interapp(app2app) integration, you should encode fiscalisationData JSON object as base64 format and pass it as uri parameter

ewogICAibGluZUl0ZW1zIjpbCiAgICAgIHsKICAgICAgICAgImFtb3VudCI6MTAwMCwKICAgICAgICAgImRlc2NyaXB0aW9uIjoiQ29mZmVlIExhdHRlIiwKICAgICAgICAgInBvc2l0aW9uIjoxLAogICAgICAgICAicHJvZHVjdEJhcmNvZGUiOiIxMjM0NTY3ODkwMTIzIiwKICAgICAgICA
gInByb2R1Y3ROdW1iZXIiOjE1NzA5LAogICAgICAgICAicXVhbnRpdHkiOjEsCiAgICAgICAgICJ2YXRBbW91bnQiOjI0MCwKICAgICAgICAgInZhdFJhdGUiOjI0MDAsCiAgICAgICAgICJwcm9jZXNzaW5nSW5kaWNhdG9yIjoiNTEzOTIwNTMwOTE1NTI0NjA4MyIKICAgICAgfSwKICAgIC
AgewogICAgICAgICAiYW1vdW50Ijo1MDAsCiAgICAgICAgICJkZXNjcmlwdGlvbiI6IkNvZmZlZSBDYXBwdWNjaW5vIiwKICAgICAgICAgInBvc2l0aW9uIjoyLAogICAgICAgICAicHJvZHVjdEJhcmNvZGUiOiIxMjM0NTY3ODkwMjAwIiwKICAgICAgICAgInByb2R1Y3ROdW1iZXIiOjE1N
zEwLAogICAgICAgICAicXVhbnRpdHkiOjIsCiAgICAgICAgICJ2YXRBbW91bnQiOjEyMCwKICAgICAgICAgInZhdFJhdGUiOjI0MDAsCiAgICAgICAgICJwcm9jZXNzaW5nSW5kaWNhdG9yIjoiNTEzOTIwNTMwOTEyNTg0NjA4MyIKICAgICAgfQogICBdLAogICAicGF5bWVudHMiOlsKICAg
ICAgewogICAgICAgICAiYW1vdW50IjoyMDAwLAogICAgICAgICAiZGF0ZVRpbWUiOiIyMDI1LTAyLTAzVDA5OjMyOjQxLjYwNFoiLAogICAgICAgICAiZGVzY3JpcHRpb24iOiJQYXltZW50IHZpYSBjYXJkIiwKICAgICAgICAgInBvc2l0aW9uIjoxLAogICAgICAgICAicHJvY2Vzc2luZ0l
uZGljYXRvciI6IjUxMzkyMDUzMDkxNTUyNDYwODMiCiAgICAgIH0KICAgXSwKICAgInByb2Nlc3NpbmdJbmRpY2F0b3IiOiI1MTM5MjA1MzA5MTU1MjQ2MDgxIiwKICAgImN1c3RvbWVyVmF0TnVtYmVyIjoiRUwwMzYwOTg1NDEiLAogICAiY3VzdG9tZXJOYW1lIjoiUHJvZmVzc2lvbmFsIF
NlcnZpY2VzIExURCIsCiAgICJjdXN0b21lckNvdW50cnlDb2RlIjoiR1IiLAogICAiY3VzdG9tZXJTdHJlZXQiOiJBbWFyb3VzaW91IENoYWxhbmRyaW91IDE4LTIwIiwKICAgImN1c3RvbWVyQ2l0eSI6IkF0aGVucyIsCiAgICJjdXN0b21lclppcCI6IjE1MTI1IiwKICAgInJlY2VpcHREY
XRlVGltZSI6IjIwMjUtMDItMDNUMDk6MzI6NDEuNjA0WiIsCiAgICJyZWNlaXB0VW5pcXVlUmVmZXJlbmNlIjoiZmlzY2FsLTEyMzQ1Njc4Igp9

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!