Release v0.3.1, 21-Nov-2026 · all releases
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
- Read
/llms.txt, also served at/: the index of the middleware’s contracts, walks, field catalogue and conformance scenarios, which lists this page first. - 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. - Take a key with
POST /sandbox/v1/keys. It opens a world of your own (step 1). - Add the sandbox’s MCP server with that key, then start a new session, or call it with
curlin the session you are in (step 3). - Learn the fields:
mw://world, thedescribe_fieldtool andmw://fields. - From your own code, send sales and refunds to your world’s simulated terminals as a POS
(step 4), or take them on
<tester>-yoursas a terminal (step 5), and read both sides withread_log. - 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.
# 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
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:
{
"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."
}
SandboxKeyis your key, aposkey 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 asAuthorization: Bearer sbx_..., and keep it out of logs and repositories, as any credential.TesterIdentificationnames you, and is no secret. Your world’s store and terminals are named after it.ExpiryDateTimeis when the key and the world end, 30 days on. After it the key is refused, and a new key is a new world.MerchantIdentificationis your world’s one store: every sale of yours names it.RegisterIdentificationis your world’s one register, which your key acts for and which a server’s certificate names inMw-Register.Terminalsare your world’s nine terminals (step 2).Enrolmentholds a pairing code for aposserver 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
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:
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://worldcan be read, anddescribe_field,validate_messageandexplain_refusalanswer. Every other tool answerskey_required, with thecurlline inNext. - A key of the
sbx_shape that is unknown or past its expiry is answeredkey_not_recognisedby every tool that needs a key, with how to get a new one inNext. - Any other credential, a token,
Basic, or a live credential, is401 credential_not_for_sandboxon 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:
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:
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:
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):
- Declare it:
SASQinMw-Message-Functionson every upgrade, asMw-Message-Functions: SASQ, SSAB, SSMQfor a terminal that does all three. Without it, aLoginNeededis refusedunknown_frame_type. - Make a fresh P-256 key pair in memory for this one asking.
RecipientKey.PublicKeyis its 65 bytes, uncompressed,0x04then 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, overmw-signin-recipient-v1, a zero byte, thePOIIdentification’s bytes, a zero byte and the 65 bytes of the public key, thePOIIdentificationhere being<tester>-yours, and send that inRecipientKey.Signature, in base64url with no padding. On your sandbox key’s connection send noSignature. - Send
{"MessageType":"LoginNeeded","RecipientKey":{"PublicKey":"...","Signature":"..."}}, and read its answer before your next frame. - Open the
LoginRequest’sSealed.Ciphertextby RFC 9180’s base mode, single-shot, with the fresh key’s private part andSealed.EncapsulatedKeyasenc, under the suiteSealed.Suitenames:Kem0x0010, DHKEM(P-256, HKDF-SHA256),Kdf0x0001, HKDF-SHA256, andAead0x0001, AES-128-GCM.infois 58 bytes:mw-signin-v1, a zero byte,LoginRequest, a zero byte, and the SHA-256 of thePOIIdentification’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.aadis empty: zero bytes. Check your opening against the worked vector first (/docs/api/terminal.md, The worked vector), then drop the private key. - Verify the opened group under the stand-in’s profile:
Adaptersandbox_signed_value,KeyIdentificationsandbox-signin-1, andSignaturethe HMAC-SHA256 of theChallenge’s ASCII bytes, keyed with the bytes of the published secretmw-sandbox-signin-secret-published-not-secret, in lowercase hex, asmw://world’sSignInstates 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. - Once the opened
Signatureverifies, send oneLoginResponsenaming the group’sLoginReference, before your next frame of sign-in:{"MessageType":"LoginResponse","LoginReference":"lgn_...","Response":"SUCC"}, itsLoginReferencethe opened group’s, as the group held it. Your terminal’s check stands in here for its fleet’s payment system, so aSignaturethat verifies is aSUCC. 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:
{
"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:
{
"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:
{
"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_startanswerscertificate_requireduntil your side has enrolled (step 4 or 5). So a run needs a sandbox that issues certificates: one with a CA, in TLS modedirectorforwarded, as one behind a load balancer is. A sandbox started with TLSoffand no CA, as a local one may be, issues none: itsPOST /v1/enrolanswers503 ca_unavailablewith aNextsaying 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’sNotesays 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_saleamong it, does not. - A terminal run’s sales are yours. On
Side: terminalthe sandbox sends each step’s sale as your POS, and it counts as one of your sales a minute, beside your own andsend_sale’s. While the minute is full,Notesays so and the sale waits. A resend of it is not counted again. - Verdicts. Each assertion is
pass,failorundetermined, and one the log cannot decide, because lines were lost or a word is unknown, isundetermined, neverpass. A run isgreenonly when it is complete, every scenario ispassornot_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:
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:
UNKNtells the cashier to check the terminal before another tender, as soon as the sale readsUNKN, while it keeps reading: not only once reading gives up.UNKNmeans a payment may have been taken (/docs/api/openapi.yaml,Sale’sTransactionStatus).- A
404 sale_not_foundon an id the middleware gave you reads as unknown, not as no sale (/docs/api/openapi.yaml,readSale’s404). 409 idempotency_conflictafter 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’s409).- A field you do not know is ignored, and a
TransactionStatusyou do not know reads asUNKN(/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
TransactionReferencebefore taking the card, and theOutcomebefore 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
Instructionthat arrives while a payment is open is not started and not queued: it is answeredRJCTwithAB11, and the payment that is open finishes as before (/docs/api/terminal.md, One payment at a time). - A repeated
Instructionnever 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). RJCTwithAB11only 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, WhichTransactionStatusto 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
Abortstops 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, neverDS02; that anAbortfor 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 sendsDS02only in answer to anAbort, andAB11for a cancel at the terminal; and that anAbortnever stops a payment for another reference (/docs/api/terminal.md, Abort).cancelstages one case, a payment held with no card presented, and judges that the terminal declaredSSABand answered theAbortwithRJCTandDS02, 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 runredthat should not be, nevergreen, and can pass when run again. Under a lost or evicted line a repeat readsundetermined. - 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/mcpis401. - 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.