> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openfiskal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment lifecycle

> How to report payments, split tender, and asynchronous settlement in the current v1 contract.

## 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

| Field    | Allowed values                                                                                     |
| -------- | -------------------------------------------------------------------------------------------------- |
| `method` | `cash`, `card`, `voucher`, `gift_card`, `bank_transfer`, `digital_wallet`, `store_credit`, `other` |
| `status` | `pending`, `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.

```json theme={null}
{
  "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

* [Transaction lifecycle](/pos-operation-ingestion)