Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

  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.

# 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."
}
  • 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.
StatusError.CodeWhenWhat to do
201A key and a world existKeep the key
429sandbox_key_rateThe sandbox has issued as many keys as it may this hour, counted across every callerTry again in an hour
503sandbox_fullThe sandbox holds as many testers as it mayKeys free up as they expire. Try again in an hour
503store_unavailableThe sandbox’s store did not answer, and no key was madeRetry 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.

TerminalHeld byOn an instruction
-approveA simulatorAfter 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
-declineA simulatorAfter 500 ms: RJCT with StatusReasonInformation.Reason AG07, ResponseCode 05, AdditionalInformation DECLINED
-technicalA simulatorAfter 500 ms: RJCT with Reason AB11: the terminal gave up and took no payment
-slowA simulatorAfter 8 seconds: as -approve
-lateA simulatorAfter the sale’s deadline plus 15 seconds: as -approve, so the sale reads UNKN, then ACSP
-silentA simulatorNever 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
-cardA simulatorAfter 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
-manualYou, through the MCP serverThe 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
-yoursYour own terminalWhatever 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://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

URITypeKeyHolds
mw://starttext/markdownNoThis document
mw://environmentstext/markdownNoThe two environments, the sandbox and staging, and each one’s base URL
mw://fieldsapplication/jsonNoThe field catalogue: one row for each field of each message
mw://fields/{Message}/{Path}application/jsonNoOne row, such as mw://fields/Sale/TransactionDetails.TotalAmount. A resource template
mw://refusalsapplication/jsonNoEvery 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://conformanceapplication/jsonNoThe conformance scenarios, and the assertions each is judged by
mw://docs/openapi.yamlapplication/yamlNoThe OpenAPI document
mw://docs/terminal.mdtext/markdownNoThe terminal contract
mw://docs/llms.txttext/plainNoThe index of these documents
mw://docs/words.txttext/plainNoThe 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/devicetext/markdownNoEnrolling an app on a device for its certificate, and the requirements of its enrolment screen
mw://onboarding/servertext/markdownNoEnrolling a server for its certificate
mw://onboarding/linkingtext/markdownNoLinking a register to a terminal at the counter
mw://report-keyapplication/jsonNoThe public key a report’s signature verifies with
mw://worldapplication/jsonYesYour 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

ToolKeyArgumentsWhat it does
describe_fieldNoPath, optional MessageThe catalogue’s rows for a field
validate_messageNoKind, Sale or Outcome, and MessageChecks 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_refusalNoCodeWhat a code means, what to do next, and which side gives it
send_saleYesMessage, optional WaitSeconds from 0 to 25Sends a sale as your world’s POS, and optionally waits for its result
read_saleYesTransactionReference, optional WaitSecondsReads one of your sales, optionally waiting for it to change
terminal_next_instructionYesOptional WaitSecondsThe next instruction, StatusRequest or Abort sent to your -manual terminal
terminal_send_outcomeYesOutcomeSends an outcome frame as your -manual terminal, and says whether it was Sent, any Refusal, and what was Dropped
read_logYesReferenceThe 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_startYesSide, ProductName, ProductVersion, optional OnlyStarts a conformance run of your side (step 6)
conformance_statusYesRunIdentification, optional WaitSecondsJudges the current step and reads the run, with its verdicts so far. A step not yet met stays waiting (step 6)
conformance_reportYesRunIdentificationThe 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.

#StepCommand or toolIts first failure says
1Read what this isGET /llms.txtNothing can fail but the network
2Take a keycurl -s -X POST "$SANDBOX/sandbox/v1/keys"503 sandbox_full: try again in an hour
3Add the server, then start a new session, or call it with curlclaude mcp add or curl, as in step 3A mistyped key connects, and the first tool that needs a key answers key_not_recognised, with the curl line
4Learn the fieldsmw://world, describe_field, mw://fieldsdescribe_field on a path no message has: invalid_argument, and Next names mw://fields
5Check a first salevalidate_message with Kind: "Sale"Accepted: false, the code, the fields, and Next
6Send one from your own codePOST /v1/sales to -approve, then the held read, with the key as bearer401 sandbox_key_invalid on a wrong key, 403 not_permitted on an id outside your world, 400 naming the fields
7See both sidesread_logsale_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
8Enrol, then run the scenariosPOST /v1/enrol with the code, then conformance_start with Side: "pos", each step from your own code with the certificate, and conformance_statusThe step’s failing assertion, its seq, and what to change
9Keep the reportconformance_report, savedrun_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:

#StepCommand or toolIts first failure says
5Connect$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 upgrade401 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
6Sign inWith 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, walksunknown_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
7Take an instructionsend_sale naming <tester>-yours: the sandbox is the POS409 terminal_offline: your terminal is not connected to <tester>-yours
8Return an outcomeFrom your own codeA Refusal frame with its code. explain_refusal gives its meaning and Next
9See both sidesread_logA fields_dropped line names anything your terminal should not send
10Enrol, then run the scenariosPOST /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
11Keep the reportconformance_report, savedrun_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:

{
  "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.

ScenarioPOS side, its terminalTerminal side, what you do, on your terminal’s own host
approved-approveApprove it
declined-declineDecline it: RJCT with AG07
timed_out-technicalGive up with no payment: RJCT with AB11
unknown-late: read UNKN, then keep reading to ACSPSend nothing until Note says Now send it., then approve
card_field-card: see the dropSend the fullest outcome your terminal builds, with every reference it has
duplicate_key-approve: repeat a create with the same key, then with another bodyNot 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 IdempotencyKeyHold the outcome 2 seconds, so the connection drops first, then reconnect and send it
restart-slow: a 5 second outage from your first readReconnect with the contract’s backoff, and send the outcome
lost_instructionNot run: nothing changes for a POS, which reads the terminal’s answer as any late outcomeThe 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
cancelNot run: a POS need not offer a cancel, and one that does reads the abort’s answers in /docs/api/openapi.yamlWith 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_inNot run: nothing changes for a POS, since the terminal signs in by itselfWith 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_noneNot run: nothing changes for a POS, since the terminal signs in by itselfWith 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:

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.

CodeWhereWhenWhat to do
key_requiredA toolNo Authorization cameGet a key: curl -X POST "$SANDBOX/sandbox/v1/keys"
key_not_recognisedA toolA key of the sbx_ shape, unknown or expired. The two read the sameGet a new key. A key lasts until its ExpiryDateTime
credential_not_for_sandbox/mcp, 401A bearer not beginning sbx_, or another schemeThe sandbox takes only keys beginning sbx_. If it was a live credential, rotate it
invalid_argumentA toolAn argument is absent, or not of its type, range or wordsFix each argument Fields names. A field’s Path and its Message are as mw://fields lists them
sale_not_foundA toolNo 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 middlewareOn an id the middleware gave you, treat the sale as unknown: tell the cashier to check the terminal before another tender
answer_lostsend_sale, read_sale or read_logThe tool’s request reached the relay and no answer it could read came back, so whether it took effect is not knownCall 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_heldA toolBy TransactionReference: the sale exists, and its lines have left the sandbox’s index. By a SaleReferenceIdentification the same sale reads sale_not_foundLines 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_instructionA toolNothing reached -manual in WaitSecondsSend a sale to your -manual terminal
run_not_foundA toolNo such run in your world, or one lost to a restart of the sandboxRuns 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_progressA toolA run of yours is runningFinish it, or wait for its deadline
run_not_finishedA toolconformance_report before the run endedRead conformance_status
sandbox_rateA 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 rowPast a bound of yours: sales or tool calls a minute, requests in flight, codes or app identities an hourWait 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 Error429 at POST /v1/enrolSent 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 itWait a minute, then try again with the same body. Do not read the body as an Error
sandbox_busyA tool, or 503As many worlds are connected as the sandbox holdsTry again shortly
sandbox_restarting503 at /v1/*A conformance step’s outage, for you aloneRetry with the normal backoff: a restart keeps the sale
sandbox_key_rate429 at the key routePast the keys the sandbox issues an hourTry again in an hour
sandbox_full503 at the key routeThe sandbox holds as many testers as it mayTry again in an hour
not_found404 at any path the sandbox does not serveA path off the sandbox’s routes, /v1 routes of the middleware’s that a sandbox does not serve among themStart 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_offline409 at /v1/sales and at /v1/sales/{TransactionReference}/abort, and send_saleNothing holds the terminal the sale names, or its queue of frames is fullIf 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_valid403 at /v1/enrolThe pairing code is wrong, unknown, expired or spent, or the serial is not the one it namesCheck 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_unavailable503 at /v1/enrolThis sandbox has no CA, so it issues no certificate, or its CA could not sign this onceWith 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.