Automatic matching (Fio)

Connect your Fio bank account once and incoming transfers settle orders automatically — every payment landing in a durable ledger with a status and a reason, so nothing is ever silently dropped.

Bookitive never holds your money. You connect your organization's own Fio banka account, and a background worker reads incoming transfers and settles the matching orders — tickets sent, map updated, buyer happy — around the clock. Matching is by variable symbol + amount, and every payment it reads is written to a durable Incoming payments ledger with a status, so you always have a row to act on instead of a transfer that vanished.

Connecting

Create a token in Fio

In Fio Internetbanking: Settings → API → create a token for your account.

The token needs payment-upload permission, not just read-only access. Bookitive uses the one stored token for both jobs: downloading statements to match payments and uploading refund batches back to the bank. A read-only token will happily match incoming payments, but its refund imports get rejected by Fio — so grant upload rights now and avoid a surprise the first time you send a refund batch.

Paste it into Bookitive

Settings → Integrations → Fio banka (or the Payments hub, or the onboarding wizard). Bookitive validates the token against the live API immediately, so a typo fails loudly, not silently next week. The token is stored encrypted.

How auto-matching works

A background worker polls Fio continuously. It ticks roughly every 30 seconds, but re-polls any given organization only about every 55 seconds — so the practical latency from a transfer executing to tickets landing is about one minute, not instant and not thirty seconds.

A payment settles an order automatically only when all of these hold:

The payment is in CZK,
Its normalized variable symbol matches a pending bank-transfer order's reference,
The amount is exact.

On an auto-match the order flips to paid, tickets are issued and emailed, the payer's counterparty account is remembered (that's where a future refund goes), and the ledger row is marked matched.

A non-CZK transfer never auto-settles, even with a perfect variable symbol and an exact amount — it is recorded as unmatched with reason foreign_currency and waits for you. Exact-amount CZK is the only thing the worker acts on by itself; everything else is a row you resolve.

The incoming payments ledger

Every incoming transfer the worker reads is recorded as a row — nothing is silently dropped anymore. Each row carries a status:

Status	Meaning
`matched`	Auto-settled a pending order (CZK, exact VS + amount).
`matched_manual`	A human matched it to an order from the ledger.
`unmatched`	Read, but not settled — see the reason.
`ignored`	Set aside by a human as not-a-ticket-payment.
`returned`	Sent back to the payer via a return-to-sender refund.

When a row is unmatched, it also carries a reason that tells you why the worker left it alone:

Reason	What happened
`missing_vs`	The transfer carried no variable symbol.
`unknown_vs`	The VS doesn't match any order.
`amount_mismatch`	VS matches an order, but the amount differs (over- or underpayment).
`foreign_currency`	Not CZK, so never auto-settled.
`order_not_pending`	The matched order is already paid, cancelled, or expired.
`already_paid`	The order was already settled by another payment.

Where to find it

Incoming payments is a tab on the Payments hub at the organization level, beside Overview, and is also available per event. It's a filterable table: reason badges on each row, full-text search, and a date from–to filter to narrow to a window.

Resolving a payment

For any row the worker couldn't settle on its own, open it and pick an action:

Match to an order — pair the payment with the right pending order and settle it (issues tickets, status becomes matched_manual). When the amount differs from the order total, a "match anyway" override lets you settle regardless.
Match + refund the difference — for an overpayment: settle the order and queue a refund of the excess back to the payer in one step.
Return to sender — refund the transfer (whole or part) back to the payer. This needs the counterparty account, so it's only available for transfers that carry one. The row becomes returned.
Ignore / Unignore — set a row aside as not a ticket payment (and bring it back if you were wrong).
Link to an already-paid order — pair a payment with an order that is already settled, for bookkeeping only. This does not re-settle the order, issue tickets, or send any email — it just records which transfer paid which order.

Return to sender and refund the difference create refunds with no order attached — they link to the bank transaction instead — and a return can be partial. They still flow through the normal refund queue → batch → Fio import pipeline and are signed in Internetbanking like any other refund.

Backfilling older statements

If you connect Fio after payments have already arrived, or you need to reach further back than the worker's live sweep, use Backfill from a date: Bookitive pulls older statements from that date forward and adds their transfers to the ledger. An optional auto-match to already-paid orders toggle will, while backfilling, link transfers to orders that were already marked paid — handy for reconciling a historical period without re-settling anything.

Behaviour and edge cases

Practical latency is about a minute — the worker ticks ~30 s but re-polls each organization ~55 s, well within Fio's rate limits.
Tokens expire — Fio tokens have a limited validity (typically 180 days). When yours stops working the integration shows an error state and matching pauses until you paste a fresh one; nothing is lost, the sweep and the ledger catch up.
Over- and underpayments never auto-settle — the amount must be exact. They land as unmatched / amount_mismatch for you to resolve (match anyway, or match + refund the difference).
Refund dates use Prague banking time — payment dates on uploaded refunds are written in the Prague banking day, which avoids Fio rejecting a batch for a "date in the past".
One Fio account per organization — the same account your payment instructions advertise.