# Middleware

> The middleware is the relay between a point of sale, a payment terminal and FUNDiMO. A POS vendor and a terminal vendor each integrate into one schema.

What to know first:

- Never send card, bank or personal data, such as a card number, an expiry, track data or a bank account. The middleware forbids them in every field, and cannot detect them: it checks a string's shape, and the contracts say what still fits.
- What a terminal sends back passes an allow-list. Anything else is dropped, and the drop is logged.
- The middleware is not the record of a payment. FUNDiMO or the terminal's acquirer is.

## Start here

- [The sandbox](/docs/api/sandbox.md): Where to start. Take a sandbox key with `POST /sandbox/v1/keys`, which needs no credential, then use the MCP server at `POST /mcp`: this page walks both journeys, a POS's and a terminal's, from that key to a conformance run and its signed report.

## Contract

- [OpenAPI document](/docs/api/openapi.yaml): The HTTP contract a POS and a back office build against, and the schemas of a terminal's frames.
- [Terminal contract](/docs/api/terminal.md): The WebSocket contract a terminal builds against.
- [Onboarding a device](/docs/api/onboarding-device.md): The walk for a vendor's Android app on a SUNMI terminal or register, with Kotlin to paste: registering the app, the code, a P-256 key in the keystore with its attestation, enrolment, presenting the certificate, the daily check, renewal, and what a holder does after each refusal.
- [Onboarding a server](/docs/api/onboarding-server.md): The host-to-host walk for a vendor's server: the listing and its code, a P-256 key in the vendor's own custody, enrolment, presenting the certificate with curl, Rust and Java, `Mw-Installation`, listing a server's register, the daily check, renewal by one renewer per identity, and what a holder does after each refusal.
- [Linking a register to a terminal](/docs/api/linking.md): The link step at the counter, by a word the terminal shows and the staff member types, what a POS shows staff at each answer, a register's terminals, unlinking, and what a store's fleet owner can do.
- [Field catalogue](/docs/api/fields.json): One row per field of each message: who sends it, its ISO 20022 element where ISO has one, its bound and an example, and on what a POS or a terminal sends, a bad example and what the middleware does with it. Rows per message: Sale 26, SaleView 29, Instruction 13, Outcome 25, Refusal 3, Error 4, LinkWord 3, LinkEnded 2.

## References by kind

- [card: PaymentReference.Card](/docs/api/fields.json): A card payment, through a card terminal and its card host. A card terminal sends it on an outcome its card host answered, holding the host's references and never card data. Keys: RetrievalReferenceNumber, SystemTraceAuditNumber, AuthorisationCode, AcquirerPOIIdentification, AcquirerMerchantIdentification, RefundReference.
- [bank: PaymentReference.Bank](/docs/api/fields.json): A payment from a bank account by the account's own bank, outside a card scheme and NPP. A terminal sends it when that bank gave a reference. Keys: AccountServicerReference.
- [wallet: PaymentReference.Wallet](/docs/api/fields.json): A payment through a wallet or payment app. A terminal that took the payment that way sends it, naming the provider, and with the provider's id for the payment when it gave one. Keys: ProviderIdentification, RecipientTransactionIdentification.
- [npp: PaymentReference.NPP](/docs/api/fields.json): A payment over Australia's New Payments Platform, PayTo included. A terminal whose payment went over NPP sends it. Keys: EndToEndIdentification, TransactionIdentification, MandateIdentification.

## Conformance

- [Conformance scenarios](/docs/api/conformance.json): The eight scenarios of each side, POS and terminal, and the assertions each is judged by. A verdict is read from the log and each step's deadline. `duplicate_key` does not apply to a terminal. A conformance run is not a card scheme's certification.

## Optional

- [MCP server](/mcp): The sandbox's MCP server, where one is running.