# Middleware: the sandbox

13-Nov-2026.

The sandbox is a middleware of its own for testing a point of sale (POS) or a payment terminal
against the middleware's one schema, with no one from FUNDiMO in the room. It runs the same relay as
`live`, beside simulated terminals, an MCP server for an agent, and conformance runs whose
report is signed. You can go from nothing to a signed report from this document alone. An agent
reads the same bytes through the sandbox's MCP server as `mw://start`, and over HTTP as
`/docs/api/sandbox.md`.

Nothing in the sandbox is a record. No card is charged and no money moves, and a world lasts 30
days. A `live` middleware refuses every sandbox key and every sandbox certificate, and the sandbox
refuses every live credential.

Never send card, bank or personal data, here or on `live`: no card number, expiry, track data,
card verification value, BSB, account number, cardholder name or other detail of a person.
The middleware cannot detect one in a string you choose, and every message that passes through it is
logged, with the ids that tie it to one sale. A key, a pairing code and a header value never
reach a line.

## In short

1. Read `/llms.txt`, also served at `/`: the index of the middleware's contracts, walks, field
   catalogue and conformance scenarios, which lists this page first.
2. Read `mw://environments`, also served as `/docs/api/environments.md`: the two environments,
   the sandbox and staging, and each one's base URL. Keep the base URL a setting from your first
   line of code.
3. Take a key with `POST /sandbox/v1/keys`. It opens a world of your own (step 1).
4. Add the sandbox's MCP server with that key, then start a new session, or call it with
   `curl` in the session you are in (step 3).
5. Learn the fields: `mw://world`, the `describe_field` tool and `mw://fields`.
6. From your own code, send sales and refunds to your world's simulated terminals as a POS
   (step 4), or take them on `<tester>-yours` as a terminal (step 5), and read both sides with
   `read_log`.
7. Enrol for a certificate, run your side's conformance scenarios, and keep the signed report
   (step 6).

The commands here read the sandbox's address from `$SANDBOX`: the address this document was
served from, with no path.

```sh
# The sandbox's address: /docs/api/environments.md gives its base URL. A name under `.invalid`
# never resolves: put the real one here.
SANDBOX=https://sandbox.mw.invalid
```

Every body the sandbox takes or gives is one JSON object in UTF-8, and every refusal it gives
over HTTP has the body `{ "Error": { "Code": "...", "Message": "...", "Fields": [] } }`. The
`404` the sandbox's gate gives for a path off its routes, and its `503 ca_unavailable` when it
has no CA, add `"Next"` beside `Error`, saying what to do, as a tool's failure does. On
enrolment, the edge in front of the sandbox, where it runs behind one, may also refuse, with a
`429` of its own whose body is not an `Error` (Codes the sandbox adds). Where a table here says
the normal backoff, wait 1 second, double the wait after each failure up to 30 seconds, and add
a little randomness.

## 1. A key and a world

```sh
curl -s -X POST "$SANDBOX/sandbox/v1/keys"
```

No credential and no body are needed, and no contact detail is asked for or kept. The answer is
`201`:

```json
{
  "SandboxKey": "sbx_...",
  "TesterIdentification": "sbx-3f9a1c2e7b10",
  "ExpiryDateTime": "2026-12-10T04:12:33Z",
  "MerchantIdentification": "sbx-3f9a1c2e7b10-M1",
  "RegisterIdentification": "reg_...",
  "Terminals": { "approve": "sbx-3f9a1c2e7b10-approve", "decline": "sbx-3f9a1c2e7b10-decline", "technical": "...", "slow": "...", "late": "...", "silent": "...", "card": "...", "manual": "...", "yours": "sbx-3f9a1c2e7b10-yours" },
  "McpEndpoint": "https://sandbox.mw.invalid/mcp",
  "Enrolment": { "Role": "server", "PairingCode": "...", "Next": "Read mw://onboarding/server. This code lasts 15 minutes. POST /sandbox/v1/codes gives another." },
  "Next": "Add the MCP server with this key, then read mw://start. This key is shown once."
}
```

- `SandboxKey` is your key, a `pos` key of your world's register. It is shown this once, and
  the sandbox keeps only its digest, so a lost key is a new key and a new world. Send it as
  `Authorization: Bearer sbx_...`, and keep it out of logs and repositories, as any credential.
- `TesterIdentification` names you, and is no secret. Your world's store and terminals are
  named after it.
- `ExpiryDateTime` is when the key and the world end, 30 days on. After it the key is refused,
  and a new key is a new world.
- `MerchantIdentification` is your world's one store: every sale of yours names it.
- `RegisterIdentification` is your world's one register, which your key acts for and which
  a server's certificate names in `Mw-Register`.
- `Terminals` are your world's nine terminals (step 2).
- `Enrolment` holds a pairing code for a `pos` server on your world, good 15 minutes (step 6).
  It is a secret, as the key is.

| Status | `Error.Code` | When | What to do |
|---|---|---|---|
| `201` | | A key and a world exist | Keep the key |
| `429` | `sandbox_key_rate` | The sandbox has issued as many keys as it may this hour, counted across every caller | Try again in an hour |
| `503` | `sandbox_full` | The sandbox holds as many testers as it may | Keys free up as they expire. Try again in an hour |
| `503` | `store_unavailable` | The sandbox's store did not answer, and no key was made | Retry with the normal backoff |

**The sandbox's TLS mode.** `mw://world`'s `TlsMode` states which this sandbox runs. In
`direct`, the mode of a sandbox with a CA on your own machine, the sandbox ends TLS itself, so a
certificate it does not take can end the handshake with a TLS alert. In `forwarded`, the mode of
a sandbox behind a load balancer, the load balancer ends TLS, no handshake fails on the
certificate, and the refusal comes on the upgrade or the request instead. In `off`, plain HTTP,
no handshake carries a certificate, and a sandbox with no CA issues none (step 6). The terminal
contract's table for a refused connection reads by it (`/docs/api/terminal.md`, What a holder of
a dead certificate does).

## 2. Your world

Each terminal's id is your `TesterIdentification`, a `-`, and a suffix. All nine terminals
exist from the moment the key is issued, each is bound to your register, and your key may send
a sale to any of them and read it. Another tester's ids answer as if they did not exist.

| Terminal | Held by | On an instruction |
|---|---|---|
| `-approve` | A simulator | After 500 ms: `TransactionStatus` `ACSP`, `ResponseCode` `00`, `AdditionalInformation` `APPROVED`, `TransactionDetails.AuthorisedAmount` equal to the instruction's `TotalAmount`, and a `PaymentReference` holding three card references under `Card` |
| `-decline` | A simulator | After 500 ms: `RJCT` with `StatusReasonInformation.Reason` `AG07`, `ResponseCode` `05`, `AdditionalInformation` `DECLINED` |
| `-technical` | A simulator | After 500 ms: `RJCT` with `Reason` `AB11`: the terminal gave up and took no payment |
| `-slow` | A simulator | After 8 seconds: as `-approve` |
| `-late` | A simulator | After the sale's deadline plus 15 seconds: as `-approve`, so the sale reads `UNKN`, then `ACSP` |
| `-silent` | A simulator | Never answers. The sale reads `UNKN`, and the terminal stays claimed for the hold. It declares neither `SSAB` nor `SSMQ`, so it is sent no `StatusRequest`, and an abort of its sale is `409 terminal_cannot_abort` while the sale waits and through the hold; once the hold has ended, `409 sale_not_abortable` |
| `-card` | A simulator | After 500 ms: as `-approve`, plus four fields a terminal must never send, a card number, an expiry, track data and a cardholder name, each a fixed test value. The middleware drops them before anything is logged or answered, and a `fields_dropped` line names each |
| `-manual` | You, through the MCP server | The instruction waits for `terminal_next_instruction`, and you answer it with `terminal_send_outcome`. A `StatusRequest` and an `Abort` wait there too. Eight wait at most, of the three kinds together: a ninth is not kept, and a sale whose instruction was not kept ends `UNKN` |
| `-yours` | Your own terminal | Whatever your terminal and its own host do: the sandbox simulates no card host behind it (step 5). A sale to it while it is not connected is `409 terminal_offline`. A `LoginNeeded` from it is answered under your store's sign-in stand-in, below |

A POS reads a sale's `TransactionStatus`: `PDNG` while it waits, then `ACSP`, `RJCT` with its
`StatusReasonInformation`, or `UNKN` when no outcome came by the deadline. An `UNKN` sale may
still settle, so keep reading it. `mw://world` states the timers in force: how long a sale
waits for its outcome, how long a terminal whose sale went `UNKN` stays claimed, how long a sale
is kept, and how often the middleware sends a connected terminal a WebSocket Ping.

**Every simulated `ACSP` states the amount.** A simulator that approves sends
`TransactionDetails.AuthorisedAmount`, the instruction's `TotalAmount` as it came, as the
terminal contract asks (`/docs/api/terminal.md`, Outcome), so the sale reads it back beside
`TotalAmount`, equal to it. A bill of `50.00` with a store's 15% public holiday surcharge on it
is a sale of `57.50`, and `-approve` approves it with `"AuthorisedAmount": "57.50"`. An `RJCT`
states none, since no payment was taken. An outcome sent again, after a reconnect or as the
answer to a `StatusRequest`, states the same amount. `-manual` sends the outcome you write, so
state the amount in it yourself.

**Every simulated terminal takes refunds.** Each says so on its upgrade,
`Mw-Transaction-Types: CRDP, RFND`, and answers a refund as the table says it answers a sale,
after the same wait: `-approve` refunds it, `ACSP` with `TransactionDetails.AuthorisedAmount`
equal to the refund's own `TotalAmount` and card references of the refund's own, never the
sale's; `-decline` declines it, `RJCT` with `AG07`; `-technical` gives up, `RJCT` with
`AB11`, and no refund is made; `-silent` never answers, so the refund reads `UNKN`; `-card` adds
its four fields, which the middleware drops; and `-manual` queues the instruction, with
`TransactionType` `RFND` and the sale under `OriginalTransaction`, for
`terminal_next_instruction`. `-yours` takes a refund only once your terminal declares `RFND` on
its upgrade (step 5). `mw://world`'s `Refunds` says the same of each of your terminals.

**Every simulated terminal but `-silent` answers a `StatusRequest`.** Each says so on its
upgrade, with `SSMQ` in `Mw-Message-Functions: SSAB, SSMQ`, keeps the outcome of each sale and
refund for 24 hours, its last 64, and answers as the terminal contract says
(`/docs/api/terminal.md`, StatusRequest). Asked about a sale whose outcome it keeps, it sends
that outcome, at most once on a connection. Asked while the payment runs, it sends nothing, and the outcome once the payment
ends. Asked about a sale it never received, it sends `RJCT` with `AB11` when what it keeps
reaches back further than `SecondsSinceInstruction`, keeps that as the sale's outcome, and
answers an instruction of the sale that comes later with it; when it does not reach back that
far, it sends nothing. A second instruction while a payment runs starts nothing: it gets `RJCT`
with `AB11`, and the payment running finishes as before. `-manual` keeps a `StatusRequest` for
`terminal_next_instruction`, and you answer it with `terminal_send_outcome`, or not at all.
`-silent` declares nothing, so it is never asked. `mw://world`'s `StatusRequests` says the same
of each of your terminals.

**Every simulated terminal but `-silent` answers an `Abort`.** Each says so on its upgrade, with
`SSAB` in the same header, and answers as the terminal contract says (`/docs/api/terminal.md`,
Abort), when your POS cancels a sale or a refund with
`POST /v1/sales/{TransactionReference}/abort`. An `Abort` of a payment still waiting stops it:
the terminal sends `RJCT` with `StatusReasonInformation.Reason` `DS02`, once, and never the
outcome its wait would have ended in, so the sale reads `RJCT` with `DS02`. `-slow`'s 8 seconds
leave the time to try it, and so does `-late`'s wait, past the deadline too until the hold after
it ends, where the `DS02` replaces the `UNKN` the sale reads. `-late` answers 15 seconds after
the deadline, so with a hold shorter than that, an abort once the hold has ended is
`409 sale_not_abortable`; `mw://world` states both timers. A payment whose wait has ended is
with its host and is not stopped: the terminal sends the outcome it keeps for the sale, at most
once on a connection, and never `DS02`. For a sale it never received, it sends nothing. An
`Abort` stops only the payment it names. `-manual` keeps an `Abort` for
`terminal_next_instruction`, and you answer it with `terminal_send_outcome`: `RJCT` with `DS02`
if you stop the payment. `-silent` declares neither, so an abort of its sale is
`409 terminal_cannot_abort` while the sale still holds the terminal, as it waits and through the
hold. The middleware reads the sale's state before the terminal's connection, so once the hold
has ended the abort is `409 sale_not_abortable`. `mw://world`'s `Aborts` says the same of each
of your terminals.

**Your store holds a sign-in credential: the sandbox's stand-in.** A terminal that needs a
session at its fleet's own payment system asks the middleware for what that system takes for a
sign-in (`/docs/api/terminal.md`, Signing in). Your world's store holds, from the moment the key
is issued, the sandbox's stand-in for a fleet's credential: `Adapter` `sandbox_signed_value`,
`KeyIdentification` `sandbox-signin-1`, and the profile `Algorithm` `HMAC-SHA256`,
`ChallengeLength` 32, `ChallengeEncoding` `hex` and `SignatureEncoding` `hex`. It signs with the
sandbox's own secret, which is published here and in `mw://world` and so proves nothing to any
fleet: `mw-sandbox-signin-secret-published-not-secret`, its bytes as written (`SecretEncoding`
`text`). So your terminal can verify the `Signature` of the group it opens: the HMAC-SHA256 of
the `Challenge`'s ASCII bytes, keyed with those bytes, in lowercase hex (step 5). No fleet's
secret is ever set in the sandbox. `mw://world`'s `SignIn` states what your store holds now, each
read counted among your tool calls a minute: a
world opened before the sandbox gave each world its stand-in holds none, and a new key opens a
world that does. The simulated terminals never ask.

The simulators connect on your world's first request, which waits up to 2 seconds for them. A
world with no call for 30 minutes has them closed, and the next request connects them again,
keeping nothing: asked about a sale made before, they send nothing.

## 3. The MCP server

```sh
claude mcp add --transport http mw-sandbox "$SANDBOX/mcp" --header "Authorization: Bearer sbx_..."
```

Then start a new session: a client reads its servers when a session starts, so an agent cannot
give itself the key in the session it is in. Any MCP client on revision `2026-07-28` or
`2025-11-25` will do, over Streamable HTTP at `POST /mcp`, with the key on every request. There
is no session and no OAuth.

Or call it over plain HTTP, which needs no new session and puts the key in no client's config.
Keep the one line `Authorization: Bearer sbx_...`, with your key, in a file only you can read,
here `~/.mw-sandbox-auth`, and send each request on its own, with no `initialize` before it.
In bash or zsh, the first line makes the file yours alone, at the second paste the key and press
Enter, and the `curl` is any request, here your world:

```sh
touch ~/.mw-sandbox-auth && chmod 600 ~/.mw-sandbox-auth
(read -rs key && printf 'Authorization: Bearer %s\n' "$key" > ~/.mw-sandbox-auth)
curl -s "$SANDBOX/mcp" -H @"$HOME/.mw-sandbox-auth" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":1,"method":"resources/read","params":{"uri":"mw://world"}}'
```

The key is not shown as you paste it. `read` and `printf` are the shell's own, and `curl` reads
the header from the file, so the key is in no argument a process list shows and no line of your
shell's history.

- With no key, every resource but `mw://world` can be read, and `describe_field`,
  `validate_message` and `explain_refusal` answer. Every other tool answers `key_required`,
  with the `curl` line in `Next`.
- A key of the `sbx_` shape that is unknown or past its expiry is answered `key_not_recognised`
  by every tool that needs a key, with how to get a new one in `Next`.
- Any other credential, a token, `Basic`, or a live credential, is `401
  credential_not_for_sandbox` on every request. If it was a live credential, rotate it.

**The release the sandbox runs.** The answer to `initialize` names the release of the
middleware this sandbox runs, in `serverInfo.version` and in the first sentence of
`instructions`. `GET /v1/health` names it too, in `Version`, and needs no key. The MCP server
states its own release and reads no other: it never calls staging. Staging's own
`GET /v1/health` names the release staging runs, at the base URL `mw://environments` gives.

### Resources

| URI | Type | Key | Holds |
|---|---|---|---|
| `mw://start` | `text/markdown` | No | This document |
| `mw://environments` | `text/markdown` | No | The two environments, the sandbox and staging, and each one's base URL |
| `mw://fields` | `application/json` | No | The field catalogue: one row for each field of each message |
| `mw://fields/{Message}/{Path}` | `application/json` | No | One row, such as `mw://fields/Sale/TransactionDetails.TotalAmount`. A resource template |
| `mw://refusals` | `application/json` | No | Every code the middleware and the sandbox answer with, and `sandbox_fault`, which a log line alone carries: what it means, and what to do next |
| `mw://conformance` | `application/json` | No | The conformance scenarios, and the assertions each is judged by |
| `mw://docs/openapi.yaml` | `application/yaml` | No | The OpenAPI document |
| `mw://docs/terminal.md` | `text/markdown` | No | The terminal contract |
| `mw://docs/llms.txt` | `text/plain` | No | The index of these documents |
| `mw://docs/words.txt` | `text/plain` | No | The word list, one word a line: a device's pairing code is five of its words, and a terminal's word when linking a pair of them |
| `mw://onboarding/device` | `text/markdown` | No | Enrolling an app on a device for its certificate, and the requirements of its enrolment screen |
| `mw://onboarding/server` | `text/markdown` | No | Enrolling a server for its certificate |
| `mw://onboarding/linking` | `text/markdown` | No | Linking a register to a terminal at the counter |
| `mw://report-key` | `application/json` | No | The public key a report's signature verifies with |
| `mw://world` | `application/json` | Yes | Your world's ids, its expiry, how each terminal takes a refund and answers a `StatusRequest` and an `Abort`, the timers in force, the TLS mode, and in `SignIn` the sign-in credential your store holds, with the published secret it signs with |

A row's `Reference` says which kind of payment reference a field carries, `card`, `bank`,
`wallet` or `npp`, when it is sent and what a POS does with it, and is `null` on a field that
is no reference. A URI no resource has is JSON-RPC `-32602`, `Resource not found`.

The same files are served over plain HTTP, for a reader with no MCP client: `/llms.txt`, also
at `/`, `/docs/api/sandbox.md` (this document), `/docs/api/environments.md`,
`/docs/api/openapi.yaml`, `/docs/api/terminal.md`, `/docs/api/fields.json`,
`/docs/api/conformance.json`, `/docs/api/onboarding-device.md`, `/docs/api/onboarding-server.md`,
`/docs/api/linking.md` and `/docs/api/words.txt`.

### Tools

| Tool | Key | Arguments | What it does |
|---|---|---|---|
| `describe_field` | No | `Path`, optional `Message` | The catalogue's rows for a field |
| `validate_message` | No | `Kind`, `Sale` or `Outcome`, and `Message` | Checks a message as the relay checks it: `Accepted`, the `Refusal` with its code and fields, what would be `Dropped`, and `Next`. It keeps nothing. A `LoginNeeded` given as an `Outcome` is refused as one, and `Next` names it the frame a terminal sends once it declares `SASQ`, and says whether its key has its shape. A `LoginResponse` is refused as one too, and `Next` names it the report a terminal sends once it declares `SASQ`, and says whether such a connection takes it or refuses it `missing_field`, `invalid_result` or `invalid_reference`, naming the fields |
| `explain_refusal` | No | `Code` | What a code means, what to do next, and which side gives it |
| `send_sale` | Yes | `Message`, optional `WaitSeconds` from 0 to 25 | Sends a sale as your world's POS, and optionally waits for its result |
| `read_sale` | Yes | `TransactionReference`, optional `WaitSeconds` | Reads one of your sales, optionally waiting for it to change |
| `terminal_next_instruction` | Yes | Optional `WaitSeconds` | The next instruction, `StatusRequest` or `Abort` sent to your `-manual` terminal |
| `terminal_send_outcome` | Yes | `Outcome` | Sends an outcome frame as your `-manual` terminal, and says whether it was `Sent`, any `Refusal`, and what was `Dropped` |
| `read_log` | Yes | `Reference` | The log lines of your sales a `TransactionReference` or a `SaleReferenceIdentification` names: the newest five, each with its lines in `seq` order. A `sale_state` line names the state in the middleware's words, and `timed_out` is its word for `RJCT` with `AB11`, after ISO's name for that code, whatever stopped the payment |
| `conformance_start` | Yes | `Side`, `ProductName`, `ProductVersion`, optional `Only` | Starts a conformance run of your side (step 6) |
| `conformance_status` | Yes | `RunIdentification`, optional `WaitSeconds` | Judges the current step and reads the run, with its verdicts so far. A step not yet met stays waiting (step 6) |
| `conformance_report` | Yes | `RunIdentification` | The signed report of a finished run |

A tool's failure is a result with `isError: true` and
`{ "Error": { "Code": "...", "Message": "...", "Fields": [] }, "Next": "..." }`, the same JSON
in a text block. An argument absent, or of the wrong type, is `invalid_argument`, naming the
argument and never its value. A message `validate_message` refuses is not a failure:
`Accepted: false` is its answer. A tool's arguments are never logged.

## 4. The POS journey

For any POS: a cloud POS on its own server, or an app on a till. A POS sends nothing for a
terminal's sign-in, which the terminal journey walks, and a sale to a terminal that signs in
reads as any sale.

| # | Step | Command or tool | Its first failure says |
|---|---|---|---|
| 1 | Read what this is | `GET /llms.txt` | Nothing can fail but the network |
| 2 | Take a key | `curl -s -X POST "$SANDBOX/sandbox/v1/keys"` | `503 sandbox_full`: try again in an hour |
| 3 | Add the server, then start a new session, or call it with `curl` | `claude mcp add` or `curl`, as in step 3 | A mistyped key connects, and the first tool that needs a key answers `key_not_recognised`, with the `curl` line |
| 4 | Learn the fields | `mw://world`, `describe_field`, `mw://fields` | `describe_field` on a path no message has: `invalid_argument`, and `Next` names `mw://fields` |
| 5 | Check a first sale | `validate_message` with `Kind: "Sale"` | `Accepted: false`, the code, the fields, and `Next` |
| 6 | Send one from your own code | `POST /v1/sales` to `-approve`, then the held read, with the key as bearer | `401 sandbox_key_invalid` on a wrong key, `403 not_permitted` on an id outside your world, `400` naming the fields |
| 7 | See both sides | `read_log` | `sale_not_found`: check the reference, and that it came from this key. By a `SaleReferenceIdentification` it is also the answer for a sale whose lines have left the index, a restart among the ways: read by its `TransactionReference` to tell, which answers `log_not_held` for a sale that exists |
| 8 | Enrol, then run the scenarios | `POST /v1/enrol` with the code, then `conformance_start` with `Side: "pos"`, each step from your own code with the certificate, and `conformance_status` | The step's failing assertion, its `seq`, and what to change |
| 9 | Keep the report | `conformance_report`, saved | `run_not_finished`, naming the state |

Step 6, from your own code, with your key in place of `sbx_...`, your `TesterIdentification`
in place of `sbx-3f9a1c2e7b10`, and a new `IdempotencyKey` for each sale:

```sh
curl -s -X POST "$SANDBOX/v1/sales" \
  -H 'Authorization: Bearer sbx_...' \
  -H 'Content-Type: application/json' \
  -d '{"MerchantIdentification":"sbx-3f9a1c2e7b10-M1","POIIdentification":"sbx-3f9a1c2e7b10-approve","SaleReferenceIdentification":"INV-1001","IdempotencyKey":"7d0c6f4e-2b1a-4c3d-8e9f-0a1b2c3d4e5f","TransactionDetails":{"Currency":"AUD","TotalAmount":"12.50","SaleItem":[{"ProductDescription":"Flat white","ProductQuantity":2,"UnitPrice":"6.25","ProductAmount":"12.50"}]}}'
```

The answer is `202`, holding the sale's `TransactionReference`. Read the sale under the same
key, holding the read up to 25 seconds for a change, until it settles:

```sh
curl -s -H 'Authorization: Bearer sbx_...' \
  "$SANDBOX/v1/sales/sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a?wait_seconds=25"
```

with the `TransactionReference` from the `202` in place of the one here. If an answer is lost,
send the same sale again with the same `IdempotencyKey`: a repeat is answered `200` with the
sale as it stands, and never makes a second sale. `mw://docs/openapi.yaml`, also served as
`/docs/api/openapi.yaml`, holds every route, field and refusal.

**A refund.** Once a sale reads `ACSP`, a refund of it, the whole amount or a part, is a
`POST /v1/sales` of its own: `TransactionType` `RFND`, the sale's `TransactionReference` in
`OriginalTransaction`, the amount to refund in `TotalAmount`, your own reference for the refund,
such as a credit note number, in `SaleReferenceIdentification`, a terminal of your world, and a
new `IdempotencyKey`. The refund's terminal need not be the sale's. With the sale's
`TransactionReference` in place of the one here:

```sh
curl -s -X POST "$SANDBOX/v1/sales" \
  -H 'Authorization: Bearer sbx_...' \
  -H 'Content-Type: application/json' \
  -d '{"TransactionType":"RFND","OriginalTransaction":{"TransactionReference":"sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a"},"MerchantIdentification":"sbx-3f9a1c2e7b10-M1","POIIdentification":"sbx-3f9a1c2e7b10-approve","SaleReferenceIdentification":"CN-1001","IdempotencyKey":"0b6e2f4a-9c1d-4e7f-8a3b-5c6d7e8f9a0b","TransactionDetails":{"Currency":"AUD","TotalAmount":"6.25","SaleItem":[{"ProductDescription":"Flat white","ProductQuantity":1,"UnitPrice":"6.25","ProductAmount":"6.25"}]}}'
```

The answer is `202`, holding the refund's own `TransactionReference`, with `TransactionType`
`RFND` and the sale in `OriginalTransaction`. Read it as a sale, by its own reference, until
`ACSP`, refunded, or `RJCT`, not refunded, whatever its `Reason`. `UNKN` means no one knows yet
whether it was refunded: tell the cashier to check the terminal before refunding another way,
keep reading, and never send the refund again under a new key. The middleware keeps no total of
a sale's refunds and does not compare a refund's amount with the sale's, so your POS shows the
cashier what it has refunded already, from its own records. Two refusals leave the key unspent
and create nothing: `409 sale_not_refundable`, a sale the middleware cannot refund here, so
refund at the terminal or another way; and `409 terminal_cannot_refund`, a terminal that has not
declared refunds, so choose one that has.

Step 8: your POS enrols as your world's `pos` server. The code is the `201`'s `Enrolment`, or
`POST /sandbox/v1/codes` with `{"Role":"server"}` under your key gives a fresh one, good 15
minutes, up to 6 an hour. `mw://onboarding/server`, also served as
`/docs/api/onboarding-server.md`, walks it from the key to the certificate. A POS app on a
device enrols on a `server` code too.

A conformance run of a working POS takes under 3 minutes.

## 5. The terminal journey

For any terminal. Steps 1 to 4 of the POS journey come first, then:

| # | Step | Command or tool | Its first failure says |
|---|---|---|---|
| 5 | Connect | `$SANDBOX` with its scheme made WebSocket's, `ws://` for `http://` and `wss://` for `https://`, then `/v1/terminals/<tester>-yours/connect`, with `Authorization: Bearer sbx_...` on the upgrade | `401 certificate_required` with no credential or `sandbox_key_invalid` on a wrong key, `403 not_permitted` for an id outside your world, `426 upgrade_required` for a plain `GET` |
| 6 | Sign in | With `SASQ` in `Mw-Message-Functions` on the upgrade, send a `LoginNeeded` holding a fresh P-256 key, then open the `LoginRequest`, verify its group and report it in a `LoginResponse`, as Step 6, below, walks | `unknown_frame_type`: the upgrade did not declare `SASQ`. `recipient_key_invalid`: the fresh key, or on a certificate its signature. `sign_in_limited`: asked again within 60 seconds of an answer, or after the day's 1440 answers. On the report, `missing_field`, `invalid_result` or `invalid_reference`: a key of it, as Step 6 writes them |
| 7 | Take an instruction | `send_sale` naming `<tester>-yours`: the sandbox is the POS | `409 terminal_offline`: your terminal is not connected to `<tester>-yours` |
| 8 | Return an outcome | From your own code | A `Refusal` frame with its code. `explain_refusal` gives its meaning and `Next` |
| 9 | See both sides | `read_log` | A `fields_dropped` line names anything your terminal should not send |
| 10 | Enrol, then run the scenarios | `POST /sandbox/v1/codes` with `{"Role":"terminal"}`, `POST /v1/enrol`, then connect with the certificate. Then `conformance_start` with `Side: "terminal"` | The step's failing assertion, such as `card_field.no_drop` when your terminal sent a field the middleware does not take |
| 11 | Keep the report | `conformance_report`, saved | `run_not_finished`, naming the state |

**This sandbox's sale deadline is 30 seconds**, as `mw://world` states, where the contract's
default is 120 (`/docs/api/terminal.md`, Deadline). A sale your terminal takes longer over, a
card with PIN entry among them, reads `UNKN` at 30 seconds, and the outcome it then sends
replaces `UNKN`, as on `live`.

**Declare refunds on every upgrade.** A terminal that takes refunds says so on each upgrade,
beside its credential: `Mw-Transaction-Types: CRDP, RFND`. The middleware keeps what a
connection declared for that connection alone. Without it, `-yours` is sent sales alone, and a
refund to it is refused `409 terminal_cannot_refund`. On an `Instruction`, read
`TransactionType` first: `RFND` is a refund of `TotalAmount` against the sale
`OriginalTransaction` names, answered in an `Outcome` under the refund's own
`TransactionReference`, as a sale's is, with the refund's own references
(`/docs/api/terminal.md`, A refund). To be sent one, approve a sale on `-yours`, then send a
refund of it naming `<tester>-yours`, with `send_sale` or from your own POS code, as step 4
shows. `-manual` shows the instruction a refund sends before you write any code for it.

**No card host stands behind `-yours`.** The simulated terminals play their host's answer as
well, but the sandbox plays no card host for your terminal: your terminal and its own host
decide each outcome, on the host's test environment or a stand-in of yours. In a run, whoever
drives your terminal, a person at it or your test code standing in for one, presents the test
card, or cancels before anything reaches the host, as the step's `Instruction` asks, and your
terminal sends what it and its host did (step 6).

`mw://docs/terminal.md`, also served as `/docs/api/terminal.md`, is the terminal's
contract: the connection, the frames, the deadline and what to resend. Before writing any
terminal code, an agent can walk the same frames with `terminal_next_instruction` and
`terminal_send_outcome` on `-manual`.

Step 6, signing in, is for a terminal that needs a session at its fleet's own payment system
before it takes a payment. One that needs none declares no `SASQ`, sends no `LoginNeeded`, and
goes on to step 7, Take an instruction. `/docs/api/terminal.md`, Signing in, is the contract;
here it is walked against your store's stand-in (step 2):

1. Declare it: `SASQ` in `Mw-Message-Functions` on every upgrade, as
   `Mw-Message-Functions: SASQ, SSAB, SSMQ` for a terminal that does all three. Without it, a
   `LoginNeeded` is refused `unknown_frame_type`.
2. Make a fresh P-256 key pair in memory for this one asking. `RecipientKey.PublicKey` is its
   65 bytes, uncompressed, `0x04` then X and Y, in base64url with no padding: 87 characters. On
   a certificate's connection, sign it with the key of the certificate the connection presented,
   DER ECDSA P-256 SHA-256, over `mw-signin-recipient-v1`, a zero byte, the
   `POIIdentification`'s bytes, a zero byte and the 65 bytes of the public key, the
   `POIIdentification` here being `<tester>-yours`, and send that in `RecipientKey.Signature`,
   in base64url with no padding. On your sandbox key's connection send no `Signature`.
3. Send `{"MessageType":"LoginNeeded","RecipientKey":{"PublicKey":"...","Signature":"..."}}`,
   and read its answer before your next frame.
4. Open the `LoginRequest`'s `Sealed.Ciphertext` by RFC 9180's base mode, single-shot, with the
   fresh key's private part and `Sealed.EncapsulatedKey` as `enc`, under the suite
   `Sealed.Suite` names: `Kem` `0x0010`, DHKEM(P-256, HKDF-SHA256), `Kdf` `0x0001`,
   HKDF-SHA256, and `Aead` `0x0001`, AES-128-GCM. `info` is 58 bytes: `mw-signin-v1`, a zero
   byte, `LoginRequest`, a zero byte, and the SHA-256 of the `POIIdentification`'s bytes, a zero
   byte and the 32 bytes of the connection's credential id. On your sandbox key's connection the
   credential id is the SHA-256 of the key's whole text, `sbx_` included; on a certificate's,
   the SHA-256 of its DER. `aad` is empty: zero bytes. Check your opening against the worked
   vector first (`/docs/api/terminal.md`, The worked vector), then drop the private key.
5. Verify the opened group under the stand-in's profile: `Adapter` `sandbox_signed_value`,
   `KeyIdentification` `sandbox-signin-1`, and `Signature` the HMAC-SHA256 of the `Challenge`'s
   ASCII bytes, keyed with the bytes of the published secret
   `mw-sandbox-signin-secret-published-not-secret`, in lowercase hex, as `mw://world`'s
   `SignIn` states it. A fleet's own payment system checks what its terminals bring it; here
   your terminal checks the stand-in's itself, and still treats the group as input, not proof of
   its sender.
6. Once the opened `Signature` verifies, send one `LoginResponse` naming the group's
   `LoginReference`, before your next frame of sign-in:
   `{"MessageType":"LoginResponse","LoginReference":"lgn_...","Response":"SUCC"}`, its
   `LoginReference` the opened group's, as the group held it. Your terminal's check stands in
   here for its fleet's payment system, so a `Signature` that verifies is a `SUCC`. A report
   the middleware takes gets no frame back, so read none before your next frame
   (`/docs/api/terminal.md`, The report).

The group may also hold `AcceptorIdentification`, `UserName` and `ApplicationIdentification`,
each where the store, its attachment or its credential holds it, for your terminal to send its
fleet's payment system as that system needs them (`/docs/api/terminal.md`, The answer). Your
world's store, its attachment and its credential hold none of `AcceptorIdentification`,
`UserName` and `ApplicationIdentification`, so the group holds its four keys and its
`LoginReference` alone. This sandbox serves no route that sets them. A fleet sets them with
three operations `/docs/api/openapi.yaml` tags `operator`: the store's own number at its
fleet's payment system with `PUT /v1/merchant-stores/{StoreIdentification}/acceptor`,
`ApplicationIdentification` on the credential
`POST /v1/vendors/{VendorIdentification}/signin-credentials` sets, and `UserName` on its
attachment to the store, `PUT /v1/merchant-stores/{StoreIdentification}/signin-credential`.

Both cases hold. **A credential attached**, as your store holds one: the terminal is answered a
`LoginRequest`, signs in with what it is sent, reports it, and takes the sale. **No credential
at the store**: the ask is refused `sign_in_not_available`, a terminal signed out is normal, and
it answers the sale `RJCT` with `AB11` and asks no more on that connection. A conformance run's
`sign_in_none` step shows the second: the run ends your store's attachment for the step and
restores it after.

Step 10: `POST /sandbox/v1/codes` with `{"Role":"terminal"}` under your key answers a
`PairingCode`, five different words of `/docs/api/words.txt` joined by dots, such as
`bronze.farm.loop.prism.tempo`, and the `SerialNumber` to enrol with, `<tester>-yours`. It
re-pairs `-yours`, so its key is refused on the upgrade until the terminal enrols, within 15
minutes. Once it has, connect on the certificate at once, whatever wait the key's refusal set
(`/docs/api/onboarding-device.md`, step 7).
`mw://onboarding/device`, also served as `/docs/api/onboarding-device.md`, walks the
enrolment on an Android device. No attestation is required here, so an emulator or a debug
build can enrol. Build the screen a person enrols on to its section The enrolment screen, which
says how a person reaches that screen and what it must be. A run sees your terminal's
connection, never that screen.

A conformance run of a working terminal takes under 3 minutes.

## 6. Conformance

A run walks its side's scenarios in order, ten for a POS and twelve for a terminal, one step at
a time, and judges each from the log alone. Each step has 300 seconds. `conformance_start` and
`conformance_status` answer the current `Step`: its `Instruction`, the `Terminal` it names, which
assertions it is `Waiting` for, and a `Note` of what the sandbox can see. `conformance_status`
with `WaitSeconds` holds up to 25 seconds for a change.

`conformance_start` answers the run's `RunIdentification` and the `Step` it is on, and nothing
else: it has no `Result` and no `Done`, which only a status read gives, so a missing `Result`
here does not mean the run ended. Keep the id and read `conformance_status` with it. Starting a
POS run:

```json
{
  "RunIdentification": "run_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a",
  "Step": {
    "Scenario": "approved",
    "Number": 1,
    "Of": 10,
    "Instruction": "From your own POS code, send one sale to sbx-3f9a1c2e7b10-approve, and read it until it settles.",
    "Terminal": "sbx-3f9a1c2e7b10-approve",
    "DeadlineSeconds": 300,
    "Waiting": ["approved.one_sale", "approved.no_refusal", "approved.result_seen"],
    "Note": null
  }
}
```

`Step` is `null` only when the run ended as it started, and a status read then gives its
`Result`.

A status read judges the current step and reads the run. A step not yet met stays waiting, and
reading again changes nothing your integration has not done. Mid-run, on the first step of a
POS run:

```json
{
  "Result": "running",
  "Step": {
    "Scenario": "approved",
    "Number": 1,
    "Of": 10,
    "Instruction": "From your own POS code, send one sale to sbx-3f9a1c2e7b10-approve, and read it until it settles.",
    "Terminal": "sbx-3f9a1c2e7b10-approve",
    "DeadlineSeconds": 300,
    "Waiting": ["approved.one_sale", "approved.no_refusal", "approved.result_seen"],
    "Note": null
  },
  "Done": [],
  "Note": null
}
```

`Result` is `running` until the run ends. Then `Step` is `null`, `Result` is `green`, `red`,
`undetermined` or `partial`, and `Done` holds every step judged, in the order walked:

```json
{
  "Result": "green",
  "Step": null,
  "Done": [
    { "Scenario": "approved", "Verdict": "pass" },
    { "Scenario": "declined", "Verdict": "pass" },
    { "Scenario": "timed_out", "Verdict": "pass" },
    { "Scenario": "unknown", "Verdict": "pass" },
    { "Scenario": "card_field", "Verdict": "pass" },
    { "Scenario": "duplicate_key", "Verdict": "pass" },
    { "Scenario": "resend", "Verdict": "pass" },
    { "Scenario": "restart", "Verdict": "pass" },
    { "Scenario": "lost_instruction", "Verdict": "not_applicable" },
    { "Scenario": "cancel", "Verdict": "not_applicable" }
  ],
  "Note": null
}
```

The top-level `Note` is `null` but on a run that could not be judged in full, where it says how
many lines were lost or evicted and to run it again. On a terminal run whose terminal did not
declare `SASQ`, it says once, green or not, that sign-in was not tested (below). It also speaks when the sandbox loses its
race in `lost_instruction`: your terminal connected again before the sandbox's sale was made,
so the instruction reached it. The sandbox tries once more when that sale has settled, or at
the latest when the sale's deadline and the hold after it have passed, the times `mw://world`
states. If it loses again, the step is `undetermined`, never `fail`, because this is not your
terminal's fault, and the `Note` says to run it again. It speaks too when the sandbox's own abort
in `cancel` was not admitted and the step did not pass: it says what the abort was answered, or
that no answer came, and whether an `Abort` went, as the step's `Note` does from the moment the
abort is answered. When such an abort sent your terminal no `Abort`, which is not your
terminal's fault, the step is `undetermined`, never `fail`, as a race lost twice leaves one, with
no `step.no_traffic`. The one exception is an outcome your terminal sent for the sale before the
abort reached the middleware: your terminal did not hold the payment, so `cancel.outcome` fails
on it, and `cancel.declared` is `undetermined` unless your terminal connected during the step,
since nothing else in the step shows what it declared. When the abort left no line in your log,
as an abort refused before the middleware could check the sandbox's key leaves none, nothing in
the log places an outcome before the abort: `cancel.outcome` does not fail on one, and a step
that has not failed by its deadline ends `undetermined`. The `Note` says nothing of a
`409 terminal_cannot_abort`: it means your terminal did not declare `SSAB`, and `cancel.declared`
fails on it. On `Side: terminal`, a step your terminal has met stays open 3 seconds before the
next opens, with `Waiting` empty and the step's `Note` saying so: a second outcome of that sale
on the same connection in that time fails the step on `<scenario>.one_outcome`. A read with
`WaitSeconds` made while a step holds answers as the hold ends, and a terminal run takes 3
seconds longer for each step your terminal meets.

| Scenario | POS side, its terminal | Terminal side, what you do, on your terminal's own host |
|---|---|---|
| `approved` | `-approve` | Approve it |
| `declined` | `-decline` | Decline it: `RJCT` with `AG07` |
| `timed_out` | `-technical` | Give up with no payment: `RJCT` with `AB11` |
| `unknown` | `-late`: read `UNKN`, then keep reading to `ACSP` | Send nothing until `Note` says `Now send it.`, then approve |
| `card_field` | `-card`: see the drop | Send the fullest outcome your terminal builds, with every reference it has |
| `duplicate_key` | `-approve`: repeat a create with the same key, then with another body | Not run: the middleware never sends a terminal one key twice |
| `resend` | `-approve`: the answer to your first create is lost on purpose, after the sale is made. Where a front end stands before the sandbox, a load balancer ending TLS, it comes as a `503` whose body is text and not an `Error`; on a sandbox you reach with nothing in front, the connection closes with no status. Treat either as an unknown outcome, and send the same body with the same `IdempotencyKey` | Hold the outcome 2 seconds, so the connection drops first, then reconnect and send it |
| `restart` | `-slow`: a 5 second outage from your first read | Reconnect with the contract's backoff, and send the outcome |
| `lost_instruction` | Not run: nothing changes for a POS, which reads the terminal's answer as any late outcome | The sandbox takes your terminal's place for the sale, so its instruction never reaches you: reconnect with `Mw-Message-Functions: SSMQ` declared, and when a `StatusRequest` asks about the sale, answer `RJCT` with `AB11` |
| `cancel` | Not run: a POS need not offer a cancel, and one that does reads the abort's answers in `/docs/api/openapi.yaml` | With `SSAB` declared in `Mw-Message-Functions`, take the sale and hold its payment, no card presented: 3 seconds after the instruction the sandbox cancels the sale, as a POS does with `POST /v1/sales/{TransactionReference}/abort`, and your terminal is sent an `Abort`. Stop the payment and answer `RJCT` with `DS02` |
| `sign_in` | Not run: nothing changes for a POS, since the terminal signs in by itself | With `SASQ` declared in `Mw-Message-Functions`, start your terminal holding no session at its fleet's payment system, asleep, its screen off and its app not in front. The sale's instruction wakes it: send one `LoginNeeded`, open the `LoginRequest` and verify its group as step 5 walks, report the outcome of your sign-in at your fleet's system with `LoginResponse`, naming the answer's `LoginReference`, then answer the sale |
| `sign_in_none` | Not run: nothing changes for a POS, since the terminal signs in by itself | With `SASQ` declared and no session held, take the sale: the sandbox ends your store's sign-in attachment for the step and restores it after, so your `LoginNeeded` is refused `sign_in_not_available`. Ask no more on that connection, and answer the sale `RJCT` with `AB11` |

On the terminal side no card host is simulated: your terminal and its own host decide each
outcome. Whoever drives the terminal presents the test card, cancels, or holds the payment with
no card presented, as the step's `Instruction` asks, and your terminal sends what it and its host
did (step 5).

`sign_in` and `sign_in_none` apply only to a terminal that declares `SASQ`. Each reads what your
terminal's connection declared as the step opened, or, if it had not connected, its first connect
in the step, when no line of the step was lost. Where that did not name `SASQ`, the step is
`not_applicable`. Read as the step opened, that is at once: no sale is sent and nothing waits for
its deadline. Read from a first connect in the step, it is at the next reading, the step's sale
already sent. Either way a run that passes every other step still reads `green`.
Its row in the report holds `NotTested`, and the ended run's `Note` says the same, once: "Sign-in
was not tested: your terminal did not declare SASQ in Mw-Message-Functions. A terminal that needs
the middleware to sign it in must declare SASQ on every upgrade and run again." A sign-in step that
runs first gives your store its stand-in again if it holds none. A terminal that
declared `SASQ` and reconnects during the step without it fails `sign_in.login_declared`. A run
sees frames alone, never your terminal's screen.

`mw://conformance`, also served as `/docs/api/conformance.json`, holds every assertion and
what to change when one fails.

- **A run needs a certificate.** A sandbox key cannot start one: `conformance_start` answers
  `certificate_required` until your side has enrolled (step 4 or 5). So a run needs a sandbox
  that issues certificates: one with a CA, in TLS mode `direct` or `forwarded`, as one behind a
  load balancer is. A sandbox started with TLS `off` and no CA, as a local one may be, issues
  none: its `POST /v1/enrol` answers `503 ca_unavailable` with a `Next` saying so, and no run
  can start on it. Everything else here works on a key alone.
- **A run judges your world's log.** Your world's log holds at most its newest 2,000 lines,
  and at most 1 MiB of them, the oldest out first, and a step reads only the lines that came
  after it opened. Older lines leaving it change nothing. A step whose own lines left it before they
  were judged, because your key wrote more than that during the step, is `undetermined`, and
  the ended run's `Note` says how many lines and to run it again with less traffic. A new key
  is a new, empty log, and so is 30 minutes with no request of yours.
- **Only your own integration counts.** A line counts only when it bears your certificate, so
  traffic from this MCP server, `send_sale` among it, does not.
- **A terminal run's sales are yours.** On `Side: terminal` the sandbox sends each step's sale as
  your POS, and it counts as one of your sales a minute, beside your own and `send_sale`'s. While
  the minute is full, `Note` says so and the sale waits. A resend of it is not counted again.
- **Verdicts.** Each assertion is `pass`, `fail` or `undetermined`, and one the log cannot
  decide, because lines were lost or a word is unknown, is `undetermined`, never `pass`. A run
  is `green` only when it is complete, every scenario is `pass` or `not_applicable`, no
  line was lost while it ran, and none of a step's own lines was evicted.

`conformance_report` gives `{ "Report": "<JSON text>", "Signature": "<base64>",
"KeyIdentification": "<16 hex>" }`. The signature is Ed25519 over the exact bytes of `Report`,
in standard base64 with padding, and `mw://report-key` holds the public key it verifies
with, and its `KeyIdentification`, the key's first 8 bytes in lowercase hex. `PublicKey` is the
raw 32-byte Ed25519 key in standard base64, not a PEM or DER structure. To check a report kept
in `report.json` with OpenSSL 3 or later, put the key in a PEM file first: its DER is the fixed
12 bytes `302a300506032b6570032100` and then the key, and since 12 bytes are exactly 16 base64
characters, `MCowBQYDK2VwAyEA`, the PEM is that text and then `PublicKey`:

```sh
KEY='...'  # mw://report-key's PublicKey
printf -- '-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA%s\n-----END PUBLIC KEY-----\n' "$KEY" > report-key.pem
jq -j .Report report.json > report.txt
jq -r .Signature report.json | base64 -d > report.sig
openssl pkeyutl -verify -pubin -inkey report-key.pem -rawin -in report.txt -sigfile report.sig
```

It prints `Signature Verified Successfully` and exits 0 when the report is the sandbox's, and
exits 1 when one byte of `Report` differs. `jq -j` writes the text of `Report` with no newline
after it, so the bytes are the ones signed. As with any check of a signature, a pass says the
report is the sandbox's, not that the run was green: read `Result` in `Report` for that.

A report shows what a holder of your certificate sent. It does not identify a product or a
vendor, `ProductName` and `ProductVersion` are as declared, the far side was simulated, a
restart was simulated for you alone, and no card, host or acquirer took part: it is not a card
scheme's certification.

`ContractVersion` in a report is the family of paths the run's routes were under: `v1`, as in
`/v1/sales` on the relay and `/sandbox/v1/keys` on the sandbox. It is not the release. It moves
only when the middleware serves a new family of paths, so many releases may share one
`ContractVersion`. To compare two reports, compare their `SandboxVersion`.

`SandboxVersion` is the release of the middleware that ran the run. A run lives in one process
of the sandbox and is lost when the sandbox restarts, so one run never spans two releases.

`ReportVersion` counts the report's own shape, not the release.

### What a green run does not check

A green run proves your integration did what each step asked, once. It cannot see what your
code would do on a day no step stages, so each rule below binds you and no scenario checks it.
Each is stated where the link says.

For a POS:

- **`UNKN` tells the cashier to check the terminal before another tender**, as soon as the
  sale reads `UNKN`, while it keeps reading: not only once reading gives up. `UNKN` means a
  payment may have been taken (`/docs/api/openapi.yaml`, `Sale`'s `TransactionStatus`).
- **A `404 sale_not_found` on an id the middleware gave you reads as unknown**, not as no sale
  (`/docs/api/openapi.yaml`, `readSale`'s `404`).
- **`409 idempotency_conflict` after a lost answer reads as unknown**: a sale may exist under
  that key, so the cashier checks the terminal before another tender
  (`/docs/api/openapi.yaml`, `createSale`'s `409`).
- **A field you do not know is ignored, and a `TransactionStatus` you do not know reads as
  `UNKN`** (`/docs/api/openapi.yaml`, `Sale`).
- **No card, bank or personal data in any string you choose**, an item's description or an
  invoice reference among them (the top of this page, and `/llms.txt`).
- **The people who use your POS are your responsibility.** The middleware takes it that a user of
  your POS was authenticated to make each sale and refund, and judges nothing about that user
  (`/docs/api/openapi.yaml`, `info`).

For a terminal:

- **Store the `TransactionReference` before taking the card, and the `Outcome` before sending
  it**, somewhere a crash or a reboot does not lose (`/docs/api/terminal.md`, In short, and
  Resending is safe).
- **One payment at a time.** An `Instruction` that arrives while a payment is open is not
  started and not queued: it is answered `RJCT` with `AB11`, and the payment that is open
  finishes as before (`/docs/api/terminal.md`, One payment at a time).
- **A repeated `Instruction` never charges twice**, after a restart of the terminal as well
  as within one run of its code (`/docs/api/terminal.md`, The paths, step by step).
- **`RJCT` with `AB11` only when no payment was taken**: decided from what the terminal and
  its host did, never from what a step is called (`/docs/api/terminal.md`, Which
  `TransactionStatus` to send).
- **A frame the middleware refused is kept aside and not sent again** but as the Refusal section
  says, across reconnects as well (`/docs/api/terminal.md`, Refusal).
- **An `Abort` stops only a payment not yet with its host.** A green run does not prove the rest
  of the contract's abort: that a terminal whose payment is already with its host carries on and
  sends the host's outcome, never `DS02`; that an `Abort` for a reference whose payment ended is
  answered with that outcome, unless the terminal already sent it on this connection; that one
  for a reference the terminal holds no record of is answered with nothing; that it sends `DS02`
  only in answer to an `Abort`, and `AB11` for a cancel at the terminal; and that an `Abort` never
  stops a payment for another reference (`/docs/api/terminal.md`, Abort). `cancel` stages one
  case, a payment held with no card presented, and judges that the terminal declared `SSAB` and
  answered the `Abort` with `RJCT` and `DS02`, once.
- **A sale's outcome goes at most once on each connection**, and again only after a
  reconnect, never on a timer (`/docs/api/terminal.md`, Resending is safe). A run fails a
  repeat it sees inside a step's 3-second hold, `<scenario>.one_outcome`, and does not see a
  slower one. The log names no connection, so a run cuts your terminal's lines into
  connections at each connect and disconnect: a repeat that straddles one of those lines as
  one connection replaces another goes unseen, and an outcome your old connection was still
  sending as your new one connected can read as a repeat on the new one, which ends a run
  `red` that should not be, never `green`, and can pass when run again. Under a lost or evicted
  line a repeat reads `undetermined`.
- **A person reaches your app's enrolment screen from the app's own menu or settings**, with
  the device alone and again after the first enrolment, and the screen meets the rest of its
  requirements (`/docs/api/onboarding-device.md`, The enrolment screen). A run sees the connection your
  terminal holds on its certificate, never the screen it was enrolled on.
- **Check the sandbox's server certificate**, and the middleware's in `live`, against your trust
  store, as any HTTPS or WSS client does. Never turn the check off: a terminal that does would
  send its outcomes to whoever answers at the address. A local sandbox may present a
  certificate under a root of its own, which you add to your trust store; one behind a load
  balancer presents a public certificate. Whoever started a local sandbox has its root
  certificate and gives it to you; the sandbox does not serve it, since a root fetched over the
  connection it vouches for proves nothing.

## 7. Codes the sandbox adds

The middleware's own codes are in the OpenAPI document and the terminal contract. The table holds the
codes only the sandbox answers, and five of the middleware's as the sandbox gives them:
`sale_not_found` from a tool, `not_found` from its gate, `terminal_offline`, whose `Next` here
names your own terminal, `code_not_valid`, whose `Next` here names the route that gives a
fresh code, and `ca_unavailable`, which a sandbox with no CA answers itself. `mw://refusals` holds every code of both, with its meaning and `Next`.
One row has no code: the `429` an edge in front of the sandbox gives on `POST /v1/enrol`, whose
body is the edge's own.

| Code | Where | When | What to do |
|---|---|---|---|
| `key_required` | A tool | No `Authorization` came | Get a key: `curl -X POST "$SANDBOX/sandbox/v1/keys"` |
| `key_not_recognised` | A tool | A key of the `sbx_` shape, unknown or expired. The two read the same | Get a new key. A key lasts until its `ExpiryDateTime` |
| `credential_not_for_sandbox` | `/mcp`, `401` | A bearer not beginning `sbx_`, or another scheme | The sandbox takes only keys beginning `sbx_`. If it was a live credential, rotate it |
| `invalid_argument` | A tool | An argument is absent, or not of its type, range or words | Fix each argument `Fields` names. A field's `Path` and its `Message` are as `mw://fields` lists them |
| `sale_not_found` | A tool | No such sale in your world. From `read_log` by a `SaleReferenceIdentification`, also a sale whose lines have left the index: only a `TransactionReference` is asked of the middleware | On an id the middleware gave you, treat the sale as unknown: tell the cashier to check the terminal before another tender |
| `answer_lost` | `send_sale`, `read_sale` or `read_log` | The tool's request reached the relay and no answer it could read came back, so whether it took effect is not known | Call `send_sale` again with the same sale and the same `IdempotencyKey`, never a new one: if the sale was made, the relay answers `200` with it as it stands and makes no second one, and if not, the key is unspent. A read changes nothing: call `read_sale` or `read_log` again as it was |
| `log_not_held` | A tool | By `TransactionReference`: the sale exists, and its lines have left the sandbox's index. By a `SaleReferenceIdentification` the same sale reads `sale_not_found` | Lines are kept until 30 minutes pass with no request of yours, within the bounds of the sandbox's index, which a restart empties. Read a sale's log soon after it settles |
| `no_instruction` | A tool | Nothing reached `-manual` in `WaitSeconds` | Send a sale to your `-manual` terminal |
| `run_not_found` | A tool | No such run in your world, or one lost to a restart of the sandbox | Runs live in memory, as the index does: start again. Every line `read_log` gives carries `boot_id`, one for each start of the sandbox, and its `seq` begins again at a restart. A `boot_id` other than the one on the lines you read while the run went says the sandbox restarted, and your code did not lose the run |
| `run_in_progress` | A tool | A run of yours is running | Finish it, or wait for its deadline |
| `run_not_finished` | A tool | `conformance_report` before the run ended | Read `conformance_status` |
| `sandbox_rate` | A tool, or `429` with this code at `/v1/*`, `/sandbox/v1/codes` and `/sandbox/v1/app-identities`. A `429` at `POST /v1/enrol` whose body is not an `Error` is the edge's: the next row | Past a bound of yours: sales or tool calls a minute, requests in flight, codes or app identities an hour | Wait a minute, and retry with the same `IdempotencyKey`. If an earlier answer was lost, the sale may exist |
| None: the body is the edge's own, not an `Error` | `429` at `POST /v1/enrol` | Sent by the edge in front of the sandbox, where it runs behind one, never by the sandbox itself: more enrolments came from this address in a minute than the edge allows. The code was not read, and no attempt is counted against it | Wait a minute, then try again with the same body. Do not read the body as an `Error` |
| `sandbox_busy` | A tool, or `503` | As many worlds are connected as the sandbox holds | Try again shortly |
| `sandbox_restarting` | `503` at `/v1/*` | A conformance step's outage, for you alone | Retry with the normal backoff: a restart keeps the sale |
| `sandbox_key_rate` | `429` at the key route | Past the keys the sandbox issues an hour | Try again in an hour |
| `sandbox_full` | `503` at the key route | The sandbox holds as many testers as it may | Try again in an hour |
| `not_found` | `404` at any path the sandbox does not serve | A path off the sandbox's routes, `/v1` routes of the middleware's that a sandbox does not serve among them | Start at `GET /llms.txt` or `POST /mcp`, and take a key with `POST /sandbox/v1/keys`. Under `/v1` only sales, the connect route, health, enrolment, a holder's own certificate, the link routes and `/v1/register/terminals` are served here. The gate's answer for a path off its routes says so in `Next`; a `404` the relay gives on a path the gate passes, such as one deep under `/v1/links/`, has no `Next` |
| `terminal_offline` | `409` at `/v1/sales` and at `/v1/sales/{TransactionReference}/abort`, and `send_sale` | Nothing holds the terminal the sale names, or its queue of frames is full | If it is `<tester>-yours`, your terminal is not connected to it: connect it, as the terminal contract says. A simulated terminal connects again by itself. Then send the same sale with the same `IdempotencyKey`: it is unspent. On an abort, the terminal was sent nothing: abort again once it is connected, or have the cashier cancel at the terminal |
| `code_not_valid` | `403` at `/v1/enrol` | The pairing code is wrong, unknown, expired or spent, or the serial is not the one it names | Check the code and send again inside its 15 minutes. Past that, `POST /sandbox/v1/codes` with `{"Role":"server"}` or `{"Role":"terminal"}` under your key gives a fresh one. In live, ask whoever listed the principal |
| `ca_unavailable` | `503` at `/v1/enrol` | This sandbox has no CA, so it issues no certificate, or its CA could not sign this once | With no CA, the answer's `Next` says so: no certificate is issued and no conformance run can start here, and a sandbox in `direct` or `forwarded` with a CA issues one. Otherwise retry on the normal backoff with the same code and the same key: the code is not spent |

## What the sandbox never does

- **Show one tester's data to another.** Every tool and route reads your world alone, from your
  key or your certificate, and another tester's sale answers as one that never existed.
- **Accept a live credential.** Its store holds no live row, a live certificate is refused, and
  a non-`sbx_` bearer at `/mcp` is `401`.
- **Keep a card or personal field.** The allow-list drops what a terminal must not send before
  any line is written, and no tool keeps what it checks.
- **Let a tool change a credential.** Keys and codes come from the plain routes under
  `/sandbox/v1/` alone, never from a tool.
