Status & Session
These endpoints establish that the SDC is ready and unlock signing for the session.
GET /api/v3/attention
Lightweight health check. Returns whether the SDC is available and which card readers are connected.
GET /api/v3/attention
200 OK
{
"available": true,
"readers": ["ACS ACR39U ICC Reader 0"]
}GET /api/v3/status
The E-SDC status document. Read this before signing.
| Field | Meaning |
|---|---|
isPinRequired | true if a PIN must be verified before signing. |
auditRequired | true when the Secure Element has reached its limit and an audit is due. |
sdcDateTime | The SDC's current date/time (use this as the fiscal clock). |
protocolVersion | POS-to-SDC protocol version. |
secureElementVersion | SE applet version. |
make, model, softwareVersion, hardwareVersion, deviceSerialNumber | Device identity. |
uid | Secure Element UID. |
currentTaxRates | The tax-rate group currently in force (the labels/categories you may use on items). |
allTaxRates | All known tax-rate groups (including future-dated). |
gsc | Status codes, e.g. 1300 (SE not present), 2400 (SE limit reached). |
POST /api/v3/pin
Verifies the operator PIN on the Secure Element and caches it in memory for the session. The request body is the PIN as plain text (digits) — not JSON. The response is a 4-digit text response code.
POST /api/v3/pin
Content-Type: text/plain
3456
200 OK
0100| Response | Meaning |
|---|---|
0100 | PIN verified — signing is unlocked. |
2100 | PIN incorrect / no usable PIN supplied. |
2110 | Blocked, or only one attempt remains (the SDC refuses the last attempt to avoid locking the card). |
1300 | Secure Element not present / unreadable. |
Card safety: the SDC will not spend the final PIN attempt. If only one try remains it returns 2110 rather than risk permanently locking the card — resolve the correct PIN before retrying.
Secure Element helpers (read-only)
Useful for status displays and pre-flight checks; none of these sign or consume a PIN attempt.
| Endpoint | Returns |
|---|---|
GET /api/v3/se/identity | Seller identity from the SE certificate: uid, tin, businessName, locationName, address, state, validFrom, validTo, TaxCore URL. |
GET /api/v3/se/amount-status | saleRefund (amount accumulated) and limit. |
GET /api/v3/se/pin-tries | triesLeft. |
GET /api/v3/se/safety | A safety snapshot: PIN tries left, whether blocked, amount used/limit/remaining, used fraction. |
GET /api/v3/se/version | SE applet version. |