Skip to main content

Matching Payments

How to match payments with documents in the REST API?

Written by Lenka Haringerová

A cash register or bank account can be matched with one or more issued or received invoices in the following way:

<?xml version="1.0"?>
<winstrom version="1.0">
	<banka>
		<!-- uhrazující doklad; může být i "pokladni-pohyb" -->
		<id>code:BANKA1</id>
		<!-- lze normálně uvést další vlastnosti dokladu jako při běžném importu -->
		<sparovani>
			<!-- uhrazovaný doklad - pro uhrazení více faktur se element opakuje type - ve spárování lze použít pouze faktury stejného typu (vydané nebo přijaté) castka - (volitelný) určuje částku, která se má z faktury uhradit -->
			<uhrazovanaFak type="faktura-vydana" castka="1000">code:FV1</uhrazovanaFak>
			<zbytek>ignorovat</zbytek>
			<!-- co dělat se zbytkem, pokud nastane -->
		</sparovani>
	</banka>
</winstrom>

Multiple invoices can be settled in a single matching operation. When matching with multiple invoices, all listed invoices must be of the same invoice type (issued or received).

For each invoice being settled, you can specify the castka attribute, whose value limits the total amount to be settled from that invoice.

<?xml version="1.0"?>
<winstrom version="1.0">
	<banka>
		<id>code:BANKA1</id>
		<sparovani>
			<!-- uhrazují se dvě faktury najednou -->
			<uhrazovanaFak type="faktura-vydana" castka="500">code:FV1</uhrazovanaFak>
			<!-- z FV1 se uhrazuje 500 -->
			<uhrazovanaFak type="faktura-vydana">code:FV2</uhrazovanaFak>
			<!-- z FV2 se uhrazuje celá zbývající částka -->
			<zbytek>ignorovat</zbytek>
		</sparovani>
	</banka>
</winstrom>

Example in JSON format:

{
    "winstrom": {
        "banka": {
            "id": "code:BANKA1",
            "sparovani": {
                "uhrazovanaFak": {
                    "@castka": "500.0",
                    "@type": "faktura-vydana",
                    "filter": "code:FV2"
                },
                "zbytek": "ignorovat"
            }
        }
    }
}

The value of the castka attribute must not exceed the remaining amount due on the invoice being settled. If the value of the castka attribute is less than the remaining amount due, that particular invoice will always be settled as a partial payment. If the value of the castka attribute equals the remaining amount due, the attribute becomes redundant and the matching will proceed as if it had not been specified.

It may happen that the paying amount on the paying document and the sum of amounts on the invoices being settled do not match (e.g. due to an exchange rate difference or a few cents missing), in which case the import is governed by the value in the tag <zbytek/> .

The following remainder values can be selected:

  • ne: no remainder is allowed; if one occurs, it is an error

  • zauctovat: the remainder is posted

  • ignorovat: the remainder is ignored

  • castecnaUhrada: if the amount on the paying document is less than on the invoice being settled, it is treated as a partial payment

  • castecnaUhradaNeboZauctovat: if the amount on the paying document is greater than on the invoice being settled, the remainder is posted; if it is less, it is treated as a partial payment

  • castecnaUhradaNeboIgnorovat: if the amount on the paying document is greater than on the invoice being settled, the remainder is ignored; if it is less, it is treated as a partial payment

The import result, depending on the selected value of the <zbytek/> tag and the size of the difference between the paying and settled amounts (the remainder), can take the following forms:

parameter zbytek

remainder = 0

remainder > 0

remainder < 0

ne

Invoices will be fully settled, or partially settled if the payment was limited by the castka attribute.

The paying document will be matched.

ERROR:

400 – The amounts on the invoice being settled and the paying document do not match

zauctovat

Invoices will be fully settled, or partially settled if the payment was limited by the castka attribute.

The paying document will be matched.

An internal document will be created for the remainder.

ignorovat

Invoices will be fully settled, or partially settled if the payment was limited by the castka attribute.

The paying document will not be matched.

castecnaUhrada

ERROR:

400 – Partial payment does not make sense; the amount on the paying document is greater than on the invoice being settled

The amount of the paying document is progressively "consumed" to settle the invoices or the amounts to be settled from them, in the order they are listed in the <sparovani/> element.

An invoice for which the remaining payment amount is insufficient for a full settlement or to cover the full specified amount will be partially settled up to the remaining available funds from the paying amount.

Invoices for which no funds remain from the paying amount are excluded from the matching and will remain unsettled.

castecnaUhradaNeboZauctovat

Invoices will be fully settled, or partially settled if the payment was limited by the castka attribute.

The paying document will be matched.

An internal document will be created for the remainder.

castecnaUhradaNeboIgnorovat

Invoices will be fully settled, or partially settled if the payment was limited by the castka attribute.

The paying document will not be matched.

In the tag <sparovani/> you can also specify the following. This is optional and is taken from the company settings by default.

<!-- kurzový rozdíl, defaultně z nastavení firmy --> 

<krTypDokl></krTypDokl> 
<!-- typ dokladu pro kurzový rozdíl --> 

<krTypDoklZisk></krTypDoklZisk> 
<!-- typ dokladu pro zisk kurzového rozdílu --> 

<krTypDoklZtrata></krTypDoklZtrata> 
<!-- typ dokladu pro ztrátu kurzového rozdílu --> 

<krRada></krRada> 
<!-- řada pro kurzový rozdíl --> 

<!-- zbytek, defaultně z nastavení firmy --> 

<zbTypDokl></zbTypDokl> 
<!-- typ dokladu pro zbytek --> 

<zbTypDoklZisk></zbTypDoklZisk> 
<!-- typ dokladu pro zisk zbytku --> 

<zbTypDoklZtrata></zbTypDoklZtrata> 
<!-- typ dokladu pro ztrátu zbytku --> 

<zbRada></zbRada> 
<!-- řada pro zbytek -->

Matching a payment in the home currency with an invoice in a foreign currency

In addition to matching documents in the same currency, it is also possible to match a cash register or bank account in the home currency with invoices in a foreign currency. The foreign currency must be the same for all matched invoices. In this case, the paying document is automatically converted to the foreign currency at an exchange rate equal to the ratio of the paying amount on the bank account in the home currency to the total amount due on the invoices in the foreign currency.

Unmatching

Unmatching can be performed analogously:

<?xml version="1.0"?>
<winstrom version="1.0">
	<banka>
		<id>code:BANKA1</id>
		<odparovani>
			<uhrazovanaFak type="faktura-vydana">code:FV1</uhrazovanaFak>
			<!-- nepovinné, lze vícekrát -->
		</odparovani>
	</banka>
</winstrom>

Example in JSON:

{
    "winstrom": {
        "banka": {
            "id": "code:BANKA1",
            "odparovani": {
                "uhrazovanaFak": {
                    "@type": "faktura-vydana",
                    "filter": "code:FV1"
                }
            }
        }
    }
}

If no invoice to be settled is specified, all invoices currently matched with the given paying document will be unmatched.

Matching is idempotent (i.e. the call can be repeated).

Automatic matching

Automatic payment matching can also be triggered via the API.

curl -H "Accept: application/xml" -u winstrom:winstrom -X PUT -L https://demo.flexibee.eu:5434/c/demo/banka/automaticke-parovani

Filtering can be used to restrict the payments that enter the matching process.

/c/{firma}/banka/{filtr}/automaticke-parovani

The example below will only match payments entered from 1 March 2020 onwards.

/c/{firma}/banka/(datVyst>='2020-03-01')/automaticke-parovani

Parameters can be used to set the matching mode, restrict which accounting periods are searched for documents to be settled, and define how to handle the difference between the payment and the document being settled.

/c/{firma}/banka/automaticke-parovani?mod=jenVar&obdobi=aktualni&ignorovat-rozdil-castka=1.5&zauctovat-rozdil=true

mod – automatic matching mode. Possible values:

  • varCasUcet: match by variable symbol, amount, and account

  • varCas: match by variable symbol and amount (default value)

  • jenVar: match by variable symbol

  • jenCastka: attach – match when the amount matches but the variable symbol does not

obdobi – which accounting periods to search for documents to be settled. Possible values:

  • aktualni: current accounting period

  • aktualni-predchozi: current and previous accounting period

  • vsechna: all accounting periods (default value)

ignorovat-rozdil-castka – the maximum difference between the payment and the document being settled to ignore (default value 0.0 – amounts must match exactly; in jenVar mode the difference setting is ignored). This refers to the difference in the amount in the currency of the bank document — for example, with a bank document in EUR and the ignorovat-rozdil-castka=1 parameter, a difference of 1 EUR will be ignored.

zauctovat-rozdil – whether documents are posted when payments are combined and the document amounts do not match (default value true – an internal document will be created for the difference between the documents and the documents will be fully matched)

It is also possible to further restrict automatic matching using automatic matching parametrization.

  • In the case of the advanced automatic matching variant, the period can be influenced via the advanced parameter paramParovaniUhradOmezeniObdobiDrgn with the values: aktualni, aktualni-predchozi (application default), vsechna (API default).

Legacy matching method via REST API only

The legacy method, which allowed matching only via REST API (not via XML import) at the URL /c/{firma}/parovani-uhrad, is also supported.

<?xml version="1.0"?>
<winstrom version="1.0">
	<sparovani>
		<uhrazovanaFak type="faktura-prijata">code:FP1</uhrazovanaFak>
		<!-- faktura -->
		<uhrazujiciDokl type="banka">code:BANKA1</uhrazujiciDokl>
		<!-- bankovní doklad -->
		<zbytek>ignorovat</zbytek>
		<!-- zbytek ignorovat -->
	</sparovani>
</winstrom>

<?xml version="1.0"?>
<winstrom version="1.0">
	<odparovani>
		<uhrazujiciDokl>code:foo</uhrazujiciDokl>
		<!-- povinné -->
		<uhrazovanaFak>code:bar</uhrazovanaFak>
		<!-- nepovinné, lze vícekrát -->
	</odparovani>
</winstrom>
Related Articles
Cash Payment
Advance Payment Deduction and Tax Document for Payment - API
Offsets
Bonds/Links of ZDD --- **Note:** "ZDD" likely refers to a specific system or document type. Here is the clean translation: Tax Document Relationships
Credit Notes
Did this answer your question?