Integrating XPOS ESDC with Your POS

This page covers installing and integrating an E-SDC device or software at a sales point: physically setting up the Secure Element reader, installing XPOS ESDC, and connecting your POS, ERP, or accounting software against its local API. If you're a day-to-day operator (cashier or shopkeeper) rather than the person setting this up, the rest of this category — starting with Getting Started — covers normal daily use instead.

Installation

What you need at the sales point:

• A Windows 10/11 PC (64-bit) to run XPOS ESDC on — this is the machine your POS software will talk to.
• A PC/SC-compliant smart-card reader, connected to that PC.
• The FRCS-issued Secure Element (SDC) card and its PIN for this taxpayer/Device.

1. Install XPOS ESDC

Follow Getting Started in this category to install the app on the PC with the reader attached, and verify the Secure Element PIN. Do this before wiring up your POS integration — everything below assumes XPOS ESDC is already installed, running, and showing "Online" with the card unlocked.

2. Confirm the reader is detected

If the Status screen doesn't show your card once inserted:

• Open Windows Services (services.msc) and confirm Smart Card (SCardSvr) is running. If it isn't, start it and set its Startup type to Automatic (or Automatic, Delayed Start) so it comes up on every reboot without needing a reader replugged first.
• Check Device Manager under "Smart card readers" — the reader should be listed with no warning icon. If it's missing or shows an error, Windows doesn't have a driver for it; most standard USB CCID readers work with Windows' built-in driver, but some vendor-specific readers need a driver installed manually first.
• Re-open XPOS ESDC after fixing either of the above.

3. Connect your POS

XPOS ESDC exposes a local API on the same PC (http://127.0.0.1:8888 by default) for your POS, ERP or accounting software to call. If your POS runs on this same PC, it can reach that address directly out of the box. See Software Integration below for the API details your POS needs to actually sign invoices.

Software Integration

The full API reference

Every endpoint, request/response schema, and example payload is published as an interactive, always-current OpenAPI reference.

Open the API reference →

Its "Try it out" button sends real requests straight from your own browser to your own computer's http://localhost:8888 — it only works while XPOS ESDC is installed and running locally, with a card inserted. This page (and Defy) never sees your requests or your data. The same reference is also built into the app itself: Settings → About → API reference (Swagger).

Architecture

XPOS ESDC runs a small local web server on each Device, listening on port 8888 by default. Your POS talks to it over plain HTTP on that same machine — XPOS ESDC handles the smart card, the mutual-TLS handshake with TaxCore, and the actual fiscal signing; your POS never touches the card directly.

• Base URL: http://127.0.0.1:8888 (or whatever port Settings → Connection shows, if 8888 was already taken on that machine).
• No authentication on the API itself — being reachable at all is the security boundary. By default it's loopback-only (only software on the same PC can reach it). If your POS runs on a different machine from the card reader, see Settings Reference → Connection for how to widen that, and the risk of doing so.
• V3 is current. A legacy V2-shaped surface also exists for older XPOS-compatible integrations, but it shuts down 2026-12-31. Build new integrations against v3; migrate existing ones before that date.

Typical flow

1. GET /api/v3/status — poll this for card presence, PIN state, and TaxCore connectivity.
2. POST /api/v3/pin — verify the operator's PIN once. The result is cached in memory for the session, so you don't need to send it again before every sign.
3. POST /api/v3/invoices — sign a sale. Fails with a PIN-required response if nothing's cached yet.

Full request/response shapes, every field, and ready-to-run examples for all of this are in the API reference — this page intentionally doesn't repeat them.

PIN attempts and elevation

If your integration (or an operator) sends several wrong PINs in a row, XPOS ESDC requires a Windows administrator to approve the next attempt, shown right there on the Device — this works identically whether the wrong PIN came from your API call or from XPOS ESDC's own window. The very last attempt on a card can only ever be made from XPOS ESDC's own UI, never via the API, as a deliberate safeguard against a fully automated integration accidentally destroying a card. Design your error handling to surface a clear "see the Device" message on that response rather than silently retrying.

Concurrency

Multiple Devices can share a single card/reader (common where several POS terminals sit behind one Secure Element). XPOS ESDC serializes all card access internally — concurrent requests are queued and processed one at a time, safely, rather than colliding. You don't need to implement your own locking; just send requests as they naturally occur and expect slightly higher latency under heavy concurrent load rather than errors.

Errors

Responses use the standard FRCS/SDC response-code convention (a 4-digit code, e.g. "0100" success, "1300" no Secure Element present, "2100" wrong PIN, "1500" PIN required). The exact set of codes and what each one means is documented per-endpoint in the API reference.

Authentication and identity

XPOS ESDC authenticates to TaxCore.API using the Secure Element's own certificate (stored in its PKI applet) for the initial mutual-TLS handshake, then uses the resulting access token for every subsequent TaxCore.API call. Your business's TIN, UID, company name, store name, address, and district are all read directly from that certificate, with nothing manually configured or hardcoded per Device.

Audit integrity

Every signed invoice is encrypted (AES-256-CBC, with the key itself RSA-encrypted using the Secure Element's TaxCore public key) and queued as an audit package before the sign response is returned, both happen inside the same local transaction, so a successful sign response can never exist without its audit package already durably queued. XPOS ESDC exports this data to TaxCore in two ways, Local Audit (offline, via removable media) and Remote Audit (automatic, online), using the identical package format either way. For Local Audit specifically, exported files follow the Technical Instructions' naming convention exactly: audit packages are named {UID}-{UID}-{Ordinal_Number}.json (the ordinal restarts at 1 per secure element UID folder), and the audit-proof file is named {UID}.arp, both written into a folder named after the UID that created them. XPOS ESDC never overwrites or erases a queued audit package until TaxCore has confirmed it with a Proof-of-Audit (POA); a rejected or stale POA is retried against the same data rather than discarded. Once a POA is received, XPOS ESDC applies it to the Secure Element promptly. The card's own acceptance is what determines whether the audit actually completed, the app never assumes success on its own. Switching Secure Elements mid-audit does not interrupt this process; XPOS ESDC detects the card change and resumes cleanly rather than getting stuck. Remote audit runs continuously in the background whenever the Device is online: not-yet-sent packages are flushed on every tick, independent of the Proof-of-Audit cycle, and a fresh Audit Start is initiated at most every 30 minutes normally (tightening to every 10 minutes as the Secure Element approaches its unaudited-amount limit) — both comfortably above the required 5-minute minimum between two Audit Starts.

Reliability under load

Registering sales and submitting audit data happen independently. Audit runs as a background process, not on the same path as signing a sale, so it does not add latency to your POS. Commands received from TaxCore.API are processed in the order they arrive, and a failure in one command is reported without blocking the rest of the batch.

Tax calculation

Invoices are taxed using the tax labels your POS sends per item, matched against the tax rate groups XPOS ESDC keeps synced from TaxCore (see Settings Reference, Tax rates). Each rate group carries the exact date and time it takes effect, so a tax change applies precisely when it should rather than retroactively or only after a restart. All amounts are rounded to 4 decimal places using round-half-away-from-zero, equivalent to round-half-up for the non-negative amounts every real invoice produces.

Storage

XPOS ESDC's local data (settings, invoice history, and the audit queue) is stored on disk, not held only in memory. It survives an app restart or a power loss intact.

Prohibited functions acknowledgment

XPOS ESDC introduces no manufacturer-specific error codes: every error code returned falls within the standard FRCS/SDC response-code taxonomy, nothing has been added outside it. An invoice using a tax label that is not part of the currently active tax rate group is rejected with a validation error rather than processed. No setting, command, or configuration option alters the TaxCore.API communication protocol itself (its request/response shapes, authentication flow, and command handling are fixed in the app, not user-editable). The Secure Element PIN is held only in memory for the current session and is never written to disk; restarting XPOS ESDC or swapping cards always requires it to be re-entered (see Getting Started, Verifying your PIN).