Pre-check POS JWT freshness without making a money call
Pre-checks a POS terminal JWT’s validity and remaining TTL without performing any business operation. A terminal calls this to decide whether to refresh before starting a checkout, avoiding a mid-transaction 401. The JWT is presented via the PosTerminalJWT bearer scheme. For a valid token the endpoint returns { valid, expires_at, remaining_seconds, scope }; for an expired, malformed, or wrong-audience token it returns { valid: false, reason }. A malformed or invalid token still returns HTTP 200 with valid: false: this is a check, not an auth gate, so a bad token is a data answer, never a 401. Read-only and rate-limited to deter token-probing. Does not extend the token.
Authorizations
POS terminal JWT minted by /auth/token; carries integrationId + terminal/cashier claims (server-trusted).
Response
Validity verdict. A valid OR an invalid/expired token both return 200 (this is a freshness check, not an auth gate).
The standard response envelope that every enveloped endpoint serializes through. ok is a boolean discriminator: when ok is true, the typed result is carried in data; when ok is false, a typed error object is returned instead. The meta object is uniform across the entire API surface.
The uniform response metadata block returned on every response. data_completeness_score is computed per call and reports the completeness of the returned data. decision_trace_id is present on responses that carry decision or insight output and can be used to correlate the response with its reasoning. capabilities is an additive, response-level array of hints advertising features the caller may use, and may be extended over time without notice.
Result of a non-mutating POS JWT freshness check. A valid AND an invalid token both return HTTP 200 with this body.
The typed error object returned with every non-2xx response. code is a string enum (for example WALLET_PROGRAM_AMBIGUOUS, CREDENTIAL_TYPE_UNSUPPORTED, INSUFFICIENT_FUNDS, IDEMPOTENCY_KEY_REUSED, CURRENCY_NOT_SUPPORTED), never a bare HTTP status number. Inspect code for programmatic branching, not the HTTP status. Some codes echo the valid set in details so clients can present or reconcile the accepted values: for example CREDENTIAL_TYPE_UNSUPPORTED lists the supported credential types, CURRENCY_NOT_SUPPORTED lists the supported ISO-4217 currencies, and WALLET_PROGRAM_AMBIGUOUS lists the candidate wallet_program_id values that matched the request.