Payments

The Payments API handles all financial transactions including full payments, split billing, and refunds. Every payment is signed via the fiskaly Cloud TSE and generates an immutable receipt as required by German fiscal law.

TSE Signing (KassenSichV)

Every payment transaction is cryptographically signed via the fiskaly Cloud TSE before a receipt is generated. The TSE signature data (transaction number, serial number, signature, and QR code) is included in every payment response. This is a legal requirement under the German Kassensicherungsverordnung (KassenSichV).

Belegausgabepflicht

German law (Belegausgabepflicht) mandates that every transaction generates a receipt for the customer. Possfer automatically creates a receipt with the TSE signature and QR code for every successful payment. The customer must be offered this receipt, even if they decline it.

Pay Order

POST/api/orders/:id/payProtected

Process a full payment for an order. The payment is signed via TSE and a receipt is generated. All payment records are immutable and append-only per GoBD requirements.

Path Parameters

Name	Type	Required	Description
`id`	`uuid`	Required	The order ID to pay.

Request Body

Name	Type	Required	Description
`payment_method`	`string`	Required	Payment method: cash, card, girocard, or mobile.
`amount`	`integer`	Required	Payment amount in cents (e.g. 2490 = 24.90 EUR). Must match or exceed the order total.
`tip_amount`	`integer`	Optional	Tip amount in cents. Default: 0. Added on top of the order total.

json

{
  __PH0__: "card",
  __PH2__: 5430,
  __PH3__: 200
}

Response 200 OK

Returns the full receipt including TSE signature data.

json

{
  __PH0__: {
    __PH1__: "pay-uuid-001",
    __PH3__: "d290f1ee-6c54-4b01-90e6-d701748f0851",
    __PH5__: "card",
    __PH7__: 5430,
    __PH8__: 200,
    __PH9__: 5630,
    __PH10__: "EUR",
    __PH12__: "completed",
    __PH14__: "2026-03-20T15:00:00Z"
  },
  __PH16__: {
    __PH17__: "2026-0320-0042",
    __PH19__: {
      __PH20__: "Gasthaus zur Linde",
      __PH22__: "Gasthaus zur Linde GmbH",
      __PH24__: "DE123456789",
      __PH26__: "Hauptstraße 42, 10115 Berlin"
    },
    __PH28__: [
      {
        __PH29__: "Rindersteak",
        __PH31__: 2,
        __PH32__: 2490,
        __PH33__: 4980,
        __PH34__: 19
      },
      {
        __PH35__: "Pommes Frites (Takeaway)",
        __PH37__: 1,
        __PH38__: 450,
        __PH39__: 450,
        __PH40__: 7
      }
    ],
    __PH41__: 5430,
    __PH42__: 200,
    __PH43__: 5630,
    __PH44__: [
      { __PH45__: 19, __PH46__: 4185, __PH47__: 795 },
      { __PH48__: 7, __PH49__: 421, __PH50__: 29 }
    ],
    __PH51__: "card",
    __PH53__: {
      __PH54__: 1042,
      __PH55__: "abc123def456...",
      __PH57__: "MEUCIQDx7v...",
      __PH59__: 8421,
      __PH60__: "2026-03-20T15:00:00Z",
      __PH62__: "2026-03-20T15:00:01Z",
      __PH64__: "Kassenbeleg-V1",
      __PH66__: "Beleg^5430^5630^2490:19.00_450:7.00^",
      __PH68__: "V0;abc123def456...;Kassenbeleg-V1;..."
    },
    __PH70__: "2026-03-20T15:00:01Z"
  }
}

Amount in Cents

All monetary values are expressed in cents (Euro cents) to avoid floating-point precision issues. For example, 2490 represents 24.90 EUR.

Split Payment

POST/api/orders/:id/split-payProtected

Pay for specific items within an order. Allows individual guests to pay for their own items. Each split payment generates its own TSE-signed receipt.

Path Parameters

Name	Type	Required	Description
`id`	`uuid`	Required	The order ID.

Request Body

Name	Type	Required	Description
`payment_method`	`string`	Required	Payment method: cash, card, girocard, or mobile.
`tip_amount`	`integer`	Optional	Tip amount in cents for this split. Default: 0.
`item_ids`	`uuid[]`	Required	Array of order item UUIDs to include in this split payment.

json

{
  __PH0__: "girocard",
  __PH2__: 100,
  __PH3__: [
    "item-uuid-1",
    "item-uuid-2"
  ]
}

Response 200 OK

Returns a payment and receipt object for the selected items only, including TSE signature data. Same structure as the full payment response, but scoped to the paid items.

json

{
  __PH0__: {
    __PH1__: "pay-uuid-002",
    __PH3__: "d290f1ee-6c54-4b01-90e6-d701748f0851",
    __PH5__: "girocard",
    __PH7__: 4980,
    __PH8__: 100,
    __PH9__: 5080,
    __PH10__: "EUR",
    __PH12__: "completed",
    __PH14__: ["item-uuid-1", "item-uuid-2"],
    __PH17__: "2026-03-20T15:05:00Z"
  },
  __PH19__: {
    __PH20__: "2026-0320-0043",
    __PH22__: [
      { __PH23__: "Rindersteak", __PH25__: 2, __PH26__: 2490, __PH27__: 4980, __PH28__: 19 }
    ],
    __PH29__: 4980,
    __PH30__: 100,
    __PH31__: 5080,
    __PH32__: { __PH33__ : "TSE signature data (see full payment response)" },
    __PH35__: "2026-03-20T15:05:01Z"
  }
}

Multi-Split Payment

POST/api/orders/:id/multi-split-payProtected

Process multiple split payments in a single request. Each split entry generates its own TSE-signed receipt. Useful when settling an entire table at once with different payment methods.

Path Parameters

Name	Type	Required	Description
`id`	`uuid`	Required	The order ID.

Request Body

Name	Type	Required	Description
`payments`	`array`	Required	Array of split payment entries. Each entry must include payment_method, item_ids, and optionally tip_amount.

Payment Entry Fields

Name	Type	Required	Description
`payment_method`	`string`	Required	Payment method: cash, card, girocard, or mobile.
`item_ids`	`uuid[]`	Required	Array of order item UUIDs for this split.
`tip_amount`	`integer`	Optional	Tip amount in cents for this split. Default: 0.

json

{
  __PH0__: [
    {
      __PH1__: "card",
      __PH3__: 200,
      __PH4__: ["item-uuid-1"]
    },
    {
      __PH6__: "cash",
      __PH8__: 0,
      __PH9__: ["item-uuid-2"]
    }
  ]
}

Response 200 OK

json

{
  __PH0__: [
    {
      __PH1__: {
        __PH2__: "pay-uuid-003",
        __PH4__: "card",
        __PH6__: 4980,
        __PH7__: 200,
        __PH8__: 5180,
        __PH9__: ["item-uuid-1"],
        __PH11__: "completed"
      },
      __PH13__: {
        __PH14__: "2026-0320-0044",
        __PH16__: { __PH17__ : "TSE signature data" }
      }
    },
    {
      __PH19__: {
        __PH20__: "pay-uuid-004",
        __PH22__: "cash",
        __PH24__: 450,
        __PH25__: 0,
        __PH26__: 450,
        __PH27__: ["item-uuid-2"],
        __PH29__: "completed"
      },
      __PH31__: {
        __PH32__: "2026-0320-0045",
        __PH34__: { __PH35__ : "TSE signature data" }
      }
    }
  ]
}

Refund

POST/api/orders/:id/refundAdmin Only

Issue a refund for a previously paid order. Restricted to admin/owner roles. Creates an immutable refund record linked to the original payment.

Admin Only

Refunds can only be issued by users with the owner or admin role. This restriction prevents unauthorized refunds and ensures accountability as required by GoBD.

Path Parameters

Name	Type	Required	Description
`id`	`uuid`	Required	The order ID to refund.

Request Body

Name	Type	Required	Description
`payment_method`	`string`	Required	Refund method: cash, card, girocard, or mobile. Typically matches the original payment method.
`reason`	`string`	Required	Reason for the refund. Recorded in the audit trail for GoBD compliance.

json

{
  __PH0__: "card",
  __PH2__: "Customer complaint - food quality issue"
}

Response 200 OK

json

{
  __PH0__: {
    __PH1__: "refund-uuid-001",
    __PH3__: "d290f1ee-6c54-4b01-90e6-d701748f0851",
    __PH5__: "pay-uuid-001",
    __PH7__: "card",
    __PH9__: -__PH26__,
    __PH10__: "Customer complaint - food quality issue",
    __PH12__: "completed",
    __PH14__: {
      __PH15__: 1043,
      __PH16__: "abc123def456...",
      __PH18__: "MEQCIF8k...",
      __PH20__: "Kassenbeleg-V1",
      __PH22__: "V0;abc123def456...;Kassenbeleg-V1;..."
    },
    __PH24__: "2026-03-20T16:00:00Z"
  }
}

Immutable Records

Refunds are stored as separate, append-only records. The original payment entry is never modified or deleted. Both the payment and refund remain permanently in the system for the 10-year GoBD retention period.

Send Receipt via Email

POST/api/orders/:id/send-receiptProtected

Send the payment receipt to the customer's email address. The email includes the full receipt with TSE signature data and QR code.

Path Parameters

Name	Type	Required	Description
`id`	`uuid`	Required	The order ID whose receipt should be emailed.

Request Body

Name	Type	Required	Description
`email`	`string`	Required	The recipient's email address.

json

{
  __PH0__: "gast@example.de"
}

Response 200 OK

json

{
  __PH0__: "Receipt sent successfully to gast@example.de"
}

bash

curl -X POST https://api.possfer.com/api/orders/d290f1ee-6c54-4b01-90e6-d701748f0851/send-receipt \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"email": "gast@example.de"}'

Payment Methods Reference

Value	Description	DSFinV-K Code
`cash`	Bar (cash payment)	Bar
`card`	Credit or debit card (Visa, Mastercard, etc.)	Unbar
`girocard`	Girocard (German EC card system)	Unbar
`mobile`	Mobile payment (Apple Pay, Google Pay, etc.)	Unbar