Invoices, Buyers and Fiscal Documents
Source implementation ready; release and issuer acceptance pending. This is not a production release announcement. The exact device/app/issuer capability must be verified and enabled. Otherwise the request is rejected with 422 physical_pos.fiscal_document.unsupported before charging. An older server cannot silently discard the new fields and initiate a legacy payment.
Your restaurant/café integration continues to send its own sale application identity and actual version. Fiscal data does not replace that source identity.
Collecting an existing invoice
Add this block to the ordinary SALE request:
{
"salesData": {
"invoices": [
{
"invoiceNumber": "ABC2026000000001",
"issuedOn": "2026-11-06",
"amountMinor": "12500"
}
]
}
}The amount is the allocation collected by this payment, not the invoice face value. No new invoice is issued. Up to 20 unique references; positive canonical minor-unit strings must sum to the payment amountMinor, in the payment currency. Optional invoiceUuid is a UUID; optional issuedOn is a valid calendar date. Further partial collections may be separate payments. An invoice number is not an Idempotency-Key. These references do not prove invoice existence or outstanding receivables.
Requesting a new document
{
"salesData": {
"fiscal": { "documentType": "E_ARCHIVE" }
}
}Only an itemized TRY SALE with a verified issuer capability can request a new fiscal document. Types are E_ARCHIVE, E_INVOICE, INFO_SLIP, OKC_RECEIPT, E_SMM; each capability narrows this set. Do not combine an existing invoice list and a new document request. The issuer source comes from the capability; callers cannot submit an issued status or the newly issued number as proof of success.
When required, add salesData.buyer:
| Field | Meaning |
|---|---|
partyType | INDIVIDUAL, BUSINESS, PUBLIC |
identityType, identityNumber | TCKN (11 digits), VKN (10 digits), FOREIGN (3–32 uppercase letters/digits/hyphens); not taxpayer or identity verification |
givenName, familyName | Separate required person names for an individual or TCKN holder; never guessed by splitting a trade name |
legalName | Required legal name for other recipients; optional trade name for a person |
taxOffice, email | Optional tax office and format-validated email |
address | Required countryCode, city, line; optional district, postalCode |
E_INVOICE/E_SMM and amounts above the capability's buyer threshold require recipient data. An unknown threshold safely requires a buyer; statutory limits are not guessed in code. Address country is not an identity-type proxy. Sector profiles, exemptions, subscriber/institution references and jewellery fields are not enabled in this limited contract. Unknown fields and arbitrary vendor JSON are rejected. Buyer details are encrypted at rest and excluded from command logs and webhooks.
Reading fiscal status
GET /api/v1/physical-pos/payments/{paymentId}/sales-data requires physical_pos:view or physical_pos:payments. salesData is null for an older payment without this data. Otherwise it contains:
invoices: existing invoice collection references.buyerProvided: presence only; no recipient identity or address.fiscalRequested: whether a new document was requested.documents[]: document ID, attempt, source/type, separatefiscalStatus, reason, issued number/UUID/date/fiscal-receipt references,historySeq,rowVersion,actionRequired,outcomeConflict,alarms.
The panel shows the same record on transaction details. PENDING, ISSUED, FAILED, UNKNOWN, NOT_REQUIRED and related review/cancellation states describe the document, not the bank payment. An issued claim needs verified device evidence and sufficient document identity; request acceptance is not issuance.
Failure, duplicates and reversals
- Same idempotency key and fiscal data refers to the same payment. Changing an invoice, buyer or requested document produces a 409 mismatch.
- An approved payment can have a failed or uncertain document. Do not charge again because of a document issue. No automatic charge retry, void or cloud switch occurs.
- A document can become UNKNOWN after its result deadline. UNKNOWN and NOT_FOUND do not prove non-issuance and never authorize reissuance.
- Conflicting evidence preserves the previous final outcome and raises a review flag and fiscal webhook. Buyer data and raw vendor responses are excluded.
- The common read-only query coordinator is implemented in source; real vendor queries, reissuance and fiscal cancellation execution remain disabled. An
action_requirednotification indicates review;availableActions: []does not promise an executable action. - Reversals of active, issued or uncertain fiscal documents are rejected until a certified fiscal reversal codec exists. Existing financial reversal rules remain available for definitive FAILED/NOT_REQUIRED documents without conflicts.
originalPaymentIdis not an invoice number.
Support status and remaining scope
Device content and rollout compatibility
Protocol package 2.4.0 uses fiscal content v2 for new requests with a registered source snapshot; historical v1 content is preserved. Signed START remains command v6 and B-19 remains document v2. Package, command and content versions are separate concepts. A source snapshot does not prove issuance or attest the executed SDK version.
Do not send v2 content to an older v1-only reader. Keep salesContextProtocol:6 disabled for an exact device/app until its new reader and vendor acceptance are verified. This is a rollout requirement, not an announcement of production support.
Common query and recovery — source delivery
When the bank outcome is known, Android can query only the document without querying or charging the bank. Evidence refers to the original START/documentId and first issuance attempt. UNKNOWN in the SDK port maps to INDETERMINATE on the wire and UNKNOWN in stored fiscal status. NOT_FOUND and timeout do not prove non-issuance. Late uncertainty cannot regress a final document; conflicting final evidence requires review.
Document query rights are persisted before SDK access: the first 6 reads are at least 60 seconds apart; subsequent reads continue at least one hour apart. Restart does not reset pacing, and the sixth read does not permanently end automatic checks. A document query cancellation preserves a bank observation already obtained. No real SDK is connected to this coordinator yet; this is not automatic fiscal resolution/reissuance or a production support announcement.
Device protocol package 2.5.0 adds POST /api/device/v1/physical-pos/recovery-state, signed with device identity. It is not a merchant API. A fresh challenge and exact device/payment/command/hash/epoch binding are required; a missing endpoint or failed authorization never unlocks the terminal. K-43 can release only the old reservation while bank/document outcomes remain UNKNOWN. Conflicting evidence is reviewed per transaction, without an automatic permanent device ban. K-43 release and automatic queries can continue for a flagged transaction. Release backend/gateway first; command v6, content v2 and B-19 v2 are unchanged.
Automatic checks and recovery of missing outcomes are the primary path. Manual review is a last resort when the provider cannot supply definitive evidence. Repeated NFC notifications or repeated delivery of the same payment outcome remain one payment. Distinct provider transaction identifiers are never merged just because amount/time look similar. Identity/signature, sandbox and storage-integrity gates remain mandatory. Package 2.5.1 corrects client behavior; the recovery-state HTTP contract is unchanged since 2.5.0.