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

What changed

v0.3.1 (21-Nov-2026)

This is the first release of what v0.3.0 holds: v0.3.0 was tagged and deployed nowhere. A release tag’s build now reads the tag it was started for, and no longer refuses before it builds.

v0.3.0 (21-Nov-2026)

A POS may now send CashierIdentification, the user of the POS who made a sale or a refund, and the middleware sends it on to the terminal. A hosted middleware may now close a terminal’s connection when a POS’s sale reaches another of its instances, and the terminal reconnects as after any close. The OpenAPI document’s descriptions are now short and its info.version stays 1.0.0: apart from the new field and the edge’s 411, no route, body, field, bound, enum or refusal changed.

Breaking

  • Terminal: A terminal conformance run’s sale now carries CashierIdentification (19-Nov-2026). A terminal that refuses an Instruction holding a key it does not know cannot pass the run. Ignore the key, or use it. A report that was green is not green again until the terminal does this.

Added

  • POS, Terminal: CashierIdentification, the user of the POS who made a sale or a refund (19-Nov-2026). A POS may send it, as an identifier it chooses and never the person’s name. The middleware checks its shape and sends it on in the Instruction. A terminal shows, prints or passes it on, or ignores it, and one that checks frames against the published field list takes the new list.

Changed

  • POS: A POS’s rules stay in the OpenAPI document, each said once, on the operation, answer or field it governs (19-Nov-2026). ISO 20022’s definitions are in /docs/api/fields.json and /docs/api/terminal.md, and the document quotes none.
  • Terminal: The OpenAPI document’s frames say what each one is, and /docs/api/terminal.md says how a terminal’s side behaves (19-Nov-2026). ISO 20022’s definitions are on that page and in /docs/api/fields.json, and the document quotes none. The page now says that a terminal ignores a key it does not know on every frame the middleware sends, and that the middleware writes an ERROR line at the day’s cap of sign_in_limited.
  • POS, Terminal: How a certificate and a link behave is on /docs/api/onboarding-server.md, /docs/api/onboarding-device.md and /docs/api/linking.md (19-Nov-2026). Each onboarding page now says that of invalid_json, unknown_field, missing_field and invalid_field, the first class that fails answers alone.
  • POS, Terminal, Operator: How the Operator API behaves is on its own page for a back office, which now holds the rules the OpenAPI document’s descriptions held (19-Nov-2026).
  • Terminal: A hosted middleware may close a terminal’s connection within a few seconds when a POS’s sale reaches another instance of it (20-Nov-2026). The terminal reconnects as after any close, as /docs/api/terminal.md says under Reconnect.

Fixed

  • POS, Terminal: A POST with no body is sent with Content-Length: 0 (19-Nov-2026). Over HTTP/1.1, the edge in front of a hosted middleware refuses one without it with 411, a body of its own and not an Error, and the request never reaches the middleware. The OpenAPI document now lists that 411 on each POST with no body, the abort and a device’s renewal challenge among them, and the guides’ cancel sends the header.

v0.2.0 (18-Nov-2026)

An installation is now a register on the wire, so a POS renames each id, header and route and enrols each register again. A terminal that does not know whether a payment was taken now finds out and reports it, and a POS can now read the amount the host approved and ask the terminal to cancel a sale in flight. A terminal can now ask the middleware to sign it in to its fleet’s own payment system, with a credential its fleet set for the store.

Breaking

  • Terminal: A terminal conformance run has a ninth scenario, lost_instruction (16-Nov-2026). The run takes the terminal’s place for one sale, so its instruction never reaches the terminal. The terminal reconnects declaring Mw-Message-Functions: SSMQ, is sent a StatusRequest for the sale, and answers RJCT with AB11. A report that was green is not green again until the terminal does this.
  • Terminal: A terminal conformance run’s approved scenario has a new assertion, approved.amount (17-Nov-2026). Every ACSP the terminal sends for the sale, a resend included, must state TransactionDetails.AuthorisedAmount, equal to the instruction’s TotalAmount exactly as received. A report that was green is not green again until the terminal does this.
  • Terminal: A terminal conformance run has a tenth scenario, cancel (17-Nov-2026). The run aborts a sale 3 seconds after its instruction, while the terminal holds the payment. The terminal declares SSAB in Mw-Message-Functions, is sent an Abort for the sale, and answers RJCT with DS02. A report that was green is not green again until the terminal does this.
  • POS, Operator: A register is called a register on the wire (18-Nov-2026). Its id is RegisterIdentification, reg_ then 32 lowercase hex characters, and its header is Mw-Register. Its routes are under /v1/registers, and every path under /v1/installations answers 404 not_found. A POS changes each name, lists and enrols each register again, and takes a new sandbox key.

Added

  • Terminal: The upgrade’s header Mw-Message-Functions, and the StatusRequest frame (16-Nov-2026). A connection that declares SSMQ is sent a StatusRequest for each sale the middleware still holds open for its terminal from an earlier connection, made in the last 23 hours. The terminal keeps every reference it received, with its outcome, for 24 hours, and answers with an Outcome: the one it holds, or RJCT with AB11 for a reference it never received when its store of references reaches back further than SecondsSinceInstruction. A connection that declares nothing is sent no StatusRequest.
  • POS: A POS conformance run lists a ninth scenario, lost_instruction, as not applicable (16-Nov-2026). A POS’s report that was green stays green.
  • POS, Terminal: The sandbox’s simulated terminals, all but -silent, declare SSMQ, and each answers a StatusRequest but -manual, which queues it for your tools, as mw://world says (16-Nov-2026).
  • Terminal: An ACSP outcome states TransactionDetails.AuthorisedAmount, the amount the host approved, or on a refund refunded (17-Nov-2026). Send it alone in that group, equal to the instruction’s TotalAmount: a terminal adds nothing to TotalAmount, no surcharge, tip or fee, and a refund refunds exactly TotalAmount. An outcome without it still applies, and a value that fails its pattern, or one beside RJCT, is dropped alone.
  • POS: A sale’s read carries TransactionDetails.AuthorisedAmount when the outcome that settled it stated one (17-Nov-2026). Record it as the amount charged, or on a refund refunded: one other than TotalAmount means the terminal broke the contract, and Sale’s ACSP says what to do. A store’s own surcharge on the bill, such as one for a public holiday, stays the POS’s to add to TotalAmount, named in DetailedAmount.Surcharge without its tax.
  • POS, Terminal: The sandbox’s simulated terminals but -manual state AuthorisedAmount on every ACSP, equal to the instruction’s TotalAmount (17-Nov-2026). -manual sends the outcome you write, so state the amount in it yourself.
  • POS: POST /v1/sales/{TransactionReference}/abort asks the sale’s terminal to cancel a sale or a refund in flight, and a POS need not offer it (17-Nov-2026). Only the register that made the sale may abort it, sending no body, while the sale holds its terminal: PDNG, or UNKN inside its hold. The 202 is the sale as it stands, so keep reading it: RJCT with DS02 means it was cancelled and nothing was charged or refunded, and ACSP that the abort came too late. 409 terminal_cannot_abort means cancel at the terminal, 409 sale_not_abortable that the sale has ended, and 409 terminal_offline that the terminal has no connection or its queue is full.
  • Terminal: The Abort frame, {"MessageType":"Abort","TransactionReference":"sal_…"}, sent only on a connection that declares SSAB in Mw-Message-Functions (17-Nov-2026). A payment not yet with its host stops and is answered RJCT with DS02, ISO’s “An authorized user has cancelled the order”; one already with its host carries on and its outcome is sent; an ended reference’s stored outcome is sent unless already sent on this connection; a reference never received gets nothing. An Abort never stops a payment for another reference, and DS02 is sent only in answer to one: a cancel at the terminal stays AB11.
  • POS: A POS conformance run lists a tenth scenario, cancel, as not applicable (17-Nov-2026). A POS’s report that was green stays green.
  • POS, Terminal: The sandbox’s simulated terminals, all but -silent, declare SSAB, and each answers an Abort but -manual, which queues it for your tools (17-Nov-2026). An abort of a sale to -silent is 409 terminal_cannot_abort while the sale holds the terminal, and 409 sale_not_abortable once its hold has ended. mw://world’s Aborts says how each of your terminals answers.
  • Terminal: A terminal that declares SASQ in Mw-Message-Functions may ask to be signed in to its fleet’s own payment system with a LoginNeeded, and is answered a LoginRequest or a Refusal (17-Nov-2026). The ask’s RecipientKey is a fresh P-256 key made for that ask alone, signed on a certificate’s connection by the key of the certificate presented. The answer’s Sealed holds the SignedValue group, whose Signature is a MAC of its Challenge under the fleet’s key, sealed to that fresh key by HPKE, RFC 9180’s base mode, with Kem 0x0010, Kdf 0x0001 and Aead 0x0001. A connection that does not declare SASQ is answered as before: its LoginNeeded is refused unknown_frame_type.
  • Terminal: Four new Refusal codes answer an ask: recipient_key_invalid, sign_in_not_available, sign_in_limited and sign_in_unavailable (17-Nov-2026). recipient_key_invalid is a bug in the terminal’s key or its signature, and after sign_in_not_available, no credential the middleware can use, the terminal asks no more on that connection. After sign_in_limited or sign_in_unavailable it asks again no sooner than 60 seconds later, and short of a session it answers the sale RJCT with AB11. No refusal of an ask closes the connection.
  • Terminal: A terminal conformance run has an eleventh and a twelfth scenario, sign_in and sign_in_none, judged only for a terminal that declared SASQ when the step opened (17-Nov-2026). In sign_in the sale wakes a terminal holding no session, which asks once and answers the sale; in sign_in_none the run ends the store’s sign-in attachment for the step, so the ask is refused sign_in_not_available and the sale answered RJCT with AB11. For a terminal that did not declare SASQ, each is not_applicable, at once where its connection was open as the step began, its row’s NotTested says sign-in was not tested, and the report reads green when every other step passes.
  • POS, Terminal: A conformance report’s ReportVersion is 2, and its DoesNotProve adds that the run judged the log alone and saw no screen (17-Nov-2026). A row may now hold NotTested, only on a terminal’s sign_in or sign_in_none that did not apply. Each scenario of mw://conformance names AppliesIfDeclared, null on every row but those two.
  • Terminal: Each sandbox world’s store holds the sandbox’s stand-in sign-in credential, sandbox-signin-1, attached, so a terminal on -yours can walk its sign-in there (17-Nov-2026). It signs with the sandbox’s own secret, published in mw://world’s SignIn, so a terminal can verify the Signature it opens, and it proves nothing to any fleet. A world opened before this release holds none: a new key opens one that does. validate_message names a LoginNeeded given as an Outcome, and says whether its key has its shape.
  • Terminal: A terminal that declares SASQ reports each sign-in it tried in a LoginResponse, and the sealed SignedValue group carries what its fleet’s payment system needs for the store (18-Nov-2026). After Signature the group holds LoginReference, the middleware’s name for that one answer, then AcceptorIdentification, UserName and ApplicationIdentification, each only where the store, its attachment or its credential holds one. The report names the opened group’s LoginReference with Response SUCC, or FAIL and ResponseReason not_covered, not_accepted or no_answer, and is sent no frame. A first failure in a row other than not_covered opens one answer at once, inside the interval, so ask again at once, once; after any other FAIL, ask again no sooner than 60 seconds later.
  • Terminal: A terminal conformance run’s sign_in has a new assertion, login_reported, and its one_ask takes a second ask only after a sign_in_failed line (18-Nov-2026). login_reported passes on a report the middleware took of the step’s LoginRequest, and one_ask never takes a third ask on one connection. sign_in is new in this release, and stays not_applicable for a terminal that did not declare SASQ, which is sent nothing new. mw://start’s sign-in step now ends with the report, and validate_message names a LoginResponse given as an Outcome.
  • Terminal: A LoginRequest that does not open, or that names a suite the terminal does not take, is treated as sign_in_unavailable (18-Nov-2026). The terminal answers the sale RJCT with AB11, and asks again no sooner than 60 seconds later. It reports nothing for it: no group was opened, so there is no LoginReference to name.
  • Terminal: The sandbox, hosted or run from its image, answers one terminal’s sign-in up to 1440 times a day, where the relay’s default stays 24 (18-Nov-2026). Each conformance run of a terminal spends one answer, and so does each restart of it. sign_in_limited still answers an ask within 60 seconds of the last answer.

Changed

  • Terminal: A terminal that does not know whether a payment was taken must find out (16-Nov-2026). It asks its host for the payment by the reference it stored, or reverses it and sends RJCT with AB11 once the host has confirmed the reversal, and it sends the outcome as soon as it knows. A second Instruction while a payment runs is never started, and is answered RJCT with AB11.
  • POS, Terminal: The two integration guides are rebuilt, one for a POS vendor’s developer and one for a terminal fleet vendor’s (17-Nov-2026). Each walks three stages, integrate, enrol and link, through the sandbox, staging and production. The terminal’s guide covers the StatusRequest and the Abort, and the POS’s guide the abort of a sale. Each says where to get help: by email in the sandbox, then on a private Slack Connect channel once the vendor signs with FUNDiMO.

v0.1.0 (16-Nov-2026)

The first numbered release. Every build from 07-Nov-2026 to this one called itself 0.1.0, so a report naming SandboxVersion 0.1.0 may come from any of them. Its FinishedAt dates it against the dated bullets below.

Breaking

  • POS, Terminal: Every operation but GET /v1/health needs a credential, the terminal’s WebSocket upgrade among them (08-Nov-2026). In the sandbox it is a sandbox key, sent as Authorization: Bearer sbx_.... The middleware issues every id, a terminal’s POIIdentification among them, so a terminal no longer chooses its own. A whitelist decides who may sell where, and its refusal is 403 not_permitted.
  • POS: A sale’s answer states its result in ISO 20022’s terms (10-Nov-2026). TransactionStatus, one of PDNG, ACSP, RJCT and UNKN, and StatusReasonInformation replace AuthorisationResult. PaymentReference groups its references by the kind of payment: Card, Bank, Wallet and NPP.
  • Terminal: The terminal contract’s version 3 states an outcome in ISO 20022’s terms (10-Nov-2026). An outcome holds TransactionStatus, ACSP or RJCT, and a StatusReasonInformation whose Reason says why no payment was taken. Its references are grouped by kind. An outcome built to version 2 is refused missing_field.
  • POS, Terminal: The link word is a pair of two different words joined by a dot, such as rabbit.lamp: the terminal contract’s version 4 (11-Nov-2026). A terminal shows it from LinkWord’s Word, and a register sends it to POST /v1/links/{LinkIdentification}/word. A terminal that checks the frame against version 3’s pattern refuses it. A link request in a store with more unbound terminals than it can give pairs is refused 409 too_many_terminals.
  • POS, Terminal: Every name a side sends or matches says mw (12-Nov-2026). The header is Mw-Installation, the MCP resources are under mw://, and the text a device’s attestation challenge is made from begins mw-enrol-v1. The OpenAPI document’s x-sent-by names the middleware mw. A client built to the earlier names changes them.
  • POS, Terminal: A device’s pairing code is five words, each different, from the list at mw://docs/words.txt (14-Nov-2026). The 16-character form ended at that day’s deploy, and a server’s code did not change. A device code issued before the deploy and not yet typed was refused. A device whose answer was lost in the 15 minutes before the deploy is paired again, with a new code.

Added

  • POS, Terminal: The relay, and the terminal contract’s version 1 (07-Nov-2026). A POS creates a sale with POST /v1/sales, and reads it with GET /v1/sales/{TransactionReference}, holding the read for up to wait_seconds. A terminal holds a WebSocket at GET /v1/terminals/{POIIdentification}/connect, is sent a TerminalInstruction, and answers with a TerminalOutcome. Field names are ISO 20022’s, and an amount is a string such as "12.50".
  • POS, Terminal: The field catalogue and the conformance scenarios (07-Nov-2026). The catalogue has one row for each field of each message. Each scenario lists the assertions it is judged by. The sandbox, from 11-Nov-2026, serves them as mw://fields and mw://conformance.
  • POS, Terminal, Operator: The Operator API, for vendors and their servers, app identities, allowed models, sandbox keys, merchant stores and their aliases, terminals and registers (08-Nov-2026). A vendor’s admin manages its own, and the operator manages every vendor’s. A PairingCode and a SandboxKey are each shown once, in one answer.
  • POS, Terminal: A device or a server holds a client certificate of its own (10-Nov-2026). It spends a pairing code once at POST /v1/enrol, and renews at POST /v1/certificates/renew, a device after POST /v1/certificates/challenge. A live middleware checks a device’s key attestation when it enrols. GET /v1/certificates/self is the daily check of the certificate presented.
  • Terminal: The terminal contract’s version 2 (10-Nov-2026). A live terminal presents a client certificate. While a register links to it, a terminal is sent LinkWord, the word to show, and LinkEnded when the link ends. A terminal built to version 1 ignores both frames.
  • POS: A register links to a terminal at the counter by the word the terminal shows (10-Nov-2026). It asks at POST /v1/links, then sends the word to POST /v1/links/{LinkIdentification}/word. GET /v1/register/terminals lists the terminals bound to it.
  • POS, Terminal: The sandbox (11-Nov-2026). POST /sandbox/v1/keys gives a key and a world of your own, and asks for no credential. Its MCP server at POST /mcp serves the contract as resources, and tools to read fields, send sales, drive a terminal and read the log. A conformance run of your side ends in a signed report, which the key at mw://report-key verifies.
  • POS, Terminal: The sandbox names its entry points (11-Nov-2026). GET / answers llms.txt, which lists the sandbox guide first. A 404 off the sandbox’s routes names GET /llms.txt, POST /mcp and POST /sandbox/v1/keys in Next. mw://world states the sandbox’s TlsMode, and its WebSocket ping interval in Timers.
  • POS, Terminal: A vendor’s admin reads the certificates of its own servers, stores, terminals and registers (13-Nov-2026). Each is a GET of certificates under the vendor, the store, the terminal or the installation, such as GET /v1/terminals/{POIIdentification}/certificates. GET /v1/merchant-stores/{StoreIdentification}/accepted-vendors reads a store’s accepted vendors.
  • POS, Terminal: A hosted middleware stands behind an edge (13-Nov-2026). On POST /v1/enrol the edge may answer a 429 of its own, whose body is not an Error. Wait a minute, then send the same request again: the code was not read, and no attempt is counted.
  • Terminal: Refunds, the terminal contract’s version 5 (14-Nov-2026). An Instruction may carry TransactionType RFND and an OriginalTransaction, the sale to refund. A terminal that declares Mw-Transaction-Types: CRDP, RFND on its upgrade is sent refunds. One that declares nothing is sent sales alone.
  • POS: A POS asks for a refund with POST /v1/sales, as for a sale (14-Nov-2026). The body holds TransactionType RFND, the sale in OriginalTransaction, and the amount to refund in TotalAmount. The refund is read as a sale is. A sale that cannot be refunded here is 409 sale_not_refundable, and a terminal that has not said it takes refunds is 409 terminal_cannot_refund.
  • POS, Terminal, Operator: A terminal’s and a register’s listing hold Attestation, the mark of a failed key attestation (14-Nov-2026). It gives State failed, the FailedChecks and Since. Only a middleware with MW_ATTESTATION_FAILURES set to mark records one. A sandbox marks nothing.
  • POS, Terminal: Two step-by-step integration guides, as PDF files: one for a POS’s developer, one for a terminal’s (14-Nov-2026). Each walks from a sandbox key to live. They followed the five pairing words the same day, the two environments on 15-Nov-2026, and the enrolment screen on 16-Nov-2026. Where a guide and the published pages differ, the pages are right.
  • POS, Terminal: mw://environments names the two environments open to an integration, the sandbox and staging (15-Nov-2026). It gives each one’s base URL, its credential, and what differs. Keep the base URL in one setting, so the same code reaches staging.
  • POS, Terminal: The device walk, mw://onboarding/device, states the requirements of an app’s enrolment screen (16-Nov-2026). It is the screen a person enrols a terminal or a register on, reached from the app’s own menu with the device alone. Each requirement is a Must or a Should, with a check a person can make at the device. A conformance run does not check the screen.
  • POS, Terminal: The middleware has a release number (16-Nov-2026). The MCP server states it in serverInfo.version and the first sentence of its instructions. Each host states it in GET /v1/health, as Version, and a report in SandboxVersion.

Changed

  • POS: A sale outlives a restart of the middleware (08-Nov-2026). The same IdempotencyKey after a restart answers the sale as it stands. 503 at_capacity is gone, and 503 store_unavailable means retry with the same key, never a new one.
  • Terminal: After any reconnect, a terminal sends its most recent outcome again (08-Nov-2026). It stops at a new TerminalInstruction, at a TerminalRefusal for that outcome, or 23 hours after it first sent it. The reconnect backoff resets only once a connection has stayed open 10 seconds.
  • POS: A sale’s TransactionStatus and Reason are open lists (11-Nov-2026). A later version may add a code, and an answer that holds one still validates. Read a status you do not know as UNKN, and RJCT as no payment taken, whatever its Reason.
  • Terminal: A terminal conformance run checks that an outcome is sent once on a connection (11-Nov-2026). Each scenario that ends on an outcome adds an assertion, such as approved.one_outcome. A sale’s outcome sent twice on one connection fails it.
  • POS, Terminal: The sandbox guide says more of a conformance run (11-Nov-2026). It shows what conformance_start answers, and two worked conformance_status answers. It gives the report key’s encoding, the raw 32-byte Ed25519 key in base64. It says, for each side, what a green run does not check.
  • POS, Terminal: The pages say more on three points (13-Nov-2026). A terminal whose WebSocket library answers Pings itself sets its own ping every 30 seconds, and the middleware answers each with a Pong. A 201 from enrolment after a re-pair ends any wait, so connect at once. The sandbox guide states the sandbox’s 30-second sale deadline, so a slow sale reads UNKN until its outcome replaces it.
  • POS, Terminal: On staging, a device whose key attestation fails some checks is issued its certificate all the same, and marked (15-Nov-2026). It enrols and takes sales, so everything but the attestation can be tested. The checks that tie the chain to this request, this key and this app still refuse.

Fixed

  • POS, Terminal: Two dead ends in the sandbox are gone (11-Nov-2026). A sandbox with no CA answers POST /v1/enrol with 503 ca_unavailable, and a Next saying no run can start there. A world whose log had filled could never run green: now a step’s window is partial only when a line after its start was lost.
  • POS, Terminal, Operator: A hosted middleware reads a client certificate’s fingerprint from its edge in standard or URL-safe base64, padded or not (13-Nov-2026). Before, it read one form alone, so a good certificate could be refused 503 edge_not_trusted. The refusal’s log line now names the check that failed.
  • POS: On the hosted sandbox, a POS run’s resend step no longer ends the run (13-Nov-2026). Its lost answer is a 503 whose body is not an Error, on a connection left open. Before, the lost answer stopped the sandbox, and the run was lost with all it held in memory.