Skip to content

Receipts ​

Where the gateway can issue the fiscal receipt, it does. For every other way money arrives — cash to a courier, a bank transfer, an invoice, a manager confirming an offline payment, a carrier settling a cash-on-delivery amount — there is a cash-register driver with a document queue and an idempotency key.

Two registers ship in the box:

KeyRegisterWhere
atolATOL Online v4Russia, 54‑ФЗ
checkboxCheckboxUkraine, ПРРО

A site can register another through fiscal_drivers in core/App/config/pbshop.php; the layer is an interface and a registry, and a new register is a map of fields over Support\Receipt.

One register per shop, chosen by pbshop_fiscal_driver. Empty means no fiscalisation at all, and that is the default: a shop outside Russia and Ukraine should not be issuing receipts, and a register enabled by default would be firing documents into nowhere on every payment.

The register's settings are MODX system settings, not method properties

Unlike payment drivers. The reason is not taste: a shop has one contract with one fiscal operator for the whole legal entity, and one register across all payment methods. Put the registration number and the address of settlement on the method and they would have to be duplicated into every method row — and once they drift apart, you get receipts from two different sellers.

What ATOL needs ​

All of these are pbshop_fiscal_* system settings:

SettingWhat it is
driveratol
login, passwordthe ATOL cabinet credentials
groupthe group code from the cabinet
innthe seller's registration number
addressthe address of settlement — for an online shop, the site address. Empty falls back to the site URL, but name it: it is printed on the receipt
snothe tax system: osn, usn_income, usn_income_outcome, envd, esn, patent. Default usn_income
emailthe seller's email, printed on the receipt
vat_codethe default rate, 1 meaning no VAT. A product's own rate is a constructor field and wins over this
currencythe currency receipts are issued in — RUB by default
test_modethe register's test circuit

What Checkbox (ПРРО) needs ​

SettingWhat it is
drivercheckbox
login, passwordthe cashier's credentials, not the cabinet's
pinsign in by PIN instead of a login; needs licence_key
licence_keythe register's licence key. Required either way — without it the shift cannot be opened, and without an open shift ПРРО accepts no receipt
cashier_nameprinted on the receipt; empty and the register fills it in
departamentthe department, a string. Spelled with the register's own typo, because otherwise it does not see the field
shift_hoursafter how many hours the register closes the shift itself. Default 23
tax_codesa JSON map from pbShop's rate numbering to Checkbox's
smssend the receipt by SMS. Off: that delivery is a paid extra at Checkbox, and without it the register would refuse every receipt
currencymust be UAH — the core will not reach the register otherwise

Two defaults here are not what you would guess

shift_hours must stay under 24. ПРРО rejects a fiscal action in a shift that has been open longer, and nobody in the shop is going to close it — a manager does not know shifts exist.

tax_codes is empty, which means the rate is not sent at all and the register applies whatever is configured against the item. That is correct for a sole trader on a single tax without VAT, and it is the only safe default in general: ПРРО rate codes are an organisation's own setting in its cabinet, not a list from the law, and they have nothing in common with pbShop's numbering.

Also: pbshop_fiscal_currency still defaults to RUB. It did not move to UAH when ПРРО arrived, on purpose — that would have silently switched already installed rouble shops to "we issue no receipts". Set it explicitly.

Never twice ​

A second fiscal document for the same payment is a conversation with the tax office, not a log line, and a surplus one cannot be withdrawn. So the protection is in three layers doing three different jobs.

The core will not create a second receipt row for one payment — a unique index on the document number — and will not let two processes call the register for one row at the same time.

The document number is computed, not stored: a UUID v5 derived from the external id. That matters precisely when things crash. If the process dies between sending and saving, the next attempt arrives with the same number, the register answers "already exists", and the shop re-reads that document instead of issuing a second one. With a random number the register would treat the retry as a new document.

"Already exists" is an answer, not an error. The register does not hand the document back with it, so it has to be re-read. Treating that reply as a failure would mean counting an issued receipt as unissued.

The case that looks like a paradox

If the register rejects the document on the merits, that number is burnt: there is no fiscal receipt against it and never will be, but the register will not accept it again either.

So after a refusal the next number is taken — and it is taken only after the register has confirmed the refusal by a read. Without that condition, "take a new number" would mean "issue a second receipt"; with it, it means "retry a document the register does not have".

And where the gateway fiscalises for itself, the register is skipped entirely: the driver is asked whether it does, and if so no second receipt is created.

The queue and its states ​

Receipts live in pb_shop_receipts, one row per document, and the row is never deleted — a fiscal document exists at the tax office independently of this database.

new  →  pending  →  done
                 ↘  failed
  • new — not sent yet, or the send failed in a way worth retrying;
  • pending — the register accepted it; the fiscal numbers have not arrived;
  • done — printed; the numbers are in the row;
  • failed — refused on the merits. Not retried.

The row holds the operation (sale or refund), the amount and currency, the attempt count, the raw exchange, and the numbers the tax office cares about: the fiscal document number, the fiscal attribute, the fiscal storage number, the shift number and the time of issue.

Managers see all of this in its own grid, Receipts, and a receipt or a refusal is also written into the order's history feed.

Picking up what never finished ​

A register's notification can simply not arrive — the site was down, the address changed, the register did not retry. The only reliable way to learn the outcome is to ask.

php
$modx->services->get('pbshop')->fiscal()->poll();

This belongs on the site's cron, every few minutes; a receipt is not printed instantly. It takes the unfinished rows whose attempts are not exhausted and which have not been touched too recently, sends or completes each, and returns how many it handled. See Subscriptions and cron — this is one of the three jobs whose silence is counted as critical.

Checkbox is asynchronous at both ends: a shift answers 202 and opens seconds later, a receipt answers 201 as "created". The driver does not sit and poll inside the payment callback — that would be seconds spent inside someone else's HTTP request. "Not ready yet" comes back as retryable and the cron finishes it. The payment is already recognised by then: a buyer must not lose money because a register was slow.

Neither driver trusts the notification body, even when it is signed. Checkbox signs its notifications and the signature is checked — but the outcome is still read from the API, because a signature proves who wrote the message, not that the document is in that state.

What is not here ​

  • A receipt for a partial refund. Deliberate: a refund receipt has to name the goods returned, and a partial refund has no composition — only a sum.
  • Registers other than these two. The layer is ready and a driver is a map of fields; Бизнес.ру, Модуль and Комтет on demand.

Neither register has issued a real receipt

There is no live register on our side, as there is no live gateway: you cannot sign a contract with a fiscal operator in order to test, and the ATOL sandbox comes with one.

The difference worth knowing: ATOL's address, time format, payment-form codes and rate list were written from a working ATOL client, not from a retelling of the documentation. Checkbox was written from its OpenAPI specification and wiki, and Checkbox has no sandbox at all — you test with a test cashier against the live address. Plan a first receipt of your own accordingly.

Next ​

pbShop — a shop component for PageBlocks