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: linking a register to a terminal

11-Nov-2026.

This is the walk for a POS vendor linking a register to a payment terminal at the counter, and for whoever writes the screen staff see while they do it. A register is one till of a POS: an app on a device, or a name a vendor’s server gives. Linking binds it to a terminal of the store it is in, so its sales can name that terminal. You can build the register’s side from this document alone. An agent reads the same bytes through llms.txt, and through the sandbox’s MCP server as mw://onboarding/linking.

Linking comes after onboarding, and needs no one but the staff member at the counter. The register asks, each unbound terminal of the store shows a different word, and the staff member types the word on the terminal in their hand. Each terminal’s word is a pair: two words of the middleware’s list joined by a dot, such as rabbit.lamp. The middleware binds the register to that terminal and keeps the binding, so the POS keeps nothing but the terminal’s id, and a sale names its POIIdentification as before.

A POS never sees a word. No answer the middleware gives a POS holds one, at any step, and that is the whole proof: the person at the register typed what only someone holding that terminal could read. If you also write the terminal’s app, never pass its word to the POS by any other path.

Read it beside docs/api/terminal.md, which says what a terminal shows (Linking to a register), and docs/api/openapi.yaml, which holds the schema of every route named here, tagged links.

In short

  1. The register asks to link at its store: POST /v1/links with the store’s MerchantIdentification (step 1).
  2. The middleware gives each paired, unbound terminal of the store a different pair of words, and answers with the request’s id (step 2).
  3. Each of those terminals shows its pair, for two minutes by default, and the register may read how many do (step 3).
  4. The staff member types the pair on the terminal in their hand, with a dot or a space between the two words: POST /v1/links/{LinkIdentification}/word (step 4).
  5. The middleware binds the register to that terminal, and answers with its POIIdentification (step 5).

What the POS shows staff at each answer is a table of its own, below the steps. Beside them: the register’s own terminals, unlinking, and what a store’s fleet owner can do.

Before you start

  • The register is onboarded. A register that is an app on a device presents its own certificate (docs/api/onboarding-device.md), and sends no Mw-Register, or one naming itself. A vendor’s pos server presents its certificate and names the register in Mw-Register on every call here (docs/api/onboarding-server.md, step 6).
  • The terminal is paired at the store, and bound to no register. Its fleet owner listed it at the store, and it enrolled. It is shown a word only while it is connected.
  • The store is onboarding or live, and accepts the register’s vendor. A store accepts the register of any onboarded vendor until its fleet owner says otherwise (What a store’s fleet owner can do, below).
  • The POS holds the store’s MerchantIdentification. The fleet owner gives the merchant the store’s own, mid_ then 8 characters, and a POS needs it for every sale anyway. An alias of it that your vendor accepted works as well.

The commands here read the middleware’s base URL from $MW, one of those /docs/api/environments.md names, and present a pos server’s certificate, chain.pem and server.key, as docs/api/onboarding-server.md makes them. The Kotlin is for a register on a device, and uses the helpers of docs/api/onboarding-device.md (What you need), its MW among them, and the client of its step 8, which presents the register’s own certificate.

In the sandbox

The link routes are served in the sandbox as on live, on a certificate or on your tester’s pos key, which names your world’s register already. That register starts bound to every terminal of your world, so asking answers 409 no_terminal_to_link until one is unbound. To try the step with your own terminal, unlink -yours (Unlinking, below), connect it, and ask at your world’s MerchantIdentification: your terminal shows the word.

1. The register asks: POST /v1/links

The register names the store with MerchantIdentification, and a pos server names the register in Mw-Register:

curl -s -X POST "$MW/v1/links" \
  --cert chain.pem --key server.key \
  -H 'Mw-Register: reg_...' \
  -H 'Content-Type: application/json' \
  -d '{"MerchantIdentification":"mid_..."}'

On a device:

import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import org.json.JSONObject

/** Asks to link this register at the store [merchantId] names. A `201` holds the request. */
fun askToLink(client: OkHttpClient, merchantId: String): Answer {
    val body = JSONObject().put("MerchantIdentification", merchantId).toString().toRequestBody(JSON)
    return call(client, Request.Builder().url("$MW/v1/links").post(body).build())
}

One request is open at a store, and one for a register, at a time. The caller’s vendor and register must be active, the store onboarding or live with an active owner, and the store must accept the caller’s vendor. Any other case is 403 not_permitted, the same answer as a store that does not exist, so a POS cannot tell which. A 409 here writes nothing and counts toward no limit. Each answer, and what to show, is in What the POS shows at each answer, below.

2. The middleware picks the words

The middleware gives each paired terminal of the store with no binding a different pair of two words from its list, and answers 201:

{ "LinkIdentification": "lnk_...", "ExpiresInSeconds": 120 }

LinkIdentification is the request’s id: keep it for steps 3 and 4. ExpiresInSeconds is how long the terminals show their words, 120 seconds by default. The answer holds no word. Only an unbound terminal is asked, so a terminal already linked is never disturbed, and a guess can never take one.

A pair is two different words of the middleware’s list, in order, joined by a dot, such as rabbit.lamp. The list holds 1,024 words of common English, each 3 to 6 lowercase letters, and no two of them are within one edit of each other. Each pair is drawn uniformly, and no request holds a pair and its reverse, so a staff member who reads the two words the wrong way round is refused, never bound to another terminal. A guess is one of 1,047,552 ordered pairs, so with N terminals asked it has N chances in 1,047,552 to match one: at 40 terminals, 1 in 26,189.

One request asks at most 523,776 terminals, the pairs of two different words of the list counted once whichever way round. A store with more paired terminals unbound than that is refused 409 too_many_terminals, and nothing is written.

3. Each terminal shows its word

Each terminal asked shows its word, large enough to read across the counter, until it links, a word is refused, or ExpiresInSeconds pass (docs/api/terminal.md, Linking to a register). A word reaches a terminal connected to the same instance of the middleware at once, and one connected to another instance within a ping interval, 30 seconds by default.

Meanwhile the POS asks the staff member to read the two words on the terminal in their hand, and may read GET /v1/links/{LinkIdentification} to know how many terminals show a pair:

curl -s "$MW/v1/links/lnk_..." \
  --cert chain.pem --key server.key \
  -H 'Mw-Register: reg_...'
{ "Asked": 2, "Shown": 1 }

Asked counts the terminals given a word, and Shown those whose word has reached them. So the screen can say that no terminal is showing a word yet while Shown is 0, and the POS never learns a word. A word not yet shown cannot link. Only the register that asked may read the request: any other is answered 404 not_found.

4. The staff member types the word: POST /v1/links/{LinkIdentification}/word

The staff member types what they see on the device in their hand, both words in the order shown, with a dot or a space between the two words, and the register sends it as Word: rabbit.lamp and rabbit lamp are the same pair. Case and surrounding spaces are ignored. Never log the word and never keep it: it is the proof while it is shown.

A Word that is not a pair is refused 400 invalid_field naming Word before the store is asked, so the request stays open and nothing is counted: one word alone, the same word twice, no dot or space between the words, two spaces, a dot with a space beside it, a third word, a digit, a word outside 3 to 6 letters, or more than 64 characters.

# Read the two words as typed, so they stay out of the shell's history.
read -r -p 'Words on the terminal: ' WORD
jq -n --arg word "$WORD" '{Word: $word}' \
  | curl -s -X POST "$MW/v1/links/lnk_.../word" \
      --cert chain.pem --key server.key \
      -H 'Mw-Register: reg_...' \
      -H 'Content-Type: application/json' \
      --data-binary @-

On a device:

/** Sends the word the staff member typed. Never log it, and never keep it. */
fun sendWord(client: OkHttpClient, linkId: String, typed: String): Answer {
    val body = JSONObject().put("Word", typed).toString().toRequestBody(JSON)
    return call(client, Request.Builder().url("$MW/v1/links/$linkId/word").post(body).build())
}

One attempt: a pair no terminal of this request showed, in that order, ends the request, clears every terminal, and counts toward your vendor’s limit at the store. A pair typed the wrong way round is such a pair. Only the register that opened the request may send its word, and any other is answered 404 not_found, so a word read over a staff member’s shoulder gains a bystander nothing. If an answer is lost, send the same word again: a word that bound answers the same 200, and a request that has ended answers 410 link_expired.

5. The middleware binds

A pair a terminal of this request showed, in the order shown, binds the register to that terminal, and sets the register at the store if it sat at none. The 200 names both:

{ "POIIdentification": "poi_...", "MerchantIdentification": "mid_..." }

The bound terminal shows that it linked, and every other terminal asked clears. From then on the register’s sales name that terminal by POIIdentification, beside the store’s MerchantIdentification. Keep the POIIdentification with the register: its sales, its list of terminals and its unlink button all name it.

A register may bind several terminals of one store, one request each, and a terminal binds one register. A register bound at one store cannot link at another until its bindings there end.

What the POS shows at each answer

The POS never shows a word, because it never has one. At each answer it tells the staff member what happened and what to do next, in its own words.

StatusError.CodeWhenWhat the POS shows
201The ask opened a requestRead the two words on the terminal in your hand and type them here, with a dot or a space between them, beside the time left from ExpiresInSeconds. While GET /v1/links/{LinkIdentification} reads Shown 0, that no terminal shows a word yet
200The word bound the register to the terminalThat the register is linked to the terminal, which shows the same
400invalid_fieldAt the word: Word is not a pair of two different words with a dot or one space between them. The request stays open, and nothing is countedThat the terminal shows two words, and to type both, in the order shown, with a dot or a space between them
403link_word_unknownNo terminal of the request showed the pair, in that order. The request has ended, every terminal has cleared, and the wrong pair counts toward your vendor’s limit at the storeThat the words did not match, and a button to ask again, which opens a new request with new words
409link_in_progressAnother request is open at this store, or for this registerThat another register at the store is linking now: try again in a minute
409no_terminal_to_linkNo terminal of the store is paired and unboundThat no terminal here is waiting to link: check the terminal is switched on, paired at this store and connected, and not already linked to another register
409too_many_terminalsMore terminals of the store are paired and unbound than one request can ask, 523,776. Nothing was writtenThat too many terminals here are waiting to link: have the store’s fleet owner bind or remove terminals of the store, then ask again
410link_expiredThe request has ended: its time passed, it was closed by a wrong pair or a refusal, or the terminal it bound has been unlinked sinceThat the words have timed out, and a button to ask again
429link_rateYour vendor asked 10 times at this store in the last hour, or sent 3 wrong pairs there in the last 24 hours, whichever of its registers askedThat linking is paused at this store: wait an hour, or after three wrong pairs until tomorrow
409register_in_other_storeThe register is bound at another store, when it asked or since. At the word, the request has endedThat this register is linked at another store, and to unlink it there first: DELETE /v1/links/{POIIdentification} for each terminal GET /v1/register/terminals lists, then ask again
404not_foundThe request is another register’s, or no request has that idA bug of the POS: a word goes from the register that asked. Ask again from this register
403not_permittedThe register or its vendor is not active, or the store does not exist, is not onboarding or live with an active owner, or does not accept your vendor, when it asked or since. At the word, the request has endedThat this register cannot link at this store: check the store’s MerchantIdentification, and ask the store’s fleet owner whether it accepts registers of your POS
401, 403certificate_required, certificate_invalid, certificate_expired, certificate_retiredThe register’s credential is refusedA fault for whoever runs the register, not for the staff member. The holder’s table of docs/api/onboarding-device.md or docs/api/onboarding-server.md says what to do
503store_unavailableThe middleware’s store did not answer. A request stands, or never existedThat linking is unavailable for now: try again in a minute. At the word, send the same word again

The register’s terminals: GET /v1/register/terminals

GET /v1/register/terminals lists the terminals bound to the caller, a register, or a pos server naming one, for the register’s own screen:

curl -s "$MW/v1/register/terminals" \
  --cert chain.pem --key server.key \
  -H 'Mw-Register: reg_...'
{ "Terminals": [ { "POIIdentification": "poi_...", "State": "paired", "Connected": true, "Busy": false } ] }
FieldMeans
POIIdentificationThe terminal’s id, which a sale names
Statelisted, paired, suspended or removed. Only paired takes a sale
ConnectedWhether the terminal holds a connection to the instance of the middleware that answered. It is that instance’s own knowledge, so it can read false for a while as the middleware moves between instances
BusyWhether a sale holds the terminal

Connected is for a screen, not a gate: a sale to a terminal not connected is refused 409 terminal_offline in any case.

Unlinking: DELETE /v1/links/{POIIdentification}

The register’s own unlink button ends its binding to a terminal, named by the terminal’s POIIdentification, not by a request’s id:

curl -s -X DELETE "$MW/v1/links/poi_..." \
  --cert chain.pem --key server.key \
  -H 'Mw-Register: reg_...'

The answer is 204. The register’s next sale naming the terminal is refused, and a sale already in flight is untouched. The terminal is unbound, so a register linking at its store may be shown a word on it again. A terminal not bound to the caller is 404 not_found. Once a register’s last binding ends it sits at no store, and may link at another.

A terminal removed, or a register removed, ends its bindings as well. A re-pair ends none, because the device and its serial are the same.

What a store’s fleet owner can do

The fleet owner that listed a store’s terminals sees each with the register and the vendor bound to it, at GET /v1/merchant-stores/{StoreIdentification}/terminals, so a binding it never made is visible (in docs/api/openapi.yaml, tagged operator). It acts on its admin server’s certificate, here admin-chain.pem and admin.key (docs/api/onboarding-server.md), and can do two things a POS cannot.

End a binding, of any register, with DELETE /v1/terminals/{POIIdentification}/binding. The terminal’s owner may, and so may the operator:

curl -s -X DELETE "$MW/v1/terminals/poi_.../binding" \
  --cert admin-chain.pem --key admin.key

The answer is 204, also where the terminal had no binding. It ends the binding as the register’s own unlink does.

Restrict which vendors’ registers the store accepts, with PUT /v1/merchant-stores/{StoreIdentification}/accepted-vendors, the store’s owner alone:

curl -s -X PUT "$MW/v1/merchant-stores/mst_.../accepted-vendors" \
  --cert admin-chain.pem --key admin.key \
  -H 'Content-Type: application/json' \
  -d '{"AcceptsAnyVendor":false,"Vendors":["ven_..."]}'

The answer is 204. Every store starts accepting the register of any onboarded vendor: an active vendor with the pos role, whose register holds a certificate. Vendors replaces the list before it, and {"AcceptsAnyVendor":true} accepts any again. A register of a vendor not accepted is refused 403 not_permitted when it asks to link at the store, and at the word of a request it opened before the change, which then ends. A binding already made stands until it is ended.

A word proves that someone can see the terminal, not that they are the store’s staff, and a vendor’s limits at a store bound what it can try there, however many registers it holds. So a fleet owner that sees a binding it does not expect ends it, and restricts the store to the vendors whose registers it uses.