Komfortkasse API v2

Komfortkasse API
2.0.0

Base URL 
https://ssl.komfortkasse.eu/api/v2

Komfortkasse Logo

The Komfortkasse API allows you to send orders to Komfortkasse and get their status back (for example, whether they have been paid).

This is Version 2 of the API. Version 1 (deprecated, not available to new customers) can be found at https://komfortkasse.eu/shopsysteme/item/34-api (PDF only).

Overview

Process flow

A normal process flow without any reminders or cancellations:

  1. Your customer places an order in your store using a payment method supported by Komfortkasse (prepayment, invoice, COD)
  2. The order is transmitted to Komfortkasse using POST /orders (or POST /order/{orderNumber} for a single order)
  3. Optional: Upload an invoice PDF for the order with POST /order/{orderNumber}/invoice/{invoiceNumber}
  4. The customer pays the order and Komfortkasse sets paymentStatus to PAID
  5. You read all orders periodically using e.g. GET /orders?paymentStatus=PAID and discover that the order has been paid
  6. Optional manual interventions:
    • POST /order/{orderNumber}/setpaid — mark an order as paid manually
    • POST /order/{orderNumber}/setunpaid — revert a manual setpaid
    • POST /order/{orderNumber}/cancel — cancel an order (sets paymentStatus to CANCELLED)
    • POST /order/remove/{orderNumber} — mark an order as removed externally (sets paymentStatus to DISAPPEARED); use this when the order vanished from your shop (e.g. cancelled by the customer or deleted by an admin) and should no longer be tracked by Komfortkasse; use cancel instead to record an explicit cancellation

Callback / Webhook

You can register a Callback URL in Komfortkasse's API access settings (menu Settings → Shop). If enabled, Komfortkasse will send a callback in the format of Get Order Details for every payment status change. Answer with HTTP 200. If the callback is not successful, Komfortkasse will retry roughly every 15 minutes for up to 7 days.

Komfortkasse will send the Callback Access Code available in the Komfortkasse merchant area as HTTP header X-Komfortkasse-Access-Code. Verify this header value. For extra security, allow callbacks only from Komfortkasse's IP addresses.

Security

For security purposes, use HTTPS requests only.

Formats

  • Date: dd-MM-yyyy
  • Decimal numbers: 0.00

Error handling

Errors are signalled with standard HTTP status codes:

Status Meaning
200 Success
400 Error
401 Authorization problem
404 Not found
500 Internal server error (unexpected; please retry or contact support if it persists)

In case of an error, the response body contains an Error object as defined in the Error schema. Example:

{ "error": "API Key missing" }

Common error messages

Status error message Meaning
401 Authentication header not present The X-Komfortkasse-API-Key header is missing.
401 Invalid authentication header The API key is unknown or no longer valid.
401 Replace '[your API key]' with the API key from the merchant area The literal placeholder string was sent instead of a real key.
400 API not active, contact support API access is disabled for this shop.
400 Update not allowed for non-API Shop Write operation attempted on a shop that only allows reads via the API.
400 Shop not active The shop is not in an active status (e.g. paused, deleted).
400 Missing body Request body is empty or could not be parsed.
400 Missing parameter <name> A required field on the request body is missing or empty.
400 Invalid date: <value>, format should be dd-MM-yyyy A date query parameter does not match the required format.
400 Parameter date is not valid / Parameter dueDate is not valid The order's date or dueDate could not be parsed.
400 Parameter date must not be in the future date is set to a future timestamp on a new order.
400 Parameter dueDate must not be more than 6 months in the future dueDate is too far ahead.
400 Parameter number and number in object do not match Path orderNumber and body number differ.
400 Parameter initialDunningLevel can only be given when creating a new order initialDunningLevel was sent on an update.
400 Could not acquire lock The same order is being updated concurrently — retry.
400 Could not update order (<reason>) Update was rejected (e.g. status no longer allows changes).
400 Refund already exists: <referenceNumber> A refund with the same externalReference already exists.
400 Planned date must be in the future plannedDate on a refund must be in the future.
400 Invalid JSON, comments not allowed in JSON body The body contains HTML comments / non-JSON content.
400 File missing / File size 0 Invoice upload missing or empty.
400 Order already in paymentStatus PAID setpaid called on an already-paid order.
400 Order must have paymentStatus PAID / Order must have manual paymentStatus Preconditions for setunpaid not met.
404 Order '<n>' not found / Order not found Unknown order number for the authenticated shop.

When using a malformed URL, you might not receive an error object but a blank page. When using a completely invalid URL (e.g. without /api) you might also be redirected to the Komfortkasse merchant area login page.

Rate limits

There is no hard rate limit. Please throttle bulk submits and split lists larger than 100 orders into multiple POST /orders calls to avoid timeouts.

Timeouts

Some operations (e.g. Sync Orders) may take a long time. Allow a timeout of at least 10 minutes.

Example Implementation

A sample implementation in PHP is available at https://github.com/ltckomfortkasse/komfortkasse-apiv2-php.

This is version 2.0.0 of this API documentation. Last update on May 1, 2026.

This API is provided under license Proprietary.