# 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`:

```sh
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:

```kotlin
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`:

```json
{ "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:

```sh
curl -s "$MW/v1/links/lnk_..." \
  --cert chain.pem --key server.key \
  -H 'Mw-Register: reg_...'
```

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

```bash
# 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:

```kotlin
/** 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:

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

| Status | `Error.Code` | When | What the POS shows |
|---|---|---|---|
| `201` | | The ask opened a request | Read 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 |
| `200` | | The word bound the register to the terminal | That the register is linked to the terminal, which shows the same |
| `400` | `invalid_field` | At 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 counted | That the terminal shows two words, and to type both, in the order shown, with a dot or a space between them |
| `403` | `link_word_unknown` | No 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 store | That the words did not match, and a button to ask again, which opens a new request with new words |
| `409` | `link_in_progress` | Another request is open at this store, or for this register | That another register at the store is linking now: try again in a minute |
| `409` | `no_terminal_to_link` | No terminal of the store is paired and unbound | That 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 |
| `409` | `too_many_terminals` | More terminals of the store are paired and unbound than one request can ask, 523,776. Nothing was written | That too many terminals here are waiting to link: have the store's fleet owner bind or remove terminals of the store, then ask again |
| `410` | `link_expired` | The request has ended: its time passed, it was closed by a wrong pair or a refusal, or the terminal it bound has been unlinked since | That the words have timed out, and a button to ask again |
| `429` | `link_rate` | Your 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 asked | That linking is paused at this store: wait an hour, or after three wrong pairs until tomorrow |
| `409` | `register_in_other_store` | The register is bound at another store, when it asked or since. At the word, the request has ended | That 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 |
| `404` | `not_found` | The request is another register's, or no request has that id | A bug of the POS: a word goes from the register that asked. Ask again from this register |
| `403` | `not_permitted` | The 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 ended | That 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`, `403` | `certificate_required`, `certificate_invalid`, `certificate_expired`, `certificate_retired` | The register's credential is refused | A 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 |
| `503` | `store_unavailable` | The middleware's store did not answer. A request stands, or never existed | That 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:

```sh
curl -s "$MW/v1/register/terminals" \
  --cert chain.pem --key server.key \
  -H 'Mw-Register: reg_...'
```

```json
{ "Terminals": [ { "POIIdentification": "poi_...", "State": "paired", "Connected": true, "Busy": false } ] }
```

| Field | Means |
|---|---|
| `POIIdentification` | The terminal's id, which a sale names |
| `State` | `listed`, `paired`, `suspended` or `removed`. Only `paired` takes a sale |
| `Connected` | Whether 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 |
| `Busy` | Whether 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:

```sh
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:

```sh
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:

```sh
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.
