Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dev.openfiskal.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Each payment entry represents one authorization, cash leg, voucher redemption, or return settlement leg. Payments are supplied on PATCH /operations/{id}/complete; they cannot be reported before completion.

​
Payment enums

FieldAllowed values
methodcash, card, voucher, gift_card, bank_transfer, digital_wallet, store_credit, other
statuspending, authorized, captured, failed, voided, refunded
All amounts are decimal strings (e.g. "42.50"), matching the operation’s amount fields.

​
Split tender

Use one payment object per tender leg. The sum of captured and authorized amounts must match the operation’s total_amount. 
{
  "payments": [
    {
      "payment_id": "pay_cash_1001",
      "method": "cash",
      "status": "captured",
      "amount": "15.00",
      "currency": "EUR"
    },
    {
      "payment_id": "pay_card_1001",
      "method": "card",
      "status": "captured",
      "amount": "32.50",
      "currency": "EUR",
      "processor": "sumup",
      "processor_reference": "ch_123"
    }
  ]
}

​
Tips and gratuity

Use tip_amount on the operation when the tip is part of the fiscalized sale. If your payment processor returns separate payment references for base amount and tip, keep separate payment entries and distinguish them through your own external payment metadata.

​
Asynchronous settlement

Some payment methods settle after the operation is fiscally completed. In that case:
  • complete the operation with the latest known payment state (e.g. authorized)
  • poll the operation resource for later state changes when needed
  • retain the processor and payment references for reconciliation

​
Returns on prior sales

A return is a new operation with type: return referencing the original sale — via related_operation_id when the sale exists in OpenFiskal, or via external_related_operation for sales from a legacy platform. The return’s payments array on completion describes the settlement legs that returned money to the customer.

​
Next steps