Getting started · 🇩🇪 Germany - OpenFiskal Platform API

This guide walks the v1 integration contract for Germany. You create a deu API key, onboard a merchant with a German fiscal_identity, register a location and terminal, fiscalize the register under KassenSichV, open a register session, start an operation, and complete it with the typed payment contract.

Examples use https://sandbox.api.openfiskal.com/v1. Replace with https://api.openfiskal.com/v1 when you go live.

Prerequisites

An OpenFiskal tenant
A tenant-scoped, country-scoped API key (of_test_deu_… or of_live_deu_…)
curl or an HTTP client
A backend service / database to store your API key, entity IDs and ETags

Authentication model

Use the standard bearer header on every request. The key encodes the environment and country — of_test_deu_… for the German sandbox, of_live_deu_… for German production. A deu key rejects payloads for any other country.

-H "Authorization: Bearer of_live_deu_abc123..."

Every merchant-scoped request must also include:

-H "X-OpenFiskal-Merchant: merchant_01HXYZ"

This header value is the merchant ID returned by POST /merchants, not your API key.

Create resources

Create these resources in order. The register cannot fiscalize until the merchant has a DEU fiscal_identity.

Create your API key

Generate a deu key at console.openfiskal.com. Store it in your secrets manager. Format: of_{env}_deu_{random}, e.g. of_test_deu_abcdefgh12345678.

Create a merchant

country_code and every address.country_code must be DEU (ISO 3166-1 alpha-3). The German fiscal_identity requires both tax_number (Steuernummer) and vat_id (USt-IdNr).

curl -X POST https://sandbox.api.openfiskal.com/v1/merchants \
  -H "Authorization: Bearer of_test_deu_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Beispiel Handel GmbH",
    "country_code": "DEU",
    "address": {
      "line1": "Beispielstraße 12",
      "city": "Berlin",
      "postal_code": "10115",
      "country_code": "DEU"
    },
    "fiscal_identities": [
      {
        "country_code": "DEU",
        "tax_number": "12/345/67890",
        "vat_id": "DE123456789"
      }
    ]
  }'

The returned id becomes the X-OpenFiskal-Merchant header on every merchant-scoped request that follows.

Create a location

A location is a physical point of sale. timezone is a required IANA zone string.

curl -X POST https://sandbox.api.openfiskal.com/v1/locations \
  -H "Authorization: Bearer of_test_deu_abc123..." \
  -H "X-OpenFiskal-Merchant: merchant_01HXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Berlin Mitte",
    "address": {
      "line1": "Beispielstraße 12",
      "city": "Berlin",
      "postal_code": "10115",
      "country_code": "DEU"
    },
    "timezone": "Europe/Berlin"
  }'

Create a register

A register is the logical checkout or terminal that creates operations.

curl -X POST https://sandbox.api.openfiskal.com/v1/registers \
  -H "Authorization: Bearer of_test_deu_abc123..." \
  -H "X-OpenFiskal-Merchant: merchant_01HXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "location_id": "loc_01HXYZ",
    "name": "Register 1",
    "external_id": "pos-register-1"
  }'

Fiscalize the register

Before the register can accept operations, call POST /registers/{id}/fiscalize. This provisions the KassenSichV components — the TSS and POS client — using the merchant’s German fiscal_identity and the location’s country. The response is 202 Accepted; poll GET /registers/{id} until fiscalizedAt is populated.

curl -X POST https://sandbox.api.openfiskal.com/v1/registers/reg_01HXYZ/fiscalize \
  -H "Authorization: Bearer of_test_deu_abc123..." \
  -H "X-OpenFiskal-Merchant: merchant_01HXYZ"

Verify your saved IDs

Persist the returned merchant, location, and register IDs. You will use them for every later operation request.

Perform a fiscalized sale

Once your register is fiscalized, you can create and complete sale operations.

Open a session

Every POS sale, return, or exchange must bind to an open register session. Send a session_open operation with the register, currency, and counted opening cash float. Without an open session, POST /operations with source: POS is rejected.

curl -X POST https://sandbox.api.openfiskal.com/v1/operations \
  -H "Authorization: Bearer of_test_deu_abc123..." \
  -H "X-OpenFiskal-Merchant: merchant_01HXYZ" \
  -H "Idempotency-Key: ses-2026-04-30-reg_01HXYZ-open" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "session_open",
    "register_id": "reg_01HXYZ",
    "currency": "EUR",
    "opening_balance_amount": "50.00"
  }'

Persist the returned session_id. See Sessions for cash adjustments, end-of-shift counting, and closing.

Start an operation

POST /operations is a single-shot create. All monetary fields are decimal strings, not integers. pretax_amount + tax_amount + tip_amount must equal total_amount. line_items is required with at least one entry.

curl -X POST https://sandbox.api.openfiskal.com/v1/operations \
  -H "Authorization: Bearer of_test_deu_abc123..." \
  -H "X-OpenFiskal-Merchant: merchant_01HXYZ" \
  -H "Idempotency-Key: op-order-1001-start" \
  -H "Content-Type: application/json" \
  -d '{
    "register_id": "reg_01HXYZ",
    "source": "POS",
    "type": "sale",
    "currency": "EUR",
    "external_id": "order-1001",
    "pretax_amount": "133.00",
    "tax_amount": "22.30",
    "tip_amount": "0.00",
    "total_amount": "155.30",
    "line_items": [
      {
        "title": "Slim Fit Jeans",
        "sku_identifier": "JEANS-001",
        "quantity": 1,
        "unit_price": "79.00",
        "total_amount": "79.00",
        "taxes": [
          { "name": "MwSt. 19%", "rate": "0.19", "tax_amount": "12.61" }
        ]
      },
      {
        "title": "Cotton T-Shirt",
        "sku_identifier": "TSHIRT-WHT-M",
        "quantity": 2,
        "unit_price": "24.90",
        "total_amount": "49.80",
        "taxes": [
          { "name": "MwSt. 19%", "rate": "0.19", "tax_amount": "7.95" }
        ]
      },
      {
        "title": "Espresso Beans 250 g",
        "sku_identifier": "ESP-250",
        "quantity": 1,
        "unit_price": "8.50",
        "total_amount": "8.50",
        "taxes": [
          { "name": "MwSt. 7%", "rate": "0.07", "tax_amount": "0.56" }
        ]
      },
      {
        "title": "Coffee Brewing Book",
        "sku_identifier": "BOOK-CFE",
        "quantity": 1,
        "unit_price": "18.00",
        "total_amount": "18.00",
        "taxes": [
          { "name": "MwSt. 7%", "rate": "0.07", "tax_amount": "1.18" }
        ]
      }
    ]
  }'

Sending line_items[].taxes[] is required.

Response:

HTTP/1.1 201 Created
ETag: "1"
X-Request-Id: req_01JSTART

{
  "id": "op_01HXYZ",
  "resource_version": 1,
  "merchant_id": "merchant_01HXYZ",
  "location_id": "loc_01HXYZ",
  "register_id": "reg_01HXYZ",
  "source": "POS",
  "external_id": "order-1001",
  "status": "open",
  "type": "sale",
  "currency": "EUR",
  "pretax_amount": "133.00",
  "tax_amount": "22.30",
  "tip_amount": "0.00",
  "total_amount": "155.30",
  "line_items": [
    {
      "id": "li_01HXYZ",
      "title": "Slim Fit Jeans",
      "sku_identifier": "JEANS-001",
      "quantity": 1,
      "unit_price": "79.00",
      "total_amount": "79.00",
      "taxes": [
        { "id": "lit_01HXYZ", "name": "MwSt. 19%", "rate": "0.19", "tax_amount": "12.61" }
      ]
    },
    {
      "id": "li_02HXYZ",
      "title": "Cotton T-Shirt",
      "sku_identifier": "TSHIRT-WHT-M",
      "quantity": 2,
      "unit_price": "24.90",
      "total_amount": "49.80",
      "taxes": [
        { "id": "lit_02HXYZ", "name": "MwSt. 19%", "rate": "0.19", "tax_amount": "7.95" }
      ]
    },
    {
      "id": "li_03HXYZ",
      "title": "Espresso Beans 250 g",
      "sku_identifier": "ESP-250",
      "quantity": 1,
      "unit_price": "8.50",
      "total_amount": "8.50",
      "taxes": [
        { "id": "lit_03HXYZ", "name": "MwSt. 7%", "rate": "0.07", "tax_amount": "0.56" }
      ]
    },
    {
      "id": "li_04HXYZ",
      "title": "Coffee Brewing Book",
      "sku_identifier": "BOOK-CFE",
      "quantity": 1,
      "unit_price": "18.00",
      "total_amount": "18.00",
      "taxes": [
        { "id": "lit_04HXYZ", "name": "MwSt. 7%", "rate": "0.07", "tax_amount": "1.18" }
      ]
    }
  ],
  "cart_level_discounts": [],
  "payments": [],
  "created_at": "2026-05-21T10:14:20Z",
  "updated_at": "2026-05-21T10:14:20Z"
}

Complete the operation

Completion includes typed payment legs. Use one entry per tender leg and include processor references where available. Send the latest ETag in If-Match. The completed operation returns fiscal_information with the KassenSichV regime.

Operation bodies are immutable after creation — there is no endpoint to amend them. Build the full line-item and amount set before calling POST /operations. Open operations only accept POST .../complete and POST .../void.

curl -X POST https://sandbox.api.openfiskal.com/v1/operations/op_01HXYZ/complete \
  -H "Authorization: Bearer of_test_deu_abc123..." \
  -H "X-OpenFiskal-Merchant: merchant_01HXYZ" \
  -H "Idempotency-Key: op-order-1001-complete" \
  -H 'If-Match: "1"' \
  -H "Content-Type: application/json" \
  -d '{
    "payments": [
      {
        "payment_id": "pay_1001_card",
        "method": "card",
        "amount": "155.30",
        "currency": "EUR",
        "status": "captured",
        "processor": "sumup",
        "card_brand": "visa",
        "processor_reference": "ch_123",
        "processed_at": "2026-05-21T10:14:24Z"
      }
    ]
  }'

Response:

HTTP/1.1 200 OK
ETag: "2"
X-Request-Id: req_01JCOMPLETE

{
  "id": "op_01HXYZ",
  "resource_version": 2,
  "status": "completed",
  "payments": [
    {
      "payment_id": "pay_1001_card",
      "method": "card",
      "amount": "155.30",
      "currency": "EUR",
      "status": "captured",
      "processor": "sumup",
      "processor_reference": "ch_123",
      "card_brand": "visa",
      "processed_at": "2026-05-21T10:14:24Z"
    }
  ],
  "fiscal_information": {
    "regime": "KassenSichV",
    "document_number": "13",
    "document_type": "Kassenbeleg",
    "tss_serial_number": "ae1a722bb28fb4f88f5592abfc6b72ef425a3bc2643eb1330069b718eea5165a",
    "pos_client_serial_number": "b187455f-a29c-4e99-8efc-083ea1302bab",
    "signature_algorithm": "ecdsa-plain-SHA256",
    "time_format": "unixTime",
    "start_event": {
      "signed_at": "2026-05-21T10:14:21Z"
    },
    "end_event": {
      "signed_at": "2026-05-21T10:14:24Z",
      "transaction_counter": 50,
      "signature": "BWdC1LCZyGnhYVB+AJ1um9QeLMs3Am5G2x8IAWqsQomo5/kAbuBklvadO4/m7IZVfSEz85t6Yhi0h262txHJUw==",
      "public_key": "BAXXi19q02bz3nPTYkcpvHsTkH9KtjPBv3jdqZiOlyyQKSTvceqLkrTL7ZWsc4RhzSmc7uNIeBtGvd3XQPXnLy8=",
      "process_type": "Kassenbeleg-V1",
      "process_data": "Beleg^128.80_26.50_0.00_0.00_0.00^155.30:Unbar"
    },
    "verification": {
      "qr_data": "V0;b187455f-a29c-4e99-8efc-083ea1302bab;Kassenbeleg-V1;Beleg^128.80_26.50_0.00_0.00_0.00^155.30:Unbar;13;50;2026-05-21T10:14:21;2026-05-21T10:14:24;ecdsa-plain-SHA256;unixTime;BWdC1LCZyGnhYVB+AJ1um9QeLMs3Am5G2x8IAWqsQomo5/kAbuBklvadO4/m7IZVfSEz85t6Yhi0h262txHJUw==;BAXXi19q02bz3nPTYkcpvHsTkH9KtjPBv3jdqZiOlyyQKSTvceqLkrTL7ZWsc4RhzSmc7uNIeBtGvd3XQPXnLy8="
    }
  }
}

Print the receipt

A completed operation returns the receipt data under fiscal_information. Print verification.qr_data as a QR code on your receipt, exactly as returned, byte for byte. That code carries the full TSE data, including both serial numbers, so it covers the TSE requirements on its own. For the required fields, where each comes from, and example layouts, see German receipt requirements.

Void an open operation

If the sale is abandoned before completion, void the open operation:

curl -X POST https://sandbox.api.openfiskal.com/v1/operations/op_01HXYZ/void \
  -H "Authorization: Bearer of_test_deu_abc123..." \
  -H "X-OpenFiskal-Merchant: merchant_01HXYZ" \
  -H "Idempotency-Key: op-order-1001-void" \
  -H 'If-Match: "1"' \
  -H "Content-Type: application/json" \
  -d '{ "reason": "void_before_completion" }'

Next steps

Transaction lifecycle — operation lifecycle in detail
Payment lifecycle — split tender, asynchronous settlement

Overview

Transaction processing

Operations and delivery

Fiscalization API

Changelog

Getting started · 🇩🇪 Germany

Prerequisites

Authentication model

Create resources

Perform a fiscalized sale

Print the receipt

Void an open operation

Next steps

​Prerequisites

​Authentication model

​Create resources

​Perform a fiscalized sale

​Print the receipt

​Void an open operation

​Next steps

Prerequisites

Authentication model

Create resources

Perform a fiscalized sale

Print the receipt

Void an open operation

Next steps