A document's payment can be recorded via the API in three ways — by pairing it with a bank or cash document, by mutual offset, or by deducting an advance payment. This article shows how to do this and links to a detailed description of each approach.
Pairing with a payment
Pairing is recorded as part of the paying document in the sparovani element. There can be multiple invoices being paid, but they must all be of the same type:
<winstrom version="1.0">
<banka>
<id>code:B+0017/2026</id>
<sparovani>
<uhrazovanaFak type="faktura-vydana" castka="1000">code:VF1-0167/2026</uhrazovanaFak>
<zbytek>ignorovat</zbytek>
</sparovani>
</banka>
</winstrom>
The same entry in JSON format:
{
"winstrom": {
"@version": "1.0",
"banka": {
"id": "code:B+0017/2026",
"sparovani": {
"uhrazovanaFak": {
"@type": "faktura-vydana",
"@castka": "1000",
"id": "code:VF1-0167/2026"
},
"zbytek": "ignorovat"
}
}
}
}
The castka attribute is optional and limits how much of the invoice is paid. The zbytek element specifies what to do with the difference between the amounts — the possible values are ne, zauctovat, ignorovat, castecnaUhrada, castecnaUhradaNeboZauctovat, and castecnaUhradaNeboIgnorovat; their behavior is described in detail in the article Pairing payments. Unpairing is recorded the same way, just using the odparovani element.
⚠️ A document in the domestic currency cannot be paid from an account kept in a foreign currency — the import will end with the message Úhrada dokladu v domácí měně úhradou v cizí měně není povolená. Therefore, check the currency of the bank account you use for pairing.
Mutual offset
In Flexi, an offset is a fictitious bank statement used to settle a receivable against a payable. It is created in the vzajemny-zapocet record, and pairing is recorded within it exactly the same way as for a bank statement:
<winstrom version="1.0">
<vzajemny-zapocet>
<id>code:ZAP+0016/2026</id>
<typDokl>code:ZAPOCET</typDokl>
<typPohybuK>typPohybu.prijem</typPohybuK>
<bezPolozek>true</bezPolozek>
<sumOsv>100.0</sumOsv>
<sparovani>
<uhrazovanaFak type="faktura-vydana">code:FAV1</uhrazovanaFak>
<zbytek>castecnaUhrada</zbytek>
</sparovani>
<cisSouhrnne>ZAP-123</cisSouhrnne>
</vzajemny-zapocet>
</winstrom>
An offset consists of two documents — one with typPohybu.prijem for the issued invoice and another with typPohybu.vydej for the received invoice; both sides are linked by the same number in cisSouhrnne. An offset can be created and paired in a single request.
ℹ️ For an offset, the zbytek element has the same values as for payment pairing. However, the castecnaUhrada option will result in an error if the amount on the paying document is greater than on the paid document — a partial payment would not make sense in that case.
Payment by advance
A typical process for an advance payment looks like this:
An advance invoice is created from a received order through fulfillment — see Fulfilling an order via the API.
The advance invoice is paid by pairing a payment, as described above.
The order is used to issue the final invoice.
The paid advance is applied to the final invoice via a deduction — see Deducting advances and tax documents for advance payments.
💡 Both pairing and unpairing are idempotent — calling the same request repeatedly won't cause any issues. This can be useful in batch processing, where it isn't certain whether the previous run completed successfully.