openapi: '3.1.0'
info:
  title: 'Middleware v0.3.1: what a POS calls'
  version: '1.0.0'
  summary: The relay between a point of sale, a payment terminal and FUNDiMO.
  description: |-
    The routes a POS calls: a sale, its reads and its abort, and a refund, which is a sale of its own; linking a register to a terminal; the five routes your own `admin` server calls on your registers; enrolling for a certificate, its daily check and its renewal; and the health check. Each property's `x-sent-by` names who sends it. `servers` holds the base URL of the sandbox, then of staging. This release publishes this document as `openapi-pos.yaml`.
servers:
  - url: https://mw.sandbox.fundimo.com.au
    description: The sandbox
  - url: https://mw.staging.fundimo.com.au
    description: Staging
security:
  - mutualTLS: []
  - sandboxKey: []
tags:
  - name: sales
    description: What a POS calls.
  - name: links
    description: >-
      Linking a register to a terminal by a word the terminal shows, and what the register is bound to.
  - name: registers
    description: 'Managing your registers: the routes your own `admin` server calls on your registers, from the Operator API.'
  - name: certificates
    description: >-
      A principal's client certificate: enrolment with a pairing code, the daily check, and renewal with a new key.
  - name: health
    description: Whether the middleware is serving.
paths:
  /v1/sales:
    post:
      tags: [sales]
      operationId: createSale
      summary: Create a sale and send its instruction to the terminal.
      description: |
        Creates a sale and sends its `TerminalInstruction` to the terminal that
        `POIIdentification` names, as one step, and answers at once. The caller is identified
        first, by its credential, and the idempotency key is then looked up, in the caller's own
        register, before the whitelist and the terminal are checked. A `400`, `403`, `409` or
        `413` refusal leaves nothing behind and spends no key.

        Any register of the sale's vendor at the sale's store may refund it here, under a key of
        its own, on any terminal it may sell to that declared `RFND` when it connected; the
        middleware keeps no total of a sale's refunds and does not compare a refund's amount with
        the sale's, so a host that caps them answers `RJCT`, and the POS shows the cashier what it
        has refunded already, from its own records.
      parameters:
        - $ref: '#/components/parameters/MwRegister'
      requestBody:
        required: true
        description: The sale. At most 65,536 bytes.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaleRequest'
            examples:
              with_items:
                summary: A sale with one item.
                value: {"MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "INV-1001", "IdempotencyKey": "b8a1f5a0-3c1e-4c52-9d3e-0a4d7f1e6c11", "CreationDateTime": "2026-11-06T15:12:33+11:00", "CashierIdentification": "STAFF-0042", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "12.50", "DetailedAmount": {"ValueAddedTax": "1.14"}, "SaleItem": [{"ProductDescription": "Flat white", "ProductCode": "FW-2", "ProductQuantity": 2, "UnitPrice": "6.25", "ProductAmount": "12.50", "ValueAddedTax": "1.14"}]}}
              without_items:
                summary: A sale with no items, which a terminal shows as an amount alone.
                value: {"MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "INV-1002", "IdempotencyKey": "c2d4e6f8-1a3b-4c5d-8e9f-0a1b2c3d4e5f", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "12.50"}}
              refund:
                summary: A refund of one of the two flat whites of the sale `with_items`, under a credit note's reference and a key of its own.
                value: {"TransactionType": "RFND", "OriginalTransaction": {"TransactionReference": "sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a"}, "MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "CN-1001", "IdempotencyKey": "refund-0001", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "6.25", "SaleItem": [{"ProductDescription": "Flat white", "ProductQuantity": 1, "UnitPrice": "6.25", "ProductAmount": "6.25"}]}}
      responses:
        '200':
          description: >-
            The same key and the same body as a sale the middleware holds, `CreationDateTime` and `CashierIdentification` aside: the sale as it stands now, even if a vendor, the store or the binding has been suspended or removed since. Nothing is sent to the terminal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sale'
              examples:
                repeat:
                  summary: A repeat while the sale is still pending.
                  value: {"TransactionReference": "sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a", "MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "INV-1001", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "12.50"}, "TransactionStatus": "PDNG", "StatusReasonInformation": null, "PaymentReference": null}
        '202':
          description: >-
            A new sale, pending, `TransactionStatus` `PDNG`, and its instruction sent to the terminal. Read it until it settles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sale'
              examples:
                accepted:
                  summary: A new sale.
                  value: {"TransactionReference": "sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a", "MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "INV-1001", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "12.50"}, "TransactionStatus": "PDNG", "StatusReasonInformation": null, "PaymentReference": null}
                refund:
                  summary: A new refund, of the request example `refund`, naming the sale it refunds.
                  value: {"TransactionType": "RFND", "TransactionReference": "sal_02a8f3c4d5e6f708192a3b4c5d6e7f80", "MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "CN-1001", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "6.25"}, "OriginalTransaction": {"TransactionReference": "sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a"}, "TransactionStatus": "PDNG", "StatusReasonInformation": null, "PaymentReference": null}
        '400':
          description: |
            The first of `invalid_json`, `unknown_field`, `missing_field` and `invalid_field` that
            fails answers alone, and `Error.Fields` names every field of that class, sorted: fix the
            sale before sending it again.

            - `invalid_json`: the body is not a JSON object, or the middleware cannot parse it
              because it holds, in any field, a `\u` escape of half a surrogate pair with no other
              half, a number beyond the range of an IEEE 754 double, such as `1e400`, or arrays and
              objects nested 128 deep, the body's own object counting as one.
            - `unknown_field`: the body holds a field this contract does not define, at any depth.
            - `missing_field`: a required field is absent.
            - `invalid_field`: a field breaks its rule, a required field sent as `null` and an item
              that is not an object included.
            - `body_unreadable`: the body could not be read to its end, such as a chunked body that
              breaks off.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_json:
                  value: {"Error": {"Code": "invalid_json", "Message": "The body is not a JSON object.", "Fields": []}}
                unknown_field:
                  value: {"Error": {"Code": "unknown_field", "Message": "The body holds a field the contract does not define.", "Fields": ["Note"]}}
                missing_field:
                  value: {"Error": {"Code": "missing_field", "Message": "The body lacks a field the contract requires.", "Fields": ["TransactionDetails.Currency"]}}
                invalid_field:
                  value: {"Error": {"Code": "invalid_field", "Message": "A field does not meet its rule in the contract.", "Fields": ["TransactionDetails.SaleItem[0].ProductDescription"]}}
                body_unreadable:
                  value: {"Error": {"Code": "body_unreadable", "Message": "The body could not be read.", "Fields": []}}
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          description: |
            - `not_permitted`: the credential is good, and it is not a register's, or the whitelist
              refuses the sale: the caller's vendor is suspended, its register is not active or not
              bound to `POIIdentification`, that terminal is not `paired`, its store is not `live`,
              the store's owner is suspended, or `MerchantIdentification` is neither the store's own
              id nor an accepted alias of it for the caller's vendor. One code answers every reason,
              so a caller cannot probe which merchants or terminals exist, and the key is unspent.
            - `certificate_retired`: the client certificate presented is retired, before any key is
              looked up, and a sale an earlier send made may stand. Send the sale again on the
              register's newer certificate, with the same `IdempotencyKey` from the same register,
              or on its newest, stop and tell a person.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_permitted:
                  value: {"Error": {"Code": "not_permitted", "Message": "The caller is not permitted to do this.", "Fields": []}}
                certificate_retired:
                  value: {"Error": {"Code": "certificate_retired", "Message": "The certificate presented is retired: a newer one of this identity is in use.", "Fields": []}}
        '409':
          description: |
            The sale conflicts with what the middleware holds, or a refund cannot be made here.

            - `idempotency_conflict`: the key names a sale with a different body, and the first
              sale is unchanged. After a lost answer, a sale may exist under that key with no id
              for you to read: treat its outcome as unknown, tell the cashier to check the
              terminal, and do not take another tender until they have.
            - `terminal_offline`: the terminal has no current connection. Nothing is
              created and the key is unspent: retry with the same key.
            - `terminal_busy`: the terminal is claimed by another sale. Nothing is created
              and the key is unspent.
            - `sale_not_refundable`: a refund whose `OriginalTransaction` names no sale the
              middleware can refund here, one approved as a sale, of the caller's vendor, at the
              store of the terminal's binding and with its refund window open: any other id, one
              never issued included, gets this one code, so a caller cannot probe what exists.
              Nothing is created and the key is unspent: refund at the terminal directly, or
              another way, since the same refund sent again is refused again.
            - `terminal_cannot_refund`: a refund for a terminal that is connected and has not
              said it takes refunds, as it declares `RFND` in `Mw-Transaction-Types` when it
              connects. Nothing is created, the terminal is sent nothing, and the key is
              unspent: choose another terminal, one that takes refunds, and send the refund there.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                idempotency_conflict:
                  value: {"Error": {"Code": "idempotency_conflict", "Message": "The idempotency key names a different sale.", "Fields": []}}
                terminal_offline:
                  value: {"Error": {"Code": "terminal_offline", "Message": "The terminal is not connected.", "Fields": []}}
                terminal_busy:
                  value: {"Error": {"Code": "terminal_busy", "Message": "The terminal is busy with another sale.", "Fields": []}}
                sale_not_refundable:
                  value: {"Error": {"Code": "sale_not_refundable", "Message": "The sale cannot be refunded here.", "Fields": []}}
                terminal_cannot_refund:
                  value: {"Error": {"Code": "terminal_cannot_refund", "Message": "The terminal has not said it takes refunds.", "Fields": []}}
        '413':
          description: >-
            `body_too_large`: the body is over 65,536 bytes. Nothing is created, and no part of the body is logged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                body_too_large:
                  value: {"Error": {"Code": "body_too_large", "Message": "The body is over 65,536 bytes.", "Fields": []}}
        '503':
          description: |
            - `store_unavailable`: the middleware's store did not answer, or a sale it holds could
              not be read. Retry with the same key, never a new one: usually nothing was created
              and the key is unspent, but a sale may have been committed with its answer lost,
              and the same key then answers that sale as it stands.
            - `edge_not_trusted`: behind the load balancer, the request did not come through
              a trusted edge. It is an edge fault and no verdict on the credential: retry on the
              normal backoff with the same key, never a new one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                store_unavailable:
                  value: {"Error": {"Code": "store_unavailable", "Message": "The store is not available. Retry.", "Fields": []}}
                edge_not_trusted:
                  value: {"Error": {"Code": "edge_not_trusted", "Message": "The request did not come through a trusted edge. Retry.", "Fields": []}}
  /v1/sales/{TransactionReference}:
    get:
      tags: [sales]
      operationId: readSale
      summary: Read a sale, holding the read while its result is open.
      description: >-
        A settled sale answers at once, and a pending sale, `PDNG`, or an unknown one, `UNKN`, holds the read until its result changes or `wait_seconds` runs out, then answers what it holds. A read held across the sale's deadline returns `UNKN` at that moment, and a read waiting on `UNKN` is answered as soon as it resolves. Read again after each answer until the result is `ACSP` or `RJCT`: a read changes nothing, so reading again is also how a POS recovers from a lost answer. A read is the caller's own: the register that made the sale, or the refund, reads it, under its own credential.
      parameters:
        - name: TransactionReference
          in: path
          required: true
          x-sent-by: pos
          description: The sale's `TransactionReference`, as the `202` gave it.
          schema:
            type: string
            pattern: '^sal_[0-9a-f]{32}$'
        - name: wait_seconds
          in: query
          required: false
          x-sent-by: pos
          description: >-
            How long to hold a read of a pending or unknown sale, in whole seconds, from 0 to 30. 25 is a good value.
          schema:
            type: integer
            minimum: 0
            maximum: 30
            default: 0
        - $ref: '#/components/parameters/MwRegister'
      responses:
        '200':
          description: >-
            The sale. `TransactionStatus` says where it stands, `StatusReasonInformation` why, and `PaymentReference` is `null` until it settles with one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sale'
              examples:
                approved:
                  summary: An approved card sale, with the terminal's references.
                  value: {"TransactionReference": "sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a", "MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "INV-1001", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "12.50", "AuthorisedAmount": "12.50"}, "TransactionStatus": "ACSP", "StatusReasonInformation": {"ResponseCode": "00", "AdditionalInformation": "APPROVED"}, "PaymentReference": {"Card": {"RetrievalReferenceNumber": "631012345678", "SystemTraceAuditNumber": "000123", "AuthorisationCode": "A1B2C3", "AcquirerPOIIdentification": "12345678", "AcquirerMerchantIdentification": "987654321", "RefundReference": "klujhadsc9ph87asd"}}}
                approved_over_npp:
                  summary: An approved PayTo sale, with NPP's references.
                  value: {"TransactionReference": "sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a", "MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "INV-1001", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "12.50", "AuthorisedAmount": "12.50"}, "TransactionStatus": "ACSP", "StatusReasonInformation": null, "PaymentReference": {"NPP": {"EndToEndIdentification": "INV-1001", "TransactionIdentification": "NPPTX0001", "MandateIdentification": "MNDT-0001"}}}
                declined:
                  summary: A declined sale.
                  value: {"TransactionReference": "sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a", "MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "INV-1001", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "12.50"}, "TransactionStatus": "RJCT", "StatusReasonInformation": {"Reason": "AG07", "ResponseCode": "05", "AdditionalInformation": "DECLINED"}, "PaymentReference": null}
                no_payment:
                  summary: A sale no payment was taken for otherwise, such as a cancel at the terminal.
                  value: {"TransactionReference": "sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a", "MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "INV-1001", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "12.50"}, "TransactionStatus": "RJCT", "StatusReasonInformation": {"Reason": "AB11"}, "PaymentReference": null}
                cancelled:
                  summary: A sale its terminal stopped, before its host, in answer to an abort.
                  value: {"TransactionReference": "sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a", "MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "INV-1001", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "12.50"}, "TransactionStatus": "RJCT", "StatusReasonInformation": {"Reason": "DS02"}, "PaymentReference": null}
                unknown:
                  summary: A sale the middleware has no word on by its deadline. A payment may have been taken.
                  value: {"TransactionReference": "sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a", "MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "INV-1001", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "12.50"}, "TransactionStatus": "UNKN", "StatusReasonInformation": null, "PaymentReference": null}
                refunded:
                  summary: An approved refund of part of a sale, with the references the host gave the refund.
                  value: {"TransactionType": "RFND", "TransactionReference": "sal_02a8f3c4d5e6f708192a3b4c5d6e7f80", "MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "CN-1001", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "6.25", "AuthorisedAmount": "6.25"}, "OriginalTransaction": {"TransactionReference": "sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a"}, "TransactionStatus": "ACSP", "StatusReasonInformation": {"ResponseCode": "00", "AdditionalInformation": "APPROVED"}, "PaymentReference": {"Card": {"RetrievalReferenceNumber": "631012345699", "AuthorisationCode": "R4F7D2"}}}
        '400':
          description: >-
            `invalid_wait`: `wait_seconds` is not an integer from 0 to 30, or is given twice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_wait:
                  value: {"Error": {"Code": "invalid_wait", "Message": "wait_seconds must be an integer from 0 to 30.", "Fields": []}}
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          description: |
            - `not_permitted`: the credential is good, and is not a register's.
            - `certificate_retired`: the client certificate presented is retired. Read again
              on the register's newer certificate, or on its newest, stop and tell a person.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_permitted:
                  value: {"Error": {"Code": "not_permitted", "Message": "The caller is not permitted to do this.", "Fields": []}}
                certificate_retired:
                  value: {"Error": {"Code": "certificate_retired", "Message": "The certificate presented is retired: a newer one of this identity is in use.", "Fields": []}}
        '404':
          description: >-
            `sale_not_found`: the middleware does not hold this id, and a sale another register made answers the same, so a caller learns nothing of another's sales. On an id the middleware gave you, that does not mean no sale happened: the sale passed retention and the middleware forgot it, so treat it as an unknown outcome: a payment may have been taken, and the cashier checks the terminal before another tender.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                sale_not_found:
                  value: {"Error": {"Code": "sale_not_found", "Message": "The middleware does not hold this sale.", "Fields": []}}
        '503':
          description: |
            - `store_unavailable`: the middleware's store did not answer, or the sale could not be
              read from it. It says nothing about the sale or its result, so it does not mean
              the middleware lacks the sale: read again.
            - `edge_not_trusted`: behind the load balancer, the request did not come through
              a trusted edge. It is an edge fault, and says nothing about the credential or
              the sale: read again on the normal backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                store_unavailable:
                  value: {"Error": {"Code": "store_unavailable", "Message": "The store is not available. Retry.", "Fields": []}}
                edge_not_trusted:
                  value: {"Error": {"Code": "edge_not_trusted", "Message": "The request did not come through a trusted edge. Retry.", "Fields": []}}
  /v1/sales/{TransactionReference}/abort:
    post:
      tags: [sales]
      operationId: abortSale
      summary: Ask the terminal to cancel a sale or a refund in flight.
      description: |
        Asks the sale's terminal to stop the payment, and answers at once: what the sale then
        settles as says what the terminal did.

        - `RJCT` with `Reason` `DS02`: the terminal stopped the payment before it reached its host,
          and the sale is cancelled: no payment was taken, and on a refund no refund was made.
        - `ACSP`: the abort came too late. The payment, or the refund, had reached its host, and was
          taken.
        - `RJCT` with any other `Reason`: no payment was taken, as on any read.
        - `UNKN`: as on any read, the cashier checks the terminal before another tender.

        An abort is the caller's own, as a read is: the register that made the sale aborts it, under
        its own credential. A sale is abortable while it holds its terminal: `PDNG`, or `UNKN`
        inside its terminal's hold, 300 seconds from the sale at the middleware's default settings.
        An abort is a message relayed, not a state, and moves no timer: the deadline and the hold
        run as they would without it, and the terminal stays claimed until its outcome or the end of
        its hold, so a new sale to it is refused `409 terminal_busy` until then.
      parameters:
        - name: TransactionReference
          in: path
          required: true
          x-sent-by: pos
          description: The sale's or refund's `TransactionReference`, as its create's `202` gave it.
          schema:
            type: string
            pattern: '^sal_[0-9a-f]{32}$'
        - $ref: '#/components/parameters/MwRegister'
      responses:
        '202':
          description: >-
            The abort is admitted, and a `TerminalAbort` is queued for the sale's terminal. The body is the sale as it stands, as a read answers it, `PDNG` or `UNKN`, and not the cancel: read the sale until it settles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sale'
              examples:
                pending:
                  summary: A pending sale, its abort sent to its terminal.
                  value: {"TransactionReference": "sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a", "MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "INV-1001", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "12.50"}, "TransactionStatus": "PDNG", "StatusReasonInformation": null, "PaymentReference": null}
                unknown_inside_its_hold:
                  summary: A sale past its deadline and inside its terminal's hold, its abort sent to its terminal.
                  value: {"TransactionReference": "sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a", "MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "INV-1001", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "12.50"}, "TransactionStatus": "UNKN", "StatusReasonInformation": null, "PaymentReference": null}
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          description: |
            Nothing was sent to the terminal.

            - `not_permitted`: the credential is good, and is not a register's.
            - `certificate_retired`: the client certificate presented is retired. Abort again
              on the register's newer certificate, or on its newest, stop and tell a person.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_permitted:
                  value: {"Error": {"Code": "not_permitted", "Message": "The caller is not permitted to do this.", "Fields": []}}
                certificate_retired:
                  value: {"Error": {"Code": "certificate_retired", "Message": "The certificate presented is retired: a newer one of this identity is in use.", "Fields": []}}
        '404':
          description: >-
            `sale_not_found`: the middleware does not hold this id for the caller, as a read answers it: an id it never issued, a sale past retention, or a sale another register made. Nothing was sent to the terminal, and on an id the middleware gave you, treat the sale as a read's `sale_not_found` says.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                sale_not_found:
                  value: {"Error": {"Code": "sale_not_found", "Message": "The middleware does not hold this sale.", "Fields": []}}
        '409':
          description: |
            The abort is refused, nothing was sent to the terminal, and the sale goes on as it was.

            - `sale_not_abortable`: the sale, or the refund, has ended and cannot be cancelled: it
              reads `ACSP` or `RJCT`, or `UNKN` because its terminal contradicted itself or its hold
              has ended, after which the terminal may be in another payment. Read the sale: its
              answer says how it ended, and `ACSP` means the abort came too late.
            - `terminal_cannot_abort`: the sale's terminal is connected and declared no `SSAB` in
              `Mw-Message-Functions` when it connected, so retrying does not help while that
              connection holds it. Have the cashier cancel at the terminal, then read the sale for
              the outcome the terminal sends.
            - `terminal_offline`: the sale's terminal has no current connection, or its queue of
              frames is full. Retry, or have the cashier cancel at the terminal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                sale_not_abortable:
                  value: {"Error": {"Code": "sale_not_abortable", "Message": "The sale has ended and cannot be cancelled.", "Fields": []}}
                terminal_cannot_abort:
                  value: {"Error": {"Code": "terminal_cannot_abort", "Message": "The terminal has not said it can cancel a sale.", "Fields": []}}
                terminal_offline:
                  value: {"Error": {"Code": "terminal_offline", "Message": "The terminal is not connected.", "Fields": []}}
        '411': {$ref: '#/components/responses/EdgeLengthRequired'}
        '503':
          description: |
            - `store_unavailable`: the middleware's store did not answer, or the sale could not be
              read from it. Nothing was sent to the terminal, and it says nothing about the sale
              or its result: abort again, or read the sale.
            - `edge_not_trusted`: behind the load balancer, the request did not come through
              a trusted edge. It is an edge fault, and says nothing about the credential or
              the sale: abort again on the normal backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                store_unavailable:
                  value: {"Error": {"Code": "store_unavailable", "Message": "The store is not available. Retry.", "Fields": []}}
                edge_not_trusted:
                  value: {"Error": {"Code": "edge_not_trusted", "Message": "The request did not come through a trusted edge. Retry.", "Fields": []}}
  /v1/health:
    get:
      tags: [health]
      operationId: health
      summary: Whether the middleware is serving.
      security: []
      responses:
        '200':
          description: The middleware is serving.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
              examples:
                ok:
                  value: {"Status": "ok", "Version": "0.0.0"}
  /v1/registers:
    post:
      tags: [registers]
      operationId: listRegister
      summary: List a register.
      description: >-
        A POS vendor's `admin`, the operator, or `onboarding`. With `SerialNumber` it is a device's register: it starts `listed`, and the middleware answers once with its `PairingCode`, five words. With none it is a server's register, which starts `active` and has no code.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterListing'
      responses:
        '201':
          description: The register, and a device's `PairingCode`, shown this once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterListed'
        '400':
          $ref: '#/components/responses/OperatorBodyRefused'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          $ref: '#/components/responses/NotPermitted'
        '413':
          $ref: '#/components/responses/OperatorBodyTooLarge'
        '503':
          $ref: '#/components/responses/OperatorStoreUnavailable'
    get:
      tags: [registers]
      operationId: readRegisters
      summary: Show the caller's registers.
      description: >-
        A POS vendor's `admin`, the operator, or `onboarding`. An `admin` sees its own registers, and the operator and `onboarding` every vendor's, a removed one among them, each with its vendor, its kind, its state, a device's serial, the store it sits at and, once it has held a certificate, its newest certificate's `NotAfter`. Never a code.
      responses:
        '200':
          description: The registers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterList'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          $ref: '#/components/responses/NotPermitted'
        '503':
          $ref: '#/components/responses/OperatorStoreUnavailable'
  /v1/registers/{RegisterIdentification}:
    parameters:
      - $ref: '#/components/parameters/RegisterIdentification'
    delete:
      tags: [registers]
      operationId: removeRegister
      summary: Remove a register.
      description: >-
        Its vendor's `admin`, or the operator. The register goes `removed`, each of its bindings ends, its code is cleared and its certificates are retired. No other caller removes a register: `removed` has no exit.
      responses:
        '200':
          description: The register, `removed`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Register'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          $ref: '#/components/responses/NotPermitted'
        '404':
          $ref: '#/components/responses/OperatorNotFound'
        '503':
          $ref: '#/components/responses/OperatorStoreUnavailable'
  /v1/registers/{RegisterIdentification}/pairing-code:
    parameters:
      - $ref: '#/components/parameters/RegisterIdentification'
    post:
      tags: [registers]
      operationId: issueRegisterPairingCode
      summary: Issue a register a fresh code, or re-pair it.
      description: >-
        Its vendor's `admin`, the operator, or `onboarding`, for a device's register. A fresh code, or on an `active` register a re-pair, as a terminal's. To `onboarding` this route gives a first code alone: a code for a register `listed` that has never held a certificate and holds no binding, and `403 not_permitted` for any other, with nothing written.
      responses:
        '201':
          description: The register and its new `PairingCode`, shown this once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterListed'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          $ref: '#/components/responses/NotPermitted'
        '404':
          $ref: '#/components/responses/OperatorNotFound'
        '411': {$ref: '#/components/responses/EdgeLengthRequired'}
        '503':
          $ref: '#/components/responses/OperatorStoreUnavailable'
  /v1/registers/{RegisterIdentification}/certificates:
    parameters:
      - $ref: '#/components/parameters/RegisterIdentification'
    get:
      tags: [registers]
      operationId: readRegisterCertificates
      summary: Show a register's certificates.
      description: >-
        The `admin` of the register's vendor, the operator, or `onboarding`. Each certificate of the register not past its `NotAfter`, ordered by `IssuedAt`, then `CertificateIdentification`.
      responses:
        '200':
          description: The certificates, `[]` where none is unexpired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateList'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          $ref: '#/components/responses/NotPermitted'
        '404':
          $ref: '#/components/responses/OperatorNotFound'
        '503':
          $ref: '#/components/responses/OperatorStoreUnavailable'
  /v1/enrol:
    post:
      tags: [certificates]
      operationId: enrol
      summary: Spend a pairing code for a first certificate.
      security: []
      description: >-
        No credential: the code is the credential, spent here by a terminal, a register's device or a vendor's server listed with a `PairingCode` for its first client certificate. `/docs/api/onboarding-device.md` § 6 walks a device's enrolment, and § The challenge, worked says how to compute the challenge its key is made with.
      requestBody:
        required: true
        description: The enrolment. At most 65,536 bytes.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Enrolment'
      responses:
        '200':
          description: The same certificate, to a repeat of an enrolment with the same code and key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrolmentIssued'
        '201':
          description: >-
            The certificate, the principal's id, and when to renew it. The code is spent, and the principal is now `paired`, `active` or `enrolled`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrolmentIssued'
        '400':
          description: |
            The body is refused, and each code means what it means on `POST /v1/sales`.

            - `invalid_json`: the body is not a JSON object.
            - `unknown_field`: the body holds a field this operation does not name, or a server's
              enrolment sends `AttestationChain`.
            - `missing_field`: a required field is absent. A device's five words sent with no
              `SerialNumber`, or with it `null`, are this, naming `SerialNumber`.
            - `invalid_field`: a field breaks its rule, or, behind a good code, the CSR's signature
              does not verify or its key is not P-256, which counts an attempt. A `SerialNumber`
              sent reads the code as a device's five words, so a server's code sent with a
              `SerialNumber` is this, naming `PairingCode`, before any row is read and with no
              attempt counted.
            - `body_unreadable`: the body could not be read to its end.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_json:
                  value: {"Error": {"Code": "invalid_json", "Message": "The body is not a JSON object.", "Fields": []}}
                unknown_field:
                  value: {"Error": {"Code": "unknown_field", "Message": "The body holds a field the contract does not define.", "Fields": ["AttestationChain"]}}
                missing_field:
                  value: {"Error": {"Code": "missing_field", "Message": "The body lacks a field the contract requires.", "Fields": ["CertificateSigningRequest"]}}
                invalid_field:
                  value: {"Error": {"Code": "invalid_field", "Message": "A field does not meet its rule in the contract.", "Fields": ["CertificateSigningRequest"]}}
                body_unreadable:
                  value: {"Error": {"Code": "body_unreadable", "Message": "The body could not be read.", "Fields": []}}
        '403':
          description: |
            Refused, and nothing is issued.

            - `code_not_valid`: the code is wrong, unknown, expired or spent, the serial is not the
              listing's, the principal is not `listed`, or its vendor is suspended, one code for
              every reason. A code no row holds counts nothing: a device's wrong serial or first
              word, or a server's wrong first 6 characters, finds no row.
            - `attestation_failed`: the device's chain fails a check of the chain, its root, its
              dates, revocation, the extension, the key, the hardware, the challenge or the boot
              state, or does not parse, or a device on a `live` middleware sent none. A middleware
              set to mark admits a device whose chain fails only checks it records, and one that
              sent none, and marks its certificate with those checks, or `chain_missing`
              (`DeviceAttestation`).
            - `app_identity_unknown`: the app the chain names is not registered for the vendor and
              the principal's role, or more than one app shares the key.
            - `model_not_allowed`: no row of the allowed list admits what the device attests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                code_not_valid:
                  value: {"Error": {"Code": "code_not_valid", "Message": "The pairing code is not valid.", "Fields": []}}
                attestation_failed:
                  value: {"Error": {"Code": "attestation_failed", "Message": "The device's key attestation does not pass.", "Fields": []}}
                app_identity_unknown:
                  value: {"Error": {"Code": "app_identity_unknown", "Message": "The app holding the key is not one registered for this device.", "Fields": []}}
                model_not_allowed:
                  value: {"Error": {"Code": "model_not_allowed", "Message": "The device is not of a model the allowed list admits.", "Fields": []}}
        '413':
          $ref: '#/components/responses/OperatorBodyTooLarge'
        '429':
          description: >-
            Sent by the edge in front of a hosted middleware, never by the middleware itself: more enrolments came from your address in a minute than the edge allows, and its body is the edge's, not an `Error`. The code was not read and no attempt is counted, so wait a minute, then send the same request again.
        '503':
          description: |
            No verdict on the code: nothing is written, no attempt is counted, and the code stays
            live, so retry on the normal backoff with the same code and the same key.

            - `store_unavailable`: the middleware's store did not answer.
            - `ca_unavailable`: the middleware could not sign the certificate.
            - `attestation_status_unavailable`: a device's enrolment on a `live` middleware, which
              holds no attestation status list fresh enough to check the chain for revocation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                store_unavailable:
                  value: {"Error": {"Code": "store_unavailable", "Message": "The store is not available. Retry.", "Fields": []}}
                ca_unavailable:
                  value: {"Error": {"Code": "ca_unavailable", "Message": "The certificate authority could not sign. Retry.", "Fields": []}}
                attestation_status_unavailable:
                  value: {"Error": {"Code": "attestation_status_unavailable", "Message": "The attestation status list is not current. Retry.", "Fields": []}}
  /v1/certificates/self:
    get:
      tags: [certificates]
      operationId: readOwnCertificate
      summary: The daily check of the certificate presented.
      security:
        - mutualTLS: []
      description: >-
        Any certificate, on itself, once a day: the middleware answers the certificate's `NotAfter`, its `RenewFrom`, day 15 of its life, and `RenewNow`, so a holder's own clock decides nothing. `/docs/api/onboarding-device.md` § 9 says when to renew, and how a refusal of the check is read.
      responses:
        '200':
          description: The certificate's dates, and whether to renew it now.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateStatus'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          $ref: '#/components/responses/NotPermitted'
        '503':
          $ref: '#/components/responses/OperatorStoreUnavailable'
  /v1/certificates/challenge:
    post:
      tags: [certificates]
      operationId: issueRenewalChallenge
      summary: A challenge for a device's next key.
      security:
        - mutualTLS: []
      description: >-
        A challenge for a device's next key, a terminal's or a register's, valid 10 minutes and for one renewal: a server renews without one, and asking is `403 not_permitted`. `/docs/api/onboarding-device.md` § 10 says how to make the key with it and renew.
      responses:
        '201':
          description: The challenge, and how long it is valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChallengeIssued'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          $ref: '#/components/responses/NotPermitted'
        '411': {$ref: '#/components/responses/EdgeLengthRequired'}
        '503':
          $ref: '#/components/responses/OperatorStoreUnavailable'
  /v1/certificates/renew:
    post:
      tags: [certificates]
      operationId: renewCertificate
      summary: Renew the certificate presented, with a new key.
      security:
        - mutualTLS: []
      description: >-
        Any certificate, from its `RenewFrom`, with a new key: the middleware runs enrolment's checks with the caller's certificate where the code was, and answers as enrolment does. `/docs/api/onboarding-device.md` § 10 says when to use the new certificate and delete the old key, and how long the old one stays good.
      requestBody:
        required: true
        description: The renewal. At most 65,536 bytes.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Renewal'
      responses:
        '200':
          description: The same certificate, to a repeat of a renewal with the same key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrolmentIssued'
        '201':
          description: The new certificate, the principal's id, and when to renew it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrolmentIssued'
        '400':
          description: |
            The body is refused, nothing is issued, and each code means what it means on
            `POST /v1/sales`.

            - `invalid_json`: the body is not a JSON object.
            - `unknown_field`: the body holds a field this operation does not name, or a server's
              renewal sends `AttestationChain`.
            - `missing_field`: a required field is absent.
            - `invalid_field`: a field breaks its rule, the CSR's signature does not verify or its
              key is not P-256, or its key is one the principal has used before.
            - `body_unreadable`: the body could not be read to its end.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_json:
                  value: {"Error": {"Code": "invalid_json", "Message": "The body is not a JSON object.", "Fields": []}}
                unknown_field:
                  value: {"Error": {"Code": "unknown_field", "Message": "The body holds a field the contract does not define.", "Fields": ["AttestationChain"]}}
                missing_field:
                  value: {"Error": {"Code": "missing_field", "Message": "The body lacks a field the contract requires.", "Fields": ["CertificateSigningRequest"]}}
                invalid_field:
                  value: {"Error": {"Code": "invalid_field", "Message": "A field does not meet its rule in the contract.", "Fields": ["CertificateSigningRequest"]}}
                body_unreadable:
                  value: {"Error": {"Code": "body_unreadable", "Message": "The body could not be read.", "Fields": []}}
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          description: |
            Refused, and nothing is issued: the current certificate stays as it was.

            - `not_permitted`: the principal is not `paired`, `active` or `enrolled`, or its vendor
              is not `active`, so a suspended vendor's certificate cannot renew.
            - `certificate_retired`: the certificate presented is retired, or set to retire at the
              end of an overlap, because a newer one of the identity is in use. Renew on the newer
              one, or on the holder's newest, stop and tell a person: something else holds a newer
              certificate of this identity.
            - `challenge_not_valid`: a device's chain was made with no challenge of this
              certificate's that is live: ask a new challenge, and make a new key with it.
            - `attestation_failed`, `app_identity_unknown` and `model_not_allowed`: the device's
              chain is refused as at enrolment. The current certificate stays good until its
              `NotAfter`, and the middleware writes a `WARNING` naming the device.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_permitted:
                  value: {"Error": {"Code": "not_permitted", "Message": "The caller is not permitted to do this.", "Fields": []}}
                certificate_retired:
                  value: {"Error": {"Code": "certificate_retired", "Message": "The certificate presented is retired: a newer one of this identity is in use.", "Fields": []}}
                challenge_not_valid:
                  value: {"Error": {"Code": "challenge_not_valid", "Message": "The key was not made with a live challenge of this certificate's. Ask a new one.", "Fields": []}}
                attestation_failed:
                  value: {"Error": {"Code": "attestation_failed", "Message": "The device's key attestation does not pass.", "Fields": []}}
                app_identity_unknown:
                  value: {"Error": {"Code": "app_identity_unknown", "Message": "The app holding the key is not one registered for this device.", "Fields": []}}
                model_not_allowed:
                  value: {"Error": {"Code": "model_not_allowed", "Message": "The device is not of a model the allowed list admits.", "Fields": []}}
        '409':
          description: >-
            `renewal_not_due`: the certificate is before its `RenewFrom`, and nothing is issued. Keep using it, and renew once the daily check answers `RenewNow` `true`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                renewal_not_due:
                  value: {"Error": {"Code": "renewal_not_due", "Message": "The certificate is not due for renewal yet: its daily check says from when.", "Fields": []}}
        '413':
          $ref: '#/components/responses/OperatorBodyTooLarge'
        '429':
          description: >-
            `renewal_rate`: this identity was issued 5 certificates in the last 24 hours, so the middleware writes a `WARNING`: a second renewer is the best sign of a fork. Keep the current certificate and renew later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                renewal_rate:
                  value: {"Error": {"Code": "renewal_rate", "Message": "This identity was issued 5 certificates in the last 24 hours. Retry later.", "Fields": []}}
        '503':
          description: |
            No verdict on the certificate: nothing is issued and a challenge is not spent, so retry
            on the normal backoff with the same key.

            - `store_unavailable`: the middleware's store did not answer.
            - `ca_unavailable`: the middleware could not sign the certificate.
            - `attestation_status_unavailable`: a device's renewal on a `live` middleware, which
              holds no attestation status list fresh enough to check the chain for revocation.
            - `edge_not_trusted`: behind the load balancer, the request did not come through a
              trusted edge. It is an edge fault, and the certificate is not in question.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                store_unavailable:
                  value: {"Error": {"Code": "store_unavailable", "Message": "The store is not available. Retry.", "Fields": []}}
                ca_unavailable:
                  value: {"Error": {"Code": "ca_unavailable", "Message": "The certificate authority could not sign. Retry.", "Fields": []}}
                attestation_status_unavailable:
                  value: {"Error": {"Code": "attestation_status_unavailable", "Message": "The attestation status list is not current. Retry.", "Fields": []}}
                edge_not_trusted:
                  value: {"Error": {"Code": "edge_not_trusted", "Message": "The request did not come through a trusted edge. Retry.", "Fields": []}}
  /v1/links:
    post:
      tags: [links]
      operationId: askToLink
      summary: Ask to link this register to a terminal of a store.
      parameters:
        - $ref: '#/components/parameters/MwRegister'
      description: >-
        A register, or a `pos` server naming one in `Mw-Register`, asks to link at the store its `MerchantIdentification` names: each `paired` terminal there with no binding shows a different pair of two words, and a POS never sees a word. `/docs/api/linking.md` § 1 says who may ask and when, and § 2 which terminals are asked and how the words are picked.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkRequest'
      responses:
        '201':
          description: >-
            The request, open. Each terminal asked shows its word until it links, a word is refused, or `ExpiresInSeconds` pass.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkOpened'
        '400':
          $ref: '#/components/responses/OperatorBodyRefused'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          $ref: '#/components/responses/NotPermitted'
        '409':
          description: |
            Nothing is written.

            - `link_in_progress`: a request is already open at this store, or for this
              register. Try again in a minute.
            - `no_terminal_to_link`: no terminal of the store is `paired` with no binding.
              Check the terminal is paired and connected, and end a binding it holds first.
            - `too_many_terminals`: more terminals of the store are `paired` with no binding
              than one request can ask, 523,776: each is shown a different pair of two
              words, and never one pair both ways round. Have the store's fleet owner bind or
              remove terminals of the store, and ask again.
            - `register_in_other_store`: the register is bound at another store. End its
              bindings there, at `DELETE /v1/links/{POIIdentification}`, and ask again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                link_in_progress:
                  value: {"Error": {"Code": "link_in_progress", "Message": "A request to link is open at this store or for this register. Retry in a minute.", "Fields": []}}
                no_terminal_to_link:
                  value: {"Error": {"Code": "no_terminal_to_link", "Message": "No terminal of this store is paired and unbound.", "Fields": []}}
                too_many_terminals:
                  value: {"Error": {"Code": "too_many_terminals", "Message": "More terminals of this store are paired and unbound than a request can ask.", "Fields": []}}
                register_in_other_store:
                  value: {"Error": {"Code": "register_in_other_store", "Message": "The register is linked at another store until its bindings end.", "Fields": []}}
        '413':
          $ref: '#/components/responses/OperatorBodyTooLarge'
        '429':
          description: >-
            `link_rate`: the caller's vendor asked 10 times at this store in the last hour, or typed 3 wrong pairs there in the last 24 hours, whichever of its registers asked, and the middleware writes a `WARNING`. Ask later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                link_rate:
                  value: {"Error": {"Code": "link_rate", "Message": "This vendor has asked to link at this store too often. Retry later.", "Fields": []}}
        '503':
          $ref: '#/components/responses/OperatorStoreUnavailable'
  /v1/links/{Identification}:
    get:
      tags: [links]
      operationId: readLink
      summary: How many terminals a request asked, and how many show their word.
      parameters:
        - name: Identification
          in: path
          required: true
          x-sent-by: pos
          description: >-
            The request, by the `LinkIdentification` its `201` gave. On `DELETE`, this path names a terminal instead.
          schema:
            type: string
            pattern: '^lnk_[0-9a-f]{32}$'
        - $ref: '#/components/parameters/MwRegister'
      description: >-
        The register that asked, alone, reads the request's counts: any other reads the request as an id no row holds, `404 not_found`. `/docs/api/linking.md` § 3 says what the counts tell a POS, and when a word is shown.
      responses:
        '200':
          description: The request's counts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkStatus'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          $ref: '#/components/responses/NotPermitted'
        '404':
          $ref: '#/components/responses/OperatorNotFound'
        '503':
          $ref: '#/components/responses/OperatorStoreUnavailable'
    delete:
      tags: [links]
      operationId: endLink
      summary: Unlink a terminal from this register.
      parameters:
        - name: Identification
          in: path
          required: true
          x-sent-by: pos
          description: >-
            The terminal bound to the caller, by its `POIIdentification`. On `GET`, this path names a request instead.
          schema:
            type: string
            pattern: '^[A-Za-z0-9_-]{1,64}$'
        - $ref: '#/components/parameters/MwRegister'
      description: >-
        The register itself, its unlink button, ends the caller's binding to the terminal: its next sale naming the terminal is refused, and a sale already in flight is untouched. A terminal not bound to the caller is `404 not_found`, and `/docs/api/linking.md` § Unlinking says what else ends a binding.
      responses:
        '204':
          description: Unlinked. No body.
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          $ref: '#/components/responses/NotPermitted'
        '404':
          $ref: '#/components/responses/OperatorNotFound'
        '503':
          $ref: '#/components/responses/OperatorStoreUnavailable'
  /v1/links/{LinkIdentification}/word:
    parameters:
      - $ref: '#/components/parameters/LinkIdentification'
    post:
      tags: [links]
      operationId: submitLinkWord
      summary: Link to the terminal showing this pair of words.
      parameters:
        - $ref: '#/components/parameters/MwRegister'
      description: >-
        The register that asked, with the `Word` the staff member reads off the terminal in their hand: a pair a terminal of this request showed, in the order shown, binds the register to that terminal, and a pair this request does not hold ends it. `/docs/api/linking.md` § 4 says how the pair is typed and what is refused before the store is asked, and § 5 what a binding does.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkWordSubmission'
      responses:
        '200':
          description: Linked; the terminal bound to the caller, and its store.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkBound'
        '400':
          $ref: '#/components/responses/OperatorBodyRefused'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          description: |
            Not linked.

            - `link_word_unknown`: no terminal of this request showed the pair, in that order. The
              request has ended, every terminal clears, and the wrong pair counts toward the
              vendor's limit at the store, so ask again.
            - `not_permitted`: the register or its vendor is not `active`, or the store is not
              `onboarding` or `live` with an `active` owner, or does not accept the vendor, read
              again at the word, and the request has ended; or the credential is not a register's.
            - `certificate_retired`: the client certificate presented is retired. Send the word
              again on the register's newer certificate, or on its newest, stop and tell a person.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                link_word_unknown:
                  value: {"Error": {"Code": "link_word_unknown", "Message": "The word is not one a terminal of this request showed. The request has ended.", "Fields": []}}
                not_permitted:
                  value: {"Error": {"Code": "not_permitted", "Message": "The caller is not permitted to do this.", "Fields": []}}
                certificate_retired:
                  value: {"Error": {"Code": "certificate_retired", "Message": "The certificate presented is retired: a newer one of this identity is in use.", "Fields": []}}
        '404':
          $ref: '#/components/responses/OperatorNotFound'
        '409':
          description: >-
            `register_in_other_store`: the register was bound at another store since it asked, and the request has ended. End the register's bindings there, and ask again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                register_in_other_store:
                  value: {"Error": {"Code": "register_in_other_store", "Message": "The register is linked at another store until its bindings end.", "Fields": []}}
        '410':
          description: >-
            `link_expired`: the request has ended: past its `ExpiresInSeconds`, closed by a wrong pair or a refusal, or its binding ended since. Ask again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                link_expired:
                  value: {"Error": {"Code": "link_expired", "Message": "The request to link has ended. Ask again.", "Fields": []}}
        '413':
          $ref: '#/components/responses/OperatorBodyTooLarge'
        '503':
          $ref: '#/components/responses/OperatorStoreUnavailable'
  /v1/register/terminals:
    get:
      tags: [links]
      operationId: readRegisterTerminals
      summary: The terminals bound to this register.
      parameters:
        - $ref: '#/components/parameters/MwRegister'
      description: >-
        A register, or a `pos` server naming one, reads each terminal bound to it, with its state, whether it is connected and whether a sale holds it. `/docs/api/linking.md` § The register's terminals says what each field means, and that `Connected` is for a screen, not a gate.
      responses:
        '200':
          description: The caller's terminals.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterTerminalList'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          $ref: '#/components/responses/NotPermitted'
        '503':
          $ref: '#/components/responses/OperatorStoreUnavailable'
components:
  securitySchemes:
    sandboxKey:
      type: http
      scheme: bearer
      description: >-
        A sandbox key, `sbx_` then 43 base64url characters, sent as `Authorization: Bearer`. It works in the sandbox alone, and its scope decides what it reaches: `pos` a register's sales and reads and its vendor's terminal connections, `admin` the Operator API inside its own vendor, `operator` FUNDiMO's routes, and `onboarding` the onboarding routes for every vendor, FUNDiMO's onboarding team's.
    mutualTLS:
      type: mutualTLS
      description: >-
        A client certificate from the middleware's own CA, presented at the TLS handshake with the issuing certificate beside it, as `CertificateChain` gave them, and never with an `Authorization` header. Its one SAN, a SPIFFE URI, names the environment, the role, `terminal`, `register`, `server` or `operator`, and the id, and a `server` certificate's scope decides what it reaches as a sandbox key's does.
  parameters:
    RegisterIdentification:
      name: RegisterIdentification
      in: path
      required: true
      x-sent-by: vendor
      description: A register, by the id the middleware issued it when it was listed.
      schema:
        type: string
        pattern: '^reg_[0-9a-f]{32}$'
    LinkIdentification:
      name: LinkIdentification
      in: path
      required: true
      x-sent-by: pos
      description: A request to link, by the `LinkIdentification` its `201` gave.
      schema:
        type: string
        pattern: '^lnk_[0-9a-f]{32}$'
    MwRegister:
      name: Mw-Register
      in: header
      required: false
      x-sent-by: pos
      description: >-
        The register a vendor's `pos` server acts for, by its `RegisterIdentification`: a register of the server's own vendor, listed with no serial. Required of a `pos` server on this route, sent once, and a `pos` server that leaves it out, sends it twice or names any other register is `403 not_permitted`; a register's own certificate needs none and may name only itself, and a sandbox `pos` key names its register already.
      schema:
        type: string
        pattern: '^reg_[0-9a-f]{32}$'
  responses:
    Unauthorised:
      description: |
        The credential is missing or not acceptable, refused before the body is read or a key
        looked up, so this request did nothing and its refusal says nothing of a sale an earlier
        send made: if the request retried a sale whose answer was lost, fix the credential and send
        the sale again with the same `IdempotencyKey` from the same register, never a new one.

        - `certificate_required`: no credential came. A holder with no certificate for the
          route enrols first, with `POST /v1/enrol`.
        - `certificate_invalid`: an `Authorization` header of another scheme, a token of no
          form the middleware issues, two `Authorization` headers, a client certificate beside an
          `Authorization` header, or a client certificate no row holds.
        - `certificate_expired`: the client certificate is past its `NotAfter`. A holder that
          meets it re-enrols with a new code.
        - `sandbox_key_on_live`: a sandbox key sent to a `live` middleware, which refuses every
          one before any lookup.
        - `sandbox_key_invalid`: the sandbox key is malformed, unknown or retired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            certificate_required:
              value: {"Error": {"Code": "certificate_required", "Message": "This route needs a credential, and none came.", "Fields": []}}
            certificate_invalid:
              value: {"Error": {"Code": "certificate_invalid", "Message": "The credential presented is not acceptable.", "Fields": []}}
            sandbox_key_on_live:
              value: {"Error": {"Code": "sandbox_key_on_live", "Message": "A sandbox key is accepted in the sandbox alone.", "Fields": []}}
            sandbox_key_invalid:
              value: {"Error": {"Code": "sandbox_key_invalid", "Message": "The sandbox key is malformed, unknown or retired.", "Fields": []}}
            certificate_expired:
              value: {"Error": {"Code": "certificate_expired", "Message": "The certificate presented has expired.", "Fields": []}}
    NotPermitted:
      description: |
        Nothing was done.

        - `not_permitted`: the credential is good, and this route refuses it: a credential of a
          scope or a role the route does not take, `operator` asked for by anyone but the operator,
          a write by a suspended vendor, a role the vendor does not hold, a move the object's state
          does not allow, or an act held back from `onboarding`: a terminal's removal, or a code for
          a device that is not `listed`, has held a certificate or holds a binding. One code answers
          every reason.
        - `certificate_retired`: the client certificate presented is retired, because a newer one of
          the identity is in use. Retry on the newer one, and on the holder's newest, stop and tell
          a person: something else holds a newer certificate of this identity.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            not_permitted:
              value: {"Error": {"Code": "not_permitted", "Message": "The caller is not permitted to do this.", "Fields": []}}
            certificate_retired:
              value: {"Error": {"Code": "certificate_retired", "Message": "The certificate presented is retired: a newer one of this identity is in use.", "Fields": []}}
    OperatorNotFound:
      description: >-
        `not_found`: no row holds this id, or the caller may not see it. The two answer the same, so a caller learns nothing of another vendor's objects.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            not_found:
              value: {"Error": {"Code": "not_found", "Message": "Nothing is served at this path.", "Fields": []}}
    OperatorBodyRefused:
      description: |
        The body is refused, and nothing was done.

        - `invalid_json`: the body is not a JSON object.
        - `unknown_field`: the body holds a field this operation does not name.
        - `missing_field`: a required field is absent.
        - `invalid_field`: a field breaks its rule, a required field sent as `null` included.
        - `body_unreadable`: the body could not be read to its end, such as a chunked body that
          breaks off. `Error.Fields` is empty.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalid_json:
              value: {"Error": {"Code": "invalid_json", "Message": "The body is not a JSON object.", "Fields": []}}
            unknown_field:
              value: {"Error": {"Code": "unknown_field", "Message": "The body holds a field the contract does not define.", "Fields": ["Note"]}}
            missing_field:
              value: {"Error": {"Code": "missing_field", "Message": "The body lacks a field the contract requires.", "Fields": ["SerialNumber"]}}
            invalid_field:
              value: {"Error": {"Code": "invalid_field", "Message": "A field does not meet its rule in the contract.", "Fields": ["Scope"]}}
            body_unreadable:
              value: {"Error": {"Code": "body_unreadable", "Message": "The body could not be read.", "Fields": []}}
    OperatorBodyTooLarge:
      description: >-
        `body_too_large`: the body is over 65,536 bytes. Nothing was done, and no part of the body is logged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    EdgeLengthRequired:
      description: 'Sent by the edge in front of a hosted middleware, never by the middleware itself, to a `POST` with no body and no `Content-Length` over HTTP/1.1: its body is the edge''s, not an `Error`, and nothing was read. Send the same request again with `Content-Length: 0`.'
    OperatorStoreUnavailable:
      description: |
        No verdict on the caller.

        - `store_unavailable`: the middleware's store did not answer, while it looked up the
          credential or did the work. A write's commit may have landed with its answer lost,
          so read the object back before doing it again.
        - `edge_not_trusted`: behind the load balancer, the request did not come through a
          trusted edge. It is an edge fault, and the caller's certificate is not in
          question: retry on the normal backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            store_unavailable:
              value: {"Error": {"Code": "store_unavailable", "Message": "The store is not available. Retry.", "Fields": []}}
            edge_not_trusted:
              value: {"Error": {"Code": "edge_not_trusted", "Message": "The request did not come through a trusted edge. Retry.", "Fields": []}}
  schemas:
    Amount:
      type: string
      pattern: '^(([0-9]|[1-9][0-9]{1,6})\.[0-9]{2}|10000000\.00)$'
      description: >-
        An amount: a JSON string in decimal major units, with a dot and exactly two fraction digits, from `0.00` to `10000000.00`, such as `"12.50"`, never a JSON number and never negative, a sign being a separate field where one exists. The middleware reads it as integer cents, never as a float, and writes it back as it arrived.
      examples: ['12.50']
    SaleRequest:
      type: object
      additionalProperties: false
      required: [MerchantIdentification, POIIdentification, SaleReferenceIdentification, IdempotencyKey, TransactionDetails]
      if:
        properties:
          TransactionType:
            const: RFND
        required: [TransactionType]
      then:
        required: [OriginalTransaction]
        properties:
          OriginalTransaction:
            type: object
      else:
        properties:
          OriginalTransaction:
            type: 'null'
      description: >-
        A sale, as a POS sends it to `POST /v1/sales`. Every string is ASCII with a stated length, and a field this schema does not name is refused: a refusal's `Error.Fields` names every field of its class, at any depth, at most 32, as paths such as `TransactionDetails.SaleItem[0].ProductDescription`. No string in a sale may hold card, bank or personal data, and the middleware cannot detect them: `SaleReferenceIdentification`, `ProductCode` and `SerialNumber` accept a whole card number, `EANUPC` and `GTIN` one of up to 14 digits, `CashierIdentification` one of up to 12, and `ProductDescription`, at most 8 digits, half of one, so a whole card number cannot fit in one item's name, though one fits across two items. Such a value is accepted and logged as sent, and `SaleReferenceIdentification`, `ProductDescription` and `CashierIdentification` go on to the terminal, where a customer may read it.
      properties:
        TransactionType:
          type: [string, 'null']
          enum: [CRDP, RFND, null]
          x-sent-by: pos
          description: >-
            `CRDP`, a sale, or `RFND`, a refund of `TotalAmount` against the sale `OriginalTransaction` names, and any other value is `invalid_field`. Absent is `CRDP`, so a sale need not send it.
        OriginalTransaction:
          type: [object, 'null']
          additionalProperties: false
          required: [TransactionReference]
          x-sent-by: pos
          description: >-
            The sale to refund, an object of one key: required with `RFND`, where absent or `null` is `missing_field`, and `invalid_field` with `CRDP` or with no `TransactionType`. The sale must be one the middleware can refund here, or the refund is `409 sale_not_refundable`.
          properties:
            TransactionReference:
              type: string
              pattern: '^sal_[0-9a-f]{32}$'
              x-sent-by: pos
              description: >-
                The sale to refund, by the id the middleware gave it, `sal_` then 32 lowercase hex characters, never the POS's own reference, as its `202` gave it.
        MerchantIdentification:
          type: string
          pattern: '^[A-Za-z0-9_-]{1,64}$'
          x-sent-by: pos
          description: >-
            The merchant: the store's own `MerchantIdentification`, `mid_` then 8 characters, or an accepted alias of it for the caller's vendor.
        POIIdentification:
          type: string
          pattern: '^[A-Za-z0-9_-]{1,64}$'
          x-sent-by: pos
          description: The terminal to use, by the id it connects with.
        SaleReferenceIdentification:
          type: string
          pattern: '^[A-Za-z0-9._:/#-]{1,64}$'
          x-sent-by: pos
          description: The POS's own reference, such as an invoice number, sent on to the terminal.
        IdempotencyKey:
          type: string
          pattern: '^[A-Za-z0-9._:/-]{8,64}$'
          x-sent-by: pos
          description: >-
            The POS's key for this sale, so a retry after a lost answer cannot make a second sale. Its scope is the register that sends the sale, which its `pos` key names, so a retry goes out from the same register. Its lifetime is the sale's: once the middleware forgets the sale, 24 hours after it stopped being pending by default, the key starts a new sale. A retry sends the same sale under the same key, the same items in the same order, or it is `idempotency_conflict`: key order, whitespace and escapes do not count, and neither do `CreationDateTime`, which a retry restamps, and `CashierIdentification`, so the sale keeps its first `CreationDateTime` and `CashierIdentification`.
        CreationDateTime:
          type: [string, 'null']
          maxLength: 35
          pattern: '^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]{1,9})?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])$'
          x-sent-by: pos
          description: >-
            The POS clock, as it states it, in RFC 3339, its shape checked and never its truth: `2020-01-01T00:00:00+10:00` and `2026-02-30T00:00:00Z` both pass. The middleware logs it unchanged and uses it for nothing: no ordering, no deadline and no decision.
        CashierIdentification:
          type: [string, 'null']
          allOf:
            - pattern: '^[A-Za-z0-9._:/#-]{1,35}$'
            - pattern: '^[^0-9]*([0-9][^0-9]*){0,12}$'
          x-sent-by: pos
          description: >-
            The POS's identifier for the user of the POS who made the sale or the refund, such as a staff number, never the person's name, email address or phone number. It goes on to the terminal, and no answer carries it.
        TransactionDetails:
          $ref: '#/components/schemas/TransactionDetails'
          x-sent-by: pos
          description: The amount, its currency, and the basket.
      examples:
        - {"MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "INV-1001", "IdempotencyKey": "b8a1f5a0-3c1e-4c52-9d3e-0a4d7f1e6c11", "CreationDateTime": "2026-11-06T15:12:33+11:00", "CashierIdentification": "STAFF-0042", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "12.50", "DetailedAmount": {"ValueAddedTax": "1.14"}, "SaleItem": [{"ProductDescription": "Flat white", "ProductCode": "FW-2", "ProductQuantity": 2, "UnitPrice": "6.25", "ProductAmount": "12.50", "ValueAddedTax": "1.14"}]}}
    TransactionDetails:
      type: object
      additionalProperties: false
      required: [Currency, TotalAmount]
      description: >-
        A sale's amount, its currency, and its basket. `TotalAmount` is what the customer pays: `AmountGoodsAndServices` plus `ValueAddedTax`, less `Rebate`, plus `Surcharge`, and each `ProductAmount` is its line after its discount and including its tax, so the items sum to `TotalAmount` less `Surcharge`. That is stated and never checked: a POS whose items do not add up shows the customer a mismatch, and the middleware does not catch it.
      properties:
        Currency:
          type: string
          enum: [AUD]
          x-sent-by: pos
          description: Exactly `AUD`. It governs every amount in the sale.
        TotalAmount:
          allOf:
            - $ref: '#/components/schemas/Amount'
            - not:
                const: '0.00'
          x-sent-by: pos
          description: >-
            What the customer pays and the terminal charges, from `0.01` to `10000000.00`. The items never change it.
        DetailedAmount:
          anyOf:
            - $ref: '#/components/schemas/DetailedAmount'
            - type: 'null'
          x-sent-by: pos
          description: >-
            Optional: the basket's header. It stays in the middleware, and an empty one reads as absent.
        SaleItem:
          type: [array, 'null']
          maxItems: 100
          items:
            $ref: '#/components/schemas/SaleItem'
          x-sent-by: pos
          description: >-
            Optional, up to 100, and an empty list reads as absent. The items travel to the terminal with the instruction, which shows them if it can and the amount alone if it cannot, so a sale with no items is complete. Item order counts.
    DetailedAmount:
      type: object
      additionalProperties: false
      description: >-
        The basket's header. Every member is optional and an amount, and all but `ValueAddedTax` can exceed `TotalAmount`: goods of `100.00` with tax of `10.00` and a rebate of `30.00` total `80.00`.
      properties:
        AmountGoodsAndServices:
          anyOf:
            - $ref: '#/components/schemas/Amount'
            - type: 'null'
          x-sent-by: pos
          description: Goods and services before tax.
        ValueAddedTax:
          anyOf:
            - $ref: '#/components/schemas/Amount'
            - type: 'null'
          x-sent-by: pos
          description: >-
            The sale's tax, which is GST: the middleware computes no tax. `ValueAddedTax` is at most `TotalAmount`: the middleware refuses one over it as `invalid_field`, a rule this schema cannot state.
        Rebate:
          anyOf:
            - $ref: '#/components/schemas/Amount'
            - type: 'null'
          x-sent-by: pos
          description: The discount, already taken off `TotalAmount`, written as a positive amount.
        Surcharge:
          anyOf:
            - $ref: '#/components/schemas/Amount'
            - type: 'null'
          x-sent-by: pos
          description: >-
            The store's own surcharge on the bill, such as 15% on a public holiday, which the POS added to `TotalAmount` before it sent the sale: the middleware holds no surcharge setting and computes no amount, and a terminal adds nothing, not this surcharge again and none of its own. Write it without its tax, as `AmountGoodsAndServices` is, and put its GST inside `ValueAddedTax`: a bill of `50.00` with 15% on a public holiday is a `TotalAmount` of `57.50`, written as `AmountGoodsAndServices` `45.45`, `ValueAddedTax` `5.23` and `Surcharge` `6.82`.
      examples:
        - {"AmountGoodsAndServices": "100.00", "ValueAddedTax": "10.00", "Rebate": "30.00"}
    SaleItem:
      type: object
      additionalProperties: false
      required: [ProductDescription, ProductQuantity, UnitPrice, ProductAmount]
      description: >-
        One line of the basket. `ProductDescription`, `ProductQuantity`, `UnitPrice`, `ProductAmount` and any sign the POS sent go on to the terminal, and the rest stays in the middleware.
      properties:
        ProductDescription:
          type: string
          minLength: 1
          maxLength: 40
          allOf:
            - pattern: '^[A-Za-z0-9.,''&()/+%#-]([A-Za-z0-9 .,''&()/+%#-]{0,38}[A-Za-z0-9.,''&()/+%#-])?$'
            - pattern: '^[^0-9]*([0-9][^0-9]*){0,8}$'
          x-sent-by: pos
          description: >-
            The name a terminal shows: 1 to 40 characters, ASCII letters, digits, space and `. , ' & ( ) / + % # -`, with no leading or trailing space, and at most 8 digits in total, such as `Fish & chips` or `1/2 Chicken`. `Café` is sent as `Cafe`, and a POS shortens a name that will not fit, or sends the sale with no items: `SaleItem` is optional, so a name never has to fail a sale.
        ProductQuantity:
          type: integer
          minimum: 1
          maximum: 100000
          x-sent-by: pos
          description: >-
            A JSON integer from 1 to 100,000, written as an integer: `2`, never `2.0` or `2e0`, which are `invalid_field`, though a schema validator counts them as integers.
        UnitPrice:
          $ref: '#/components/schemas/Amount'
          x-sent-by: pos
          description: The price of one unit.
        UnitPriceSign:
          type: [boolean, 'null']
          x-sent-by: pos
          description: >-
            The unit price's sign: `false` makes the price negative, for a discount line, and absent means plus.
        ProductAmount:
          $ref: '#/components/schemas/Amount'
          x-sent-by: pos
          description: The line's total, after its discount and including its tax.
        ProductAmountSign:
          type: [boolean, 'null']
          x-sent-by: pos
          description: The line total's sign, read as `UnitPriceSign` is.
        ProductCode:
          type: [string, 'null']
          pattern: '^[A-Za-z0-9._:/#-]{1,64}$'
          x-sent-by: pos
          description: The item's product code, optional, so a named item with no code can be shown.
        ValueAddedTax:
          anyOf:
            - $ref: '#/components/schemas/Amount'
            - type: 'null'
          x-sent-by: pos
          description: The tax inside this line's `ProductAmount`.
        DiscountAmount:
          anyOf:
            - $ref: '#/components/schemas/Amount'
            - type: 'null'
          x-sent-by: pos
          description: The discount already taken off this line's `ProductAmount`.
        EANUPC:
          type: [string, 'null']
          pattern: '^[0-9]{8,14}$'
          x-sent-by: pos
          description: The item's European Article Number or Universal Product Code, 8 to 14 digits.
        GTIN:
          type: [string, 'null']
          pattern: '^[0-9]{8,14}$'
          x-sent-by: pos
          description: The item's Global Trade Item Number, 8 to 14 digits.
        SerialNumber:
          type: [string, 'null']
          pattern: '^[A-Za-z0-9._:/#-]{1,35}$'
          x-sent-by: pos
          description: The item's serial or other code.
      examples:
        - {"ProductDescription": "Flat white", "ProductCode": "FW-2", "ProductQuantity": 2, "UnitPrice": "6.25", "ProductAmount": "12.50", "ValueAddedTax": "1.14"}
    Sale:
      type: object
      required: [TransactionReference, MerchantIdentification, POIIdentification, SaleReferenceIdentification, TransactionDetails, TransactionStatus, StatusReasonInformation, PaymentReference]
      description: >-
        A sale, as `POST /v1/sales` and every read answer it. A refund's `TransactionStatus` reads as a sale's: `ACSP` refunded, `RJCT` not refunded whatever its `Reason`, and `UNKN` not known, so check the terminal before refunding another way, and never send the refund again under a new key. Ignore a field you do not know, treat a `TransactionStatus` you do not know as `UNKN`, and read `RJCT` as no payment taken whatever its `Reason`. `TransactionStatus` and `Reason` each list this version's codes beside any other string, so an answer holding a code you do not know still validates against this schema.
      properties:
        TransactionType:
          type: [string, 'null']
          anyOf:
            - enum: [RFND, null]
            - type: string
          x-sent-by: mw
          description: >-
            `RFND` on a refund, and absent on a sale, even one sent with `CRDP`: absent means a sale. The list is open: the `TransactionStatus` of a type you do not know reads as a sale's.
        TransactionReference:
          type: string
          pattern: '^sal_[0-9a-f]{32}$'
          x-sent-by: mw
          description: >-
            The middleware's id for the sale, `sal_` then 32 lowercase hex characters: read the sale by it. It is the matching key between the sale, its instruction and the terminal's outcome.
        MerchantIdentification:
          type: string
          x-sent-by: mw
          description: The merchant, as the sale was accepted with it.
        POIIdentification:
          type: string
          x-sent-by: mw
          description: The sale's terminal.
        SaleReferenceIdentification:
          type: string
          x-sent-by: mw
          description: The POS's own reference, from what the middleware holds.
        TransactionDetails:
          type: object
          required: [Currency, TotalAmount]
          x-sent-by: mw
          description: >-
            The sale's currency and total, and the amount the host approved when the outcome that settled the sale stated one. The basket is not read back.
          properties:
            Currency:
              type: string
              x-sent-by: mw
              description: The sale's currency, `AUD`.
            TotalAmount:
              $ref: '#/components/schemas/Amount'
              x-sent-by: mw
              description: What the terminal was told to charge, or on a refund to refund.
            AuthorisedAmount:
              anyOf:
                - $ref: '#/components/schemas/Amount'
                - type: 'null'
              x-sent-by: mw
              description: >-
                The amount the host approved, as the outcome that settled the sale stated it: what the customer was charged, or on a refund what was refunded. Absent when that outcome stated none, and only an approval states one.
        OriginalTransaction:
          type: [object, 'null']
          required: [TransactionReference]
          x-sent-by: mw
          description: On a refund, the sale it refunds, as the POS sent it. Absent on a sale.
          properties:
            TransactionReference:
              type: string
              pattern: '^sal_[0-9a-f]{32}$'
              x-sent-by: mw
              description: The middleware's id for the sale refunded, as the POS sent it.
        TransactionStatus:
          type: string
          anyOf:
            - enum: [PDNG, ACSP, RJCT, UNKN]
            - type: string
          x-sent-by: mw
          description: |
            Where the sale stands, one of four codes in this version.

            - `PDNG`: the terminal is instructed and has not answered. Read again.
            - `ACSP`: the terminal approved the whole `TotalAmount`. Complete the sale, and where
              `TransactionDetails.AuthorisedAmount` differs from `TotalAmount`, record
              `AuthorisedAmount` as the amount charged: a lower one leaves the rest of the bill
              owed, and a higher one is more than the bill. On a refund, record it as the amount
              refunded: a lower one leaves the rest of the refund owed to the customer, and a higher
              one is more than was asked. Either way the terminal broke the contract, and the
              middleware's `amount_differs` line tells FUNDiMO.
            - `RJCT`: no payment was taken, whatever its `Reason`. Take another tender.
            - `UNKN`: the middleware does not know the outcome: no word came by the deadline, or the
              terminal contradicted itself. A payment may have been taken. Tell the cashier to check
              the terminal before another tender, and keep reading: a late word from the terminal
              replaces it, unless the terminal contradicted itself, when it stays `UNKN`.

            A terminal that declared `SSMQ` when it connected finds out what happened and reports as
            soon as it knows: where its host answers, before the terminal's hold ends, 300 seconds
            from the sale at the middleware's default settings. `UNKN` past the hold means the
            sale's terminal has not yet resolved it: its word may still come, however late, and
            replaces `UNKN` when it does.
        StatusReasonInformation:
          type: [object, 'null']
          x-sent-by: mw
          description: >-
            Why the sale stands where it does: `null` on `PDNG` and `UNKN`, and with `RJCT` its `Reason`. With `ACSP` or `RJCT` it holds whatever else the settling outcome carried that passed, so it is `null` on an `ACSP` whose outcome carried none.
          properties:
            Reason:
              type: [string, 'null']
              anyOf:
                - enum: [AG07, AB11, DS02, null]
                - type: string
              x-sent-by: mw
              description: |
                With `RJCT` only, one of three codes in this version.

                - `AG07`: the host or the card declined.
                - `AB11`: no payment was taken otherwise, such as a cancel at the terminal, a host
                  that did not answer, or an approval the terminal reversed.
                - `DS02`: the sale was aborted with `POST /v1/sales/{TransactionReference}/abort`,
                  and its terminal stopped the payment before it reached its host. On a refund, no
                  refund was made.
            ResponseCode:
              type: [string, 'null']
              x-sent-by: mw
              description: >-
                The card host's code, as the terminal sent it, such as `00`, when a settled sale's outcome carried it.
            AdditionalInformation:
              type: [string, 'null']
              x-sent-by: mw
              description: >-
                The host's text, as the terminal sent it, such as `APPROVED`, when a settled sale's outcome carried it.
        PaymentReference:
          type: [object, 'null']
          x-sent-by: mw
          description: >-
            The terminal's references for the payment, under the group of its kind of payment: `Card`, `Bank`, `Wallet` or `NPP`. Always present, and `null` unless the sale is settled and its outcome carried a reference that passed. It then holds what passed, unchanged, under the same group and key, and those that failed their pattern are left out. Each key says whether a POS prints it, refunds against it or matches settlement by it, and a POS treats these strings as opaque, so this schema gives them no pattern.
          properties:
            Card:
              type: [object, 'null']
              x-sent-by: mw
              description: A card payment, through a card terminal and its card host.
              properties:
                RetrievalReferenceNumber:
                  type: [string, 'null']
                  x-sent-by: mw
                  description: >-
                    The card host's retrieval reference, as the terminal sent it. Print it on a receipt, and match settlement by it.
                SystemTraceAuditNumber:
                  type: [string, 'null']
                  x-sent-by: mw
                  description: >-
                    The card host's trace number, as the terminal sent it. Print it on a receipt, and match settlement by it.
                AuthorisationCode:
                  type: [string, 'null']
                  x-sent-by: mw
                  description: >-
                    The authorising party's code, as the terminal sent it. Print it on a receipt, and match settlement by it.
                AcquirerPOIIdentification:
                  type: [string, 'null']
                  x-sent-by: mw
                  description: >-
                    The acquirer's id for the terminal. Print it on a receipt, and match settlement by it.
                AcquirerMerchantIdentification:
                  type: [string, 'null']
                  x-sent-by: mw
                  description: >-
                    The acquirer's id for the merchant. Print it on a receipt, and match settlement by it.
                RefundReference:
                  type: [string, 'null']
                  x-sent-by: mw
                  description: >-
                    The host's reference for a later refund. Not on a receipt: keep it to refund against.
            Bank:
              type: [object, 'null']
              x-sent-by: mw
              description: An account's payment by its own bank, outside a card scheme and NPP.
              properties:
                AccountServicerReference:
                  type: [string, 'null']
                  x-sent-by: mw
                  description: >-
                    The reference the account's own bank gave the payment, as the terminal sent it. Print it on a receipt, and match settlement by it.
            Wallet:
              type: [object, 'null']
              x-sent-by: mw
              description: A payment through a wallet or payment app.
              properties:
                ProviderIdentification:
                  type: [string, 'null']
                  x-sent-by: mw
                  description: >-
                    The wallet's or payment app's provider, by name, as the terminal sent it. Print it on a receipt.
                RecipientTransactionIdentification:
                  type: [string, 'null']
                  x-sent-by: mw
                  description: >-
                    The provider's id for the payment, as the terminal sent it. Print it on a receipt, keep it to refund against, and match settlement by it.
            NPP:
              type: [object, 'null']
              x-sent-by: mw
              description: A payment over Australia's New Payments Platform, PayTo included.
              properties:
                EndToEndIdentification:
                  type: [string, 'null']
                  x-sent-by: mw
                  description: >-
                    The payer's reference, passed on unchanged end to end, as the terminal sent it, NOTPROVIDED when the payer gave none. Print it on a receipt, keep it to refund against, and match settlement by it.
                TransactionIdentification:
                  type: [string, 'null']
                  x-sent-by: mw
                  description: >-
                    The payer's bank's id for the payment, as the terminal sent it. Keep it to refund against, and match settlement by it.
                MandateIdentification:
                  type: [string, 'null']
                  x-sent-by: mw
                  description: >-
                    The PayTo mandate's id, which on NPP the Mandate Management Service generates, not the creditor, as the terminal sent it. Print it on a receipt, and match settlement by it.
      examples:
        - {"TransactionReference": "sal_01970f6e7c3a7d3e8a4f2b1c9d0e1f2a", "MerchantIdentification": "M-1001", "POIIdentification": "T-APPROVE", "SaleReferenceIdentification": "INV-1001", "TransactionDetails": {"Currency": "AUD", "TotalAmount": "12.50"}, "TransactionStatus": "PDNG", "StatusReasonInformation": null, "PaymentReference": null}
    Error:
      type: object
      required: [Error]
      description: The body of every non-2xx answer the middleware gives. Every field is present.
      properties:
        Error:
          type: object
          required: [Code, Message, Fields]
          x-sent-by: mw
          description: What was refused, and why.
          properties:
            Code:
              type: string
              x-sent-by: mw
              description: The reason's code, one per case, named under its answer. Branch on this.
            Message:
              type: string
              x-sent-by: mw
              description: A fixed sentence per code for a person, holding nothing the request sent.
            Fields:
              type: array
              maxItems: 32
              items:
                type: string
              x-sent-by: mw
              description: >-
                The fields the refusal is about, sorted, at most 32, as paths such as `TransactionDetails.SaleItem[0].ProductDescription`, and empty when the refusal is about no field. A name the sender chose is shown as sent only when it has at most 64 characters, only ASCII letters, digits, `_`, `.` and `-`, and at most 2 digits, and as `<unprintable>` otherwise.
      examples:
        - {"Error": {"Code": "terminal_offline", "Message": "The terminal is not connected.", "Fields": []}}
    Health:
      type: object
      required: [Status, Version]
      description: Whether the middleware is serving.
      properties:
        Status:
          type: string
          x-sent-by: mw
          description: '`ok`.'
        Version:
          type: string
          x-sent-by: mw
          description: The release of the middleware answering, not this document's `info.version`.
      examples:
        - {"Status": "ok", "Version": "0.0.0"}
    RegisterListing:
      type: object
      additionalProperties: false
      description: >-
        What `POST /v1/registers` takes: a device's `SerialNumber`, or `{}` for a server's register, and from the operator or `onboarding` the register's `VendorIdentification`.
      properties:
        SerialNumber:
          type: [string, 'null']
          pattern: '^[A-Za-z0-9._-]{1,64}$'
          x-sent-by: vendor
          description: The device's serial, as printed on it. None lists a server's register.
        VendorIdentification:
          type: [string, 'null']
          pattern: '^ven_[0-9a-f]{32}$'
          x-sent-by: vendor
          description: >-
            From the operator or `onboarding` alone: the POS vendor the register is listed for, else the caller's vendor. From a vendor's `admin` it is `400 unknown_field`, and a vendor that holds no `pos` role, or that no row holds, is `403 not_permitted`.
    DeviceAttestation:
      type: object
      required: [State, FailedChecks, Since]
      description: >-
        A device's attestation mark, which is its newest certificate's: the middleware issued that certificate though the device's key attestation failed the checks `FailedChecks` lists.
      properties:
        State:
          type: string
          anyOf:
            - enum: [failed]
            - type: string
          x-sent-by: mw
          description: >-
            `failed`, the one value today: the key attestation failed, and the middleware admitted the device all the same. Read a `State` you do not know as not attested by Google.
        FailedChecks:
          type: array
          minItems: 1
          items:
            type: string
            enum: [chain_missing, chain, root, dates, revoked, hardware, boot, app_debug, model]
          x-sent-by: mw
          description: |
            The checks the newest certificate's key attestation failed, at least one, each once, in
            the order the middleware runs them:

            - `chain_missing`: the device sent no chain, and it stands alone.
            - `chain`: the chain holds fewer than three certificates, does not end in a self-issued
              one, or holds one not signed by the next, and `root` comes with it.
            - `root`: the chain does not end at one of Google's two attestation roots.
            - `dates`: a certificate of the chain is outside its dates.
            - `revoked`: a certificate of the chain is revoked or suspended.
            - `hardware`: the key was not made in the trusted environment or StrongBox, or is not a
              P-256 key for signing.
            - `boot`: the bootloader is not locked, or the boot not verified.
            - `app_debug`: the app is registered for its vendor and role as a debug build alone.
            - `model`: no row of the allowed list admits what the device attests.
        Since:
          type: string
          x-sent-by: mw
          description: >-
            When the device's current unbroken run of failed certificates began, in RFC 3339 and UTC: the `IssuedAt` of the run's first certificate.
    RegisterListed:
      type: object
      required: [RegisterIdentification, VendorIdentification, Kind, State]
      description: A register just listed or given a fresh code, and a device's code, shown once.
      properties:
        RegisterIdentification:
          type: string
          pattern: '^reg_[0-9a-f]{32}$'
          x-sent-by: mw
          description: The register's id, issued by the middleware.
        VendorIdentification:
          type: string
          pattern: '^ven_[0-9a-f]{32}$'
          x-sent-by: mw
          description: The register's POS vendor, the caller's or the one FUNDiMO named.
        Kind:
          type: string
          enum: [device, server]
          x-sent-by: mw
          description: '`device` for an app on a device, `server` for a vendor''s server.'
        State:
          type: string
          enum: [listed, active, removed]
          x-sent-by: mw
          description: '`listed` for a device until it enrols, `active` for a server''s register.'
        SerialNumber:
          type: [string, 'null']
          x-sent-by: mw
          description: A device's serial. Absent for a server's register.
        PairingCode:
          type: [string, 'null']
          pattern: '^[a-z]{3,6}(\.[a-z]{3,6}){4}$'
          x-sent-by: mw
          description: >-
            A device's code: five different words of `docs/api/words.txt`, joined by dots, valid 15 minutes and for one use, shown this once. Absent for a server's register.
    Register:
      type: object
      required: [RegisterIdentification, VendorIdentification, Kind, State]
      description: A register, as its routes show it.
      properties:
        RegisterIdentification:
          type: string
          pattern: '^reg_[0-9a-f]{32}$'
          x-sent-by: mw
          description: The register's id.
        VendorIdentification:
          type: string
          pattern: '^ven_[0-9a-f]{32}$'
          x-sent-by: mw
          description: The POS vendor whose register it is.
        Kind:
          type: string
          enum: [device, server]
          x-sent-by: mw
          description: '`device` or `server`.'
        State:
          type: string
          enum: [listed, active, removed]
          x-sent-by: mw
          description: '`listed`, `active`, the one state that may sell, or `removed`.'
        SerialNumber:
          type: [string, 'null']
          x-sent-by: mw
          description: A device's serial. Absent for a server's register.
        StoreIdentification:
          type: [string, 'null']
          pattern: '^mst_[0-9a-f]{32}$'
          x-sent-by: mw
          description: The store it sits at, absent until its first binding.
        NotAfter:
          type: [string, 'null']
          x-sent-by: mw
          description: >-
            When its newest certificate expires, a retired or expired one among them, in RFC 3339. Absent before any: present, it means the register has held a certificate, so a code for it is a re-pair.
        Attestation:
          anyOf:
            - $ref: '#/components/schemas/DeviceAttestation'
            - type: 'null'
          x-sent-by: mw
          description: >-
            Its attestation mark, its newest certificate's, absent unless that certificate's key attestation failed, so always absent for a server's register.
    RegisterList:
      type: object
      required: [Registers]
      description: The registers the caller may see.
      properties:
        Registers:
          type: array
          items:
            $ref: '#/components/schemas/Register'
          x-sent-by: mw
          description: Each register, a removed one among them, oldest first.
    CertificateList:
      type: object
      required: [Certificates]
      description: >-
        The certificates a listing shows, each not past its `NotAfter`, ordered by the id of the principal that holds it, then `IssuedAt`, then `CertificateIdentification`.
      properties:
        Certificates:
          type: array
          items:
            $ref: '#/components/schemas/CertificateView'
          x-sent-by: mw
          description: Each certificate.
    CertificateView:
      type: object
      required: [CertificateIdentification, Role, SpkiDigest, IssuedAt, NotBefore, NotAfter, RenewFrom, State]
      oneOf:
        - required: [POIIdentification]
        - required: [RegisterIdentification]
        - required: [ServerIdentification]
      description: >-
        A certificate as a listing shows it, and the principal that holds it, by exactly one of its ids: its digests and its dates, and never the certificate itself, a key, a challenge or an attested value.
      properties:
        CertificateIdentification:
          type: string
          pattern: '^[0-9a-f]{64}$'
          x-sent-by: mw
          description: >-
            The SHA-256 of the certificate, the DER of the leaf, in lowercase hex: the id each log line of a request that presented it records.
        Role:
          type: string
          enum: [terminal, register, server]
          x-sent-by: mw
          description: 'Whose it is: a terminal''s, a register''s on a device, or a vendor''s server''s.'
        POIIdentification:
          type: [string, 'null']
          pattern: '^[A-Za-z0-9_-]{1,64}$'
          x-sent-by: mw
          description: A terminal's id, when the certificate is a terminal's.
        RegisterIdentification:
          type: [string, 'null']
          pattern: '^reg_[0-9a-f]{32}$'
          x-sent-by: mw
          description: A register's id, when the certificate is a register's.
        ServerIdentification:
          type: [string, 'null']
          pattern: '^srv_[0-9a-f]{32}$'
          x-sent-by: mw
          description: A vendor's server's id, when the certificate is a server's.
        Scope:
          type: [string, 'null']
          enum: [pos, admin, operator, onboarding, null]
          x-sent-by: mw
          description: What a server's certificate reaches. Absent on a terminal's and a register's.
        SpkiDigest:
          type: string
          pattern: '^[0-9a-f]{64}$'
          x-sent-by: mw
          description: >-
            The SHA-256 of the certificate's key, its `subjectPublicKeyInfo`, in lowercase hex, as a server's listing shows it.
        IssuedAt:
          type: string
          x-sent-by: mw
          description: When the middleware signed it, in RFC 3339 and UTC. `NotBefore` may be earlier.
        NotBefore:
          type: string
          x-sent-by: mw
          description: Its X.509 `notBefore`, in RFC 3339 and UTC.
        NotAfter:
          type: string
          x-sent-by: mw
          description: Its X.509 `notAfter`, when it expires, in RFC 3339 and UTC.
        RenewFrom:
          type: string
          x-sent-by: mw
          description: >-
            When it may renew, day 15 of its life, in RFC 3339 and UTC: from then `GET /v1/certificates/self` answers `RenewNow` `true` on it.
        FirstSeen:
          type: [string, 'null']
          x-sent-by: mw
          description: When it was first presented, in RFC 3339 and UTC. Absent if never.
        RetiredAt:
          type: [string, 'null']
          x-sent-by: mw
          description: >-
            When it is retired, in RFC 3339 and UTC, which may lie ahead, inside the overlap after a renewal. Absent if it is not retired.
        State:
          type: string
          enum: [unused, current, retired]
          x-sent-by: mw
          description: >-
            Its state, by the middleware's clock read once for the whole answer: `retired` once its `RetiredAt` has come, else `unused` where it was never presented, else `current`.
        Attestation:
          anyOf:
            - $ref: '#/components/schemas/CertificateAttestation'
            - type: 'null'
          x-sent-by: mw
          description: Its attestation mark, absent unless issued on a failed key attestation.
    CertificateAttestation:
      type: object
      required: [State, FailedChecks]
      description: >-
        A certificate's attestation mark: the middleware issued it though the device's key attestation failed the checks `FailedChecks` lists, and its `IssuedAt` says when.
      properties:
        State:
          type: string
          anyOf:
            - enum: [failed]
            - type: string
          x-sent-by: mw
          description: >-
            `failed`, the one value today: the key attestation failed, and the middleware issued the certificate all the same.
        FailedChecks:
          type: array
          minItems: 1
          items:
            type: string
            enum: [chain_missing, chain, root, dates, revoked, hardware, boot, app_debug, model]
          x-sent-by: mw
          description: >-
            The checks the key attestation failed, at least one, each once, in the order the middleware runs them, each word as `DeviceAttestation`'s `FailedChecks` says it.
    Enrolment:
      type: object
      additionalProperties: false
      required: [PairingCode, CertificateSigningRequest]
      description: >-
        What `POST /v1/enrol` takes. A device sends its `SerialNumber` and, on `live`, its `AttestationChain`, and a server sends neither.
      properties:
        PairingCode:
          type: string
          maxLength: 64
          pattern: '^[0-9A-Za-z .-]{1,64}$'
          x-sent-by: vendor
          description: >-
            The code as its listing showed it, at most 64 characters, read by the `SerialNumber` beside it. With a `SerialNumber` that is not `null`, a device's five different words of `docs/api/words.txt`, in any case, with one or more dots, spaces or hyphens between two words; with none, absent or `null`, a server's 16 characters in Crockford base32, spaces and hyphens dropped, either case read, and `I` and `L` read as `1` and `O` as `0`.
        CertificateSigningRequest:
          type: string
          maxLength: 4096
          x-sent-by: vendor
          description: >-
            A PKCS 10 request in PEM, one `CERTIFICATE REQUEST` block, for a P-256 key the principal never used. The middleware reads its public key and nothing else, and never logs it.
        SerialNumber:
          type: [string, 'null']
          pattern: '^[A-Za-z0-9._-]{1,64}$'
          x-sent-by: vendor
          description: Optional. A device's serial, as its listing names it.
        AttestationChain:
          type: [string, 'null']
          maxLength: 49152
          x-sent-by: vendor
          description: >-
            A device's Android Key Attestation chain for the key of the CSR, as `KeyStore` gives it, in PEM, leaf first. Required of a device on a `live` middleware, and checked when a sandbox is offered one.
    Renewal:
      type: object
      additionalProperties: false
      required: [CertificateSigningRequest]
      description: What renewal takes. A device on `live` sends `AttestationChain`; a server none.
      properties:
        CertificateSigningRequest:
          type: string
          maxLength: 4096
          x-sent-by: vendor
          description: >-
            A PKCS 10 request in PEM, one `CERTIFICATE REQUEST` block, for a new P-256 key the principal has never used. The middleware reads its public key and nothing else.
        AttestationChain:
          type: [string, 'null']
          maxLength: 49152
          x-sent-by: vendor
          description: >-
            A device's Android Key Attestation chain for the new key, made with the challenge of `POST /v1/certificates/challenge`, in PEM, leaf first.
    LinkRequest:
      type: object
      additionalProperties: false
      required: [MerchantIdentification]
      description: What `POST /v1/links` takes.
      properties:
        MerchantIdentification:
          type: string
          pattern: '^[A-Za-z0-9_-]{1,64}$'
          x-sent-by: pos
          description: >-
            The store to link at: its own `MerchantIdentification`, or an alias of it the caller's vendor accepted, as a sale names it.
    LinkWordSubmission:
      type: object
      additionalProperties: false
      required: [Word]
      description: What `POST /v1/links/{LinkIdentification}/word` takes.
      properties:
        Word:
          type: string
          maxLength: 64
          pattern: '^ *[A-Za-z]{3,6}[. ][A-Za-z]{3,6} *$'
          x-sent-by: pos
          description: >-
            The pair the staff member reads off the terminal in their hand, as typed, such as `rabbit.lamp` or `rabbit lamp`: two different words of the middleware's list, in the order shown, with a dot or a space between them, case and surrounding spaces ignored. The same word twice is refused, which this pattern cannot say.
    EnrolmentIssued:
      type: object
      required: [CertificateChain, SpiffeId, NotAfter, RenewFrom]
      oneOf:
        - required: [POIIdentification]
        - required: [RegisterIdentification]
        - required: [ServerIdentification]
      description: >-
        A certificate just issued, by enrolment or renewal, and the principal it names, by exactly one of its ids. A certificate is public.
      properties:
        CertificateChain:
          type: string
          x-sent-by: mw
          description: The certificate then its issuer's, PEM. Present both at the TLS handshake.
        POIIdentification:
          type: [string, 'null']
          x-sent-by: mw
          description: A terminal's id, when the certificate is a terminal's.
        RegisterIdentification:
          type: [string, 'null']
          pattern: '^reg_[0-9a-f]{32}$'
          x-sent-by: mw
          description: A register's id, when the certificate is a register's.
        ServerIdentification:
          type: [string, 'null']
          pattern: '^srv_[0-9a-f]{32}$'
          x-sent-by: mw
          description: A vendor's server's id, when the certificate is a server's.
        SpiffeId:
          type: string
          x-sent-by: mw
          description: >-
            The certificate's one SAN, `spiffe://`, the middleware's trust domain, then the environment, the role and the id, each after a `/`.
        NotAfter:
          type: string
          x-sent-by: mw
          description: When the certificate expires, in RFC 3339.
        RenewFrom:
          type: string
          x-sent-by: mw
          description: When it may renew, day 15 of its life, in RFC 3339.
    CertificateStatus:
      type: object
      required: [NotAfter, RenewFrom, RenewNow]
      description: The certificate presented, as its daily check reads it.
      properties:
        NotAfter:
          type: string
          x-sent-by: mw
          description: When it expires, in RFC 3339.
        RenewFrom:
          type: string
          x-sent-by: mw
          description: When it may renew, day 15 of its life, in RFC 3339.
        RenewNow:
          type: boolean
          x-sent-by: mw
          description: Whether to renew it now, by the middleware's clock.
    ChallengeIssued:
      type: object
      required: [Challenge, ExpiresInSeconds]
      description: A challenge for a device's next key.
      properties:
        Challenge:
          type: string
          pattern: '^[0-9a-f]{64}$'
          x-sent-by: mw
          description: 32 random bytes, for the new key's attestation. Keep it out of every log.
        ExpiresInSeconds:
          type: integer
          x-sent-by: mw
          description: How long it is valid, in whole seconds.
    LinkOpened:
      type: object
      required: [LinkIdentification, ExpiresInSeconds]
      description: A request to link, just opened. Never a word.
      properties:
        LinkIdentification:
          type: string
          pattern: '^lnk_[0-9a-f]{32}$'
          x-sent-by: mw
          description: The request's id, `lnk_` then 32 lowercase hex characters.
        ExpiresInSeconds:
          type: integer
          x-sent-by: mw
          description: How long the terminals show their words, in whole seconds.
    LinkStatus:
      type: object
      required: [Asked, Shown]
      description: A request to link, as its register reads it.
      properties:
        Asked:
          type: integer
          x-sent-by: mw
          description: How many terminals the request gave a word.
        Shown:
          type: integer
          x-sent-by: mw
          description: How many of those words have reached their terminal.
    LinkBound:
      type: object
      required: [POIIdentification, MerchantIdentification]
      description: The terminal a word linked, and its store.
      properties:
        POIIdentification:
          type: string
          x-sent-by: mw
          description: The terminal now bound to the caller, which its sales name.
        MerchantIdentification:
          type: string
          x-sent-by: mw
          description: The store's `MerchantIdentification`, as the request named it.
    RegisterTerminal:
      type: object
      required: [POIIdentification, State, Connected, Busy]
      description: A terminal bound to the caller.
      properties:
        POIIdentification:
          type: string
          x-sent-by: mw
          description: The terminal's id.
        State:
          type: string
          enum: [listed, paired, suspended, removed]
          x-sent-by: mw
          description: '`paired` is the one state that may take a sale.'
        Connected:
          type: boolean
          x-sent-by: mw
          description: Whether it holds a connection to this instance of the middleware.
        Busy:
          type: boolean
          x-sent-by: mw
          description: Whether a sale holds it.
    RegisterTerminalList:
      type: object
      required: [Terminals]
      description: The terminals bound to the caller.
      properties:
        Terminals:
          type: array
          items:
            $ref: '#/components/schemas/RegisterTerminal'
          x-sent-by: mw
          description: Each terminal.
