Hungary Fiscalization Guide

What is Hungarian fiscalization?

Hungary requires real-time invoice data reporting to NAV (Nemzeti Adó- és Vámhivatal — the National Tax and Customs Administration) under the Online Számla (Online Invoice) regime. Every invoice issued by a Hungarian VAT subject — domestic B2B, cross-border, and B2C — must be transmitted to NAV in XML form within five minutes of issuance.

In plain English: Hungary doesn't certify your software or your hardware — it just wants to see every invoice as soon as you issue it. NAV decides asynchronously whether the invoice is acceptable; you keep selling in the meantime.

You don't need to worry about this

Zyntem handles the XML schema, the AES key exchange, the SHA-512 request signature, and the asynchronous status polling. From your perspective, you just create transactions — they complete in ~10ms with a fiscal ID and the receipt is ready to print before NAV has even seen the data.

How it works

Hungary's flow is asynchronous and cloud-based — there's no local signing or hardware:

1. Your POS creates a transaction via POST /v1/transactions.
2. Zyntem assembles the InvoiceData XML in NAV's namespace, base64-encodes it, signs the request with SHA-512, and queues it for submission.
3. The transaction returns immediately with a fiscal_id (NAV transactionId + your invoice number).
4. In the background, Zyntem exchanges the technical user's password hash + signature key for a 5-minute token (/tokenExchange), then submits up to 100 invoices per call to /manageInvoice.
5. Zyntem polls /queryTransactionStatus until NAV reports DONE, ABORTED, or surfaces business-validation warnings, then either marks the transaction as fiscalized, retries (transient errors), or raises a regulatory rejection (ABORTED).

Submission window: 5 minutes from invoice issuance (ŠovUv rule of NAV's interface spec). Zyntem submits well within that window.

Country config fields

The country_config object for Hungarian locations:

Field	Type	Required	Description
tax_number	string	Yes	8-digit taxpayer root id (first 8 digits of the adószám).
vat_code	string	Yes	Single VAT code digit (position 9 of the adószám).
county_code	string	Yes	Two-digit county code (positions 10–11 of the adószám).
login	string	Yes	15-character technical-user login issued by NAV.
password_hash	string	Yes	SHA-512 hex digest of the technical user's password (128 hex chars).
signature_key	string	Yes	19-character signing key issued by NAV (server-side secret).
exchange_key_b64	string	Yes	16-byte AES-128 exchange key, base64-encoded.
software_id	string	Yes	Stable 18-character software identifier registered with NAV.
legal_name	string	No	Taxpayer legal name printed on the invoice.
community_vat_number	string	No	Optional EU community VAT number (HU + 8 digits).
group_member_tax_number	string	No	Optional VAT-group member tax number (csoportos adóalanyiság).

Cloud-only. Hungary's flow has no on-device certificate and no signing hardware. The technical-user credentials come from a one-time NAV portal registration (onlineszamla.nav.gov.hu) — Zyntem never sees the underlying password, only the SHA-512 hash.

Configuration example

curl -X POST https://api.zyntem.dev/v1/locations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zyn_test_abc123def456..." \
  -d '{
    "name": "Budapest Office",
    "country": "HU",
    "address": "Andrássy út 1, 1061 Budapest",
    "country_config": {
      "tax_number": "12345678",
      "vat_code": "2",
      "county_code": "41",
      "login": "tech-user-15chr",
      "password_hash": "<128-char SHA-512 hex digest>",
      "signature_key": "1234567890ABCDEFGHJ",
      "exchange_key_b64": "AAECAwQFBgcICQoLDA0ODw==",
      "software_id": "ZYNTEM-CLOUD-00001",
      "legal_name": "Zyntem Minta Kft."
    }
  }'

Creating a transaction

Example: A B2C sale of HUF 12 700 at a Budapest café.

curl -X POST https://api.zyntem.dev/v1/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zyn_test_abc123def456..." \
  -d '{
    "location_id": "loc_abc123",
    "type": "sale",
    "amount": 12700,
    "currency": "HUF",
    "line_items": [
      {
        "description": "Espresso",
        "quantity": 2,
        "unit_price": 850,
        "vat_rate": 2700
      },
      {
        "description": "Pastry",
        "quantity": 3,
        "unit_price": 3000,
        "vat_rate": 2700
      }
    ]
  }'

Response

{
  "id": "txn_abc123",
  "status": "pending_submission",
  "fiscal_id": "NAV-TX-00042-INV-2026-001",
  "country": "HU",
  "created_at": "2026-03-15T14:30:22Z"
}

The transaction returns pending_submission immediately. NAV finalizes asynchronously; subscribe to the transaction.fiscalized webhook (or poll GET /v1/transactions/{id}) to learn when status flips to success.

Sandbox access

NAV operates a separate sandbox at api-test.onlineszamla.nav.gov.hu. Sandbox credentials are obtained from the test portal (onlineszamla-test.nav.gov.hu). Sandbox routing is automatic — use a test API key (zyn_test_...) and Zyntem dispatches to the sandbox host.

curl -X POST https://api.zyntem.dev/v1/transactions \
  -H "Authorization: Bearer zyn_test_abc123def456..." \
  -d '{ "location_id": "loc_abc123", ... }'

Sandbox onboarding typically takes 2–4 weeks (NAV processes the technical-user request manually).

Error handling

When NAV rejects an invoice, error.category distinguishes recoverable from terminal failures:

• transient — network blip, 5xx, rate-limit. Zyntem retries automatically.
• regulatory_reject — NAV ABORTED or business-validation error (error.authority_code carries NAV's code, e.g. INVOICE_VALIDATION_ERROR). Correct the invoice and re-issue.
• permanent — sealed-config or payload error on Zyntem's side. Surface to operator.
• duplicate_as_success — NAV already accepted an indistinguishable transaction; treated as success.

See the Error handling guide for the full taxonomy.