miaPOS.eu
Contact sales
Docs · API reference

POS API

The interface used by hardware POS terminals (Sunmi, SmartOne, Datecs, Ingenico, PAX) and SoftPOS apps to accept payments through miaPOS. Terminal activation, seller auth, shift management, QR transactions, refunds, settings — twenty-five endpoints under /pos/api/v1/.

AudienceDeveloper
DifficultyIntermediate
Versionv1 · spec v5
Updated2026-06-25
Interactive reference
Full Redoc spec →
Complete request and response schemas, examples in curl/JavaScript/Python, error catalogues. Rendered from the same OpenAPI spec that drives the mia-pos service.
Open reference →
Postman
Download collection →
The full request set as a Postman collection. Environment template published alongside — populate the placeholders with sandbox values received from sales.
Collection · env template

Overview

The POS API is the interface between a POS device (hardware terminal or SoftPOS app) and the miaPOS backend. All endpoints live under /pos/api/v1/. The flow is: activate the terminal, sign the seller in, open a shift, generate QR / create transactions, then close the shift at end-of-day. Refunds and status queries hang off the same base.

The API is IP-rail only. Payments are authorised by the buyer in their own banking app after scanning the QR or opening the miaPOS payment link — the terminal does not touch card data, so there is no PCI scope on the merchant side.

Base URL & environments

Every partner integration uses its own base URL. Sandbox and production hosts, merchant identifiers, terminal identifiers and operator credentials are issued per partner during onboarding — request sandbox access from sales. Public documentation intentionally does not list host names or credentials.

Authentication

Each seller signs in with userName + userPassword against the seller endpoint and receives an access token and a refresh token. The access token is passed as Authorization: Bearer <accessToken> on every subsequent request. Refresh is one-shot — POST /seller/refresh exchanges the refresh token for a new pair.

Two-step onboarding. Before a seller can log in, the terminal itself must be activated. The activation flow (init → otp-resend → confirm or the simplified variant) binds this physical device to the merchant and the terminal identifier. Once activated, the seller flow is enough for day-to-day operations.

Endpoints

Terminal activation

6 endpoints
Bind a physical device to a merchant and terminal identifier. Standard flow requires an OTP; the simplified variant is used for pre-provisioned devices.
POST/pos/api/v1/terminal-activation/initstart activation, sends OTP
POST/pos/api/v1/terminal-activation/otp-resendresend OTP
POST/pos/api/v1/terminal-activation/confirmconfirm OTP, finalize binding
GET/pos/api/v1/terminal-activation/typeavailable activation flows
POST/pos/api/v1/terminal-activation/simplifiedpre-provisioned devices
GET/pos/api/v1/terminal-activation/{posActivationId}activation status

Seller authentication

4 endpoints
Sign in a cashier, refresh their session, read the current session profile.
POST/pos/api/v1/seller/loginusername + password → tokens
POST/pos/api/v1/seller/refreshrefresh token → new pair
POST/pos/api/v1/seller/logoutinvalidate tokens
GET/pos/api/v1/seller/infocurrent seller profile

Shift management

4 endpoints
Open and close a work shift on the terminal. Transactions are always attached to the currently open shift. The Z-report is the end-of-day summary.
GET/pos/api/v1/shift/checkis a shift currently open?
POST/pos/api/v1/shift/openopen new shift
POST/pos/api/v1/shift/closeclose current shift
GET/pos/api/v1/shift/{shiftId}/z-reportZ-report (end-of-day summary)

Transactions — QR & status

6 endpoints
Generate a QR for the buyer, poll or push status, retrieve the transaction and its receipt. The buyer authorises the payment in their own banking app; the POS receives status via check-endpoint and (recommended) via webhooks.
POST/pos/api/v1/qr/generatecreate QR for an amount
GET/pos/api/v1/qr/{qrId}/checkcheck QR / transaction status
POST/pos/api/v1/qr/{qrId}/cancelcancel an unpaid QR
POST/pos/api/v1/txcreate transaction
GET/pos/api/v1/tx/{txId}transaction detail
GET/pos/api/v1/tx/{txId}/receiptreceipt for a settled transaction

Returns & refunds

3 endpoints
Push a refund against a previous transaction and check its status. Refund reasons are enumerated by the backend.
GET/pos/api/v1/tx/return/reasonrefund reason catalogue
POST/pos/api/v1/tx/returnissue a refund request
GET/pos/api/v1/tx/return/{requestId}/statusrefund status

Settings

2 endpoints
Read and update terminal settings and QR-specific settings (defaults, expiry, cosmetic options).
GET/PUT/pos/api/v1/settingsterminal settings
GET/PUT/pos/api/v1/qr-settingsQR-specific settings

Schemas

Full request and response schemas for every endpoint — including examples, enum values and per-field descriptions — are published in the interactive Redoc reference. The reference is generated from the same OpenAPI spec (v5) that drives the mia-pos service in production.

Postman collection

The full request set is published as a Postman collection so a developer can start integrating without hand-writing calls:

No credentials are shipped with the docs. The environment template contains only placeholder strings — no live URL, no token, no password. Sandbox credentials are issued per partner.

Errors

All endpoints return errors in the standard envelope. See Errors for the full catalogue and the mapping from HTTP status to internal error code.

Webhooks

Terminal-to-backend polling is supported for status checks, but webhooks are the recommended way to receive transaction lifecycle events (paid, failed, refunded). See Webhooks for payload shape and Signature verification for verifying authenticity.