> ## Documentation Index > Fetch the complete documentation index at: https://docs-pos.solya.app/llms.txt > Use this file to discover all available pages before exploring further. # Run the card-terminal round-trip self-test > Commands the resolved payment provider through two probes, in this order: authorize -> capture, then authorize -> void. It exists so a human on the till's peripherals screen can prove the terminal is wired; an agent should reach for it ONLY on an explicit operator request to test the terminal, never to 'check' anything. Use `getPaymentTerminalConfig` for that. WHY `avoid`: (1) it talks to the provider with the deployment's REAL credentials, so with a live Adyen POI it engages the physical reader mid-shift and asks a person to present a card; (2) the capture probe SETTLES its authorization and the round-trip never reverses it, so a green run leaves a captured payment of `amountCents` behind — only the second, void probe is released; (3) nothing in this route asserts test mode. The 'sandbox' guarantee is entirely environmental (an `sk_test_` Stripe key, the Adyen TEST host); the code does not check it. NOT IDEMPOTENT: every call issues two FRESH authorizations. There is no read-back endpoint for the result, so a call that times out must NOT be retried blindly — the authorizations may already have been taken. Ask the operator to inspect the provider dashboard instead. Body: send at least `{}`; `amountCents` (integer minor units, default 100 = 1.00, max 1 000 000) and `currency` (3-letter ISO 4217, default `EUR`) override the probe amount — keep it small, it is money. Unknown keys are rejected. Always inspect `ok` (true only when all four steps passed); `steps[].detail` is free-form engineering text, never a machine field. The `enabled` toggle does NOT gate this route: a terminal an operator switched off still runs the round-trip. ERROR-VOCABULARY TRAP (solya-pos#955): the 422 this route returns when the selected provider has no credentials carries `error.code: "PSP_NOT_CONFIGURED"`, which is NOT a member of the kernel `ResultCode` enum the shared `ErrorResponse` component documents. Match that string literally rather than expecting a documented code. ## OpenAPI ````yaml /openapi.json post /v1/payment-terminal/test openapi: 3.0.3 info: title: Solya POS API version: 1.0.0 description: >- The Solya POS backend HTTP surface. Every documented operation is agent-ready: it carries an `operationId`, an agent-facing `description`, the `pos.*` scopes it enforces (`x-required-permissions`) and an `x-agent-tier`. Success responses return the payload as raw JSON; failures return the `ErrorResponse` envelope (`{ error: { code, message, statusCode } }`). servers: - url: / description: The backend, relative to its deployed origin. security: [] paths: /v1/payment-terminal/test: post: tags: - Devices summary: Run the card-terminal round-trip self-test description: >- Commands the resolved payment provider through two probes, in this order: authorize -> capture, then authorize -> void. It exists so a human on the till's peripherals screen can prove the terminal is wired; an agent should reach for it ONLY on an explicit operator request to test the terminal, never to 'check' anything. Use `getPaymentTerminalConfig` for that. WHY `avoid`: (1) it talks to the provider with the deployment's REAL credentials, so with a live Adyen POI it engages the physical reader mid-shift and asks a person to present a card; (2) the capture probe SETTLES its authorization and the round-trip never reverses it, so a green run leaves a captured payment of `amountCents` behind — only the second, void probe is released; (3) nothing in this route asserts test mode. The 'sandbox' guarantee is entirely environmental (an `sk_test_` Stripe key, the Adyen TEST host); the code does not check it. NOT IDEMPOTENT: every call issues two FRESH authorizations. There is no read-back endpoint for the result, so a call that times out must NOT be retried blindly — the authorizations may already have been taken. Ask the operator to inspect the provider dashboard instead. Body: send at least `{}`; `amountCents` (integer minor units, default 100 = 1.00, max 1 000 000) and `currency` (3-letter ISO 4217, default `EUR`) override the probe amount — keep it small, it is money. Unknown keys are rejected. Always inspect `ok` (true only when all four steps passed); `steps[].detail` is free-form engineering text, never a machine field. The `enabled` toggle does NOT gate this route: a terminal an operator switched off still runs the round-trip. ERROR-VOCABULARY TRAP (solya-pos#955): the 422 this route returns when the selected provider has no credentials carries `error.code: "PSP_NOT_CONFIGURED"`, which is NOT a member of the kernel `ResultCode` enum the shared `ErrorResponse` component documents. Match that string literally rather than expecting a documented code. operationId: runPaymentTerminalTest requestBody: required: true content: application/json: schema: type: object properties: amountCents: type: integer minimum: 0 exclusiveMinimum: true maximum: 1000000 currency: type: string minLength: 3 maxLength: 3 additionalProperties: false example: amountCents: 250 currency: EUR responses: '200': description: >- The round-trip report. A 200 means the probes RAN, not that they passed — read `ok`. content: application/json: schema: type: object properties: provider: type: string enum: - mock - adyen - stripe ok: type: boolean steps: type: array items: type: object properties: operation: type: string enum: - authorize - capture - void ok: type: boolean detail: type: string required: - operation - ok - detail additionalProperties: false required: - provider - ok - steps additionalProperties: false description: >- The round-trip report. A 200 means the probes RAN, not that they passed — read `ok`. example: provider: stripe ok: true steps: - operation: authorize ok: true detail: approved pi_3Qk1 - operation: capture ok: true detail: captured ch_3Qk1 - operation: authorize ok: true detail: approved pi_3Qk2 - operation: void ok: true detail: voided pi_3Qk2 '400': description: >- The request failed schema validation; `error.fieldErrors` lists the fields. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '401': description: No valid credential was presented — send a bearer token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: The actor is authenticated but lacks the required `pos.*` scope. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: The request is well-formed but violates a domain rule. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: An unexpected server error — safe to retry idempotent requests. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: ValidationErrorResponse: type: object required: - error additionalProperties: false description: >- A `VALIDATION_FAILED` envelope carrying the offending fields in `fieldErrors`. properties: error: type: object required: - code - message - statusCode additionalProperties: false properties: code: type: string enum: - VALIDATION_FAILED message: type: string statusCode: type: integer fieldErrors: type: array description: >- One entry per rejected field: the field path and why it was rejected. items: type: object required: - field - message additionalProperties: false properties: field: type: string description: Dot-path of the offending field. message: type: string description: Why the field was rejected. ErrorResponse: type: object required: - error additionalProperties: false description: The uniform failure envelope every non-2xx response returns. properties: error: type: object required: - code - message - statusCode additionalProperties: false properties: code: type: string enum: - VALIDATION_FAILED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - BUSINESS_RULE_VIOLATION - INTERNAL_ERROR description: >- Machine-readable kernel `ResultCode` — branch on this, not on `message`. message: type: string description: >- Human-readable explanation. Safe to surface; never leaks server internals. statusCode: type: integer description: >- The HTTP status, mirrored into the body so a client need not read headers. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- `Authorization: Bearer `. Accepts EITHER a Keycloak access token (scopes-in-token) OR an opaque POS session token; both resolve to the same `pos.*` scope vocabulary the route guards enforce. ````