Skip to main content

​
Overview

Each payment entry represents one authorization, cash leg, voucher redemption, or return settlement leg. Payments are supplied on POST /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 every payments[].amount must equal the operation’s total_amount — the check is on the full array, regardless of each leg’s status. A pending or failed leg counts toward the sum like any other. 
{
  "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