Catalog

Who calls these endpoints?External API (s2s)

Base path: /api/v1/physical-pos
Identity: Ed25519 request signature on every request — X-Key-Id, X-Date, X-Nonce, X-Signature, plus Digest on requests with a body. ±5 min clock window, single-use nonce. A Bearer token or a panel session is not accepted here.
Authorization: The key must carry the Physical POS product (PHYSICAL_POS) and the scope for the endpoints on this page: physical_pos:view. Without the product the call gets 403 PRODUCT_NOT_ENABLED; without the scope 403 API_INSUFFICIENT_SCOPE. See Authentication and Scopes.
Cross-surface: These endpoints are the s2s surface — call them from your own server with a signed request. The same records have screens in the panel, but panel endpoints cannot be called with an API key, and these endpoints cannot be called with a panel session.

The catalog lists the POS vendors, device models and banks usable on physical POS that are defined on the platform. The catalog is shared by all businesses; it is read-only and independent of the environment (test and live keys see the same list).

Catalog endpoints are not paginated: data is an array with the whole list. → Common Rules › Response envelope

Vendors

GET /api/v1/physical-pos/catalog/vendors

Takes no query parameters; an undefined parameter returns 400 VALIDATION_ERROR. The list returns every vendor, including disabled ones, ordered by code.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/catalog/vendors"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

lunixi-sign.sh: Authentication › Signing helper.

{
  "status": "success",
  "code": "SUCCESS",
  "data": [
    {
      "code": "PAVO",
      "displayName": "Pavo",
      "status": "ACTIVE",
      "fallbackImage": {
        "assetId": "00000000-0000-4000-8000-000000000a01",
        "url": "https://img.lunixi.com/00000000-0000-4000-8000-000000000a01"
      }
    },
    {
      "code": "PLUSPAY",
      "displayName": "PlusPay",
      "status": "ACTIVE",
      "fallbackImage": null
    }
  ],
  "statusCode": 200,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Field	Type	Description
`code`	string	Vendor code. You put this value in `vendorCode` when creating a terminal.
`displayName`	string	Vendor display name.
`status`	string	`ACTIVE` or `DISABLED`. A disabled vendor cannot be used on a new terminal.
`fallbackImage`	object \| null	The vendor's fallback image, shown when a model has no image of its own. → Image object

Device models

GET /api/v1/physical-pos/catalog/device-models

Query parameter	Type	Description
`vendorCode`	string	Only this vendor's models. Case-insensitive. A well-formed code that is not in the catalog returns an empty list; a malformed code returns `400 physical_pos.input.filter_invalid`.
`deviceType`	string	`PHYSICAL` or `SOFTPOS`.
`status`	string	`ACTIVE` or `DEPRECATED`. If omitted, both are returned.

If deviceType or status is outside its set (case-sensitive), the request gets 400 physical_pos.input.filter_invalid; details.field names the filter.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/catalog/device-models?vendorCode=PAVO&status=ACTIVE"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

{
  "status": "success",
  "code": "SUCCESS",
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000b01",
      "vendorCode": "PAVO",
      "modelCode": "EXAMPLE-M1",
      "displayName": "Example Model M1",
      "deviceType": "PHYSICAL",
      "formFactor": "COUNTERTOP",
      "fiscalCapable": true,
      "status": "ACTIVE",
      "image": {
        "assetId": "00000000-0000-4000-8000-000000000a02",
        "url": "https://img.lunixi.com/00000000-0000-4000-8000-000000000a02"
      },
      "vendorFallbackImage": {
        "assetId": "00000000-0000-4000-8000-000000000a01",
        "url": "https://img.lunixi.com/00000000-0000-4000-8000-000000000a01"
      }
    }
  ],
  "statusCode": 200,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Field	Type	Description
`id`	string (UUID)	Model ID.
`vendorCode`	string	Code of the model's vendor.
`modelCode`	string	Model code within the vendor.
`displayName`	string	Model display name.
`deviceType`	string	`PHYSICAL`: dedicated POS hardware. `SOFTPOS`: a mobile device that accepts cards.
`formFactor`	string	`COUNTERTOP`, `PORTABLE`, `MOBILE`, `UNATTENDED` (e.g. kiosk) or `PINPAD`.
`fiscalCapable`	boolean	`true` if the model can be used as a fiscal device (electronic cash register).
`status`	string	`ACTIVE` or `DEPRECATED`. A `DEPRECATED` model stays in the catalog but should not be chosen for new installations.
`image`	object \| null	The model's own image. → Image object
`vendorFallbackImage`	object \| null	The vendor's fallback image (same as `fallbackImage` in the vendor list).

Banks

GET /api/v1/physical-pos/catalog/acquirers

Takes no query parameters; an undefined parameter returns 400 VALIDATION_ERROR. The list returns only active banks, ordered by acquirerCode.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/catalog/acquirers"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

{
  "status": "success",
  "code": "SUCCESS",
  "data": [
    { "acquirerCode": "0000", "providerCode": "EXAMPLEBANK", "displayName": "Example Bank" }
  ],
  "statusCode": 200,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Field	Type	Description
`acquirerCode`	string	The bank's four-digit bank code. The `acquirerCode` field on a terminal's bank rows carries this value.
`providerCode`	string	The provider code Lunixi uses for this bank.
`displayName`	string	Bank display name.

When you add a bank row you identify the bank not by acquirerCode but by the code the POS vendor gives the bank (vendorAcquirerRef); Lunixi maps that code to the bank in the catalog. → Bank Rows

Image object

Images are always returned as an { assetId, url } object; when there is no image the field is null.

Field	Type	Description
`assetId`	string (UUID)	Image ID. A replaced image gets a new ID, so you can use it as a cache key.
`url`	string	The image's public `https` address. Use the address as is; do not build it yourself.

Images are PNG, JPEG or WebP. When showing a model, we recommend this order: image → vendorFallbackImage → your own generic image (by device type and form factor).

Errors

HTTP	`code`	When
`400`	`VALIDATION_ERROR`	Undefined query parameter.
`400`	`physical_pos.input.filter_invalid`	Invalid `vendorCode`, `deviceType` or `status` filter.
`400`	`physical_pos.input.environment_invalid`	`environment` was sent in the query.
`403`	`PRODUCT_NOT_ENABLED` / `API_INSUFFICIENT_SCOPE`	The key lacks the product or `physical_pos:view`.

All codes: Error Codes.

Common Rules Stores