Physical POS
API Reference
Card Provider Rows

Card Provider Rows

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 · physical_pos:manage. 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.

To take payments with closed-loop cards such as meal cards, you add the merchant and terminal codes the card provider gave you to the logical terminal as a provider row. It is the closed-loop counterpart of the bank rows used for bank cards. Which row a sale uses: Meal Card Sale.

MethodPathScope
GET/api/v1/physical-pos/terminals/{terminalId}/providersphysical_pos:view
POST/api/v1/physical-pos/terminals/{terminalId}/providersphysical_pos:manage
PATCH/api/v1/physical-pos/terminal-providers/{terminalProviderId}physical_pos:manage

A row is tied to the provider's vendor account (vendorAccountId). You add the provider account and its secret credentials on the Integrations screen in the panel; there is no API endpoint for this. Supported provider today: METROPOL.

  • A test key reads rows; writes get 403 physical_pos.environment.test_key_read_only.
  • Writes are subject to the terminal write rate limit: 30 requests per API key in 60 seconds.

The provider row object

FieldTypeDescription
idstringThe row's ID. You send it as terminalProviderId on a payment.
terminalIdstringLogical terminal.
environmentstringLIVE or TEST.
providerCodestringCard provider, e.g. METROPOL. Comes from the linked vendor account.
vendorAccountIdstringThe provider's vendor account.
merchantCodestringMerchant code at the provider.
terminalCodestringTerminal code at the provider.
productCodestring | nullProduct code at the provider.
labelstring | nullYour own description.
providerStatusstringACTIVE or DISABLED. Payments are taken only with an ACTIVE row.
rowVersionintegerThe record's version; you send it when updating.
createdAt, updatedAtstringCreation and last change.

List

GET /api/v1/physical-pos/terminals/{terminalId}/providers · physical_pos:view

Takes limit (1–100, default 25), cursor and includeTotal. The response is { "items": [ … ], "pageInfo": { … } }; each item is a provider row.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/terminals/00000000-0000-0000-0000-000000000301/providers"
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"

Add

POST /api/v1/physical-pos/terminals/{terminalId}/providers · physical_pos:manage

The Idempotency-Key header is required. A new row returns 201; repeating with the same key and the same body returns 200 and replayed: true.

FieldTypeRequiredDescription
vendorAccountIdstring (UUID)YesThe provider's vendor account in the same environment.
merchantCodestringYesMerchant code. METROPOL: 10 digits.
terminalCodestringYesTerminal code. METROPOL: 10 digits.
productCodestringDepends on providerProduct code. Required for METROPOL: 1–5 digits, not starting with zero.
labelstringNoUp to 64 characters.

A code in the wrong format gets 400 physical_pos.input.code_invalid (details.field); the value is not echoed in the response.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/terminals/00000000-0000-0000-0000-000000000301/providers"
BODY='{"vendorAccountId":"00000000-0000-0000-0000-000000000601","merchantCode":"1234567890","terminalCode":"0987654321","productCode":"1","label":"Register 1 meal card"}'
lunixi_sign POST "$REQ_PATH" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: 5f2a7c9e-1b4d-4a8e-9c3f-6d0b8e2a4c71" \
  --data-raw "$BODY"

The example shows the data field.

{
  "provider": {
    "id": "00000000-0000-0000-0000-000000000351",
    "terminalId": "00000000-0000-0000-0000-000000000301",
    "environment": "LIVE",
    "providerCode": "METROPOL",
    "vendorAccountId": "00000000-0000-0000-0000-000000000601",
    "merchantCode": "1234567890",
    "terminalCode": "0987654321",
    "productCode": "1",
    "label": "Register 1 meal card",
    "providerStatus": "ACTIVE",
    "rowVersion": 1,
    "createdAt": "2026-01-02T09:00:00.000Z",
    "updatedAt": "2026-01-02T09:00:00.000Z"
  },
  "replayed": false
}
  • If the terminal already has an active row for the same provider, or the same merchant and terminal code pair is active on another terminal in your account: 409 physical_pos.terminal_provider.duplicate.
  • If the vendor account is not a payment provider account: 400 physical_pos.vendor_account.vendor_not_supported; if the account does not exist: 404 physical_pos.vendor_account.not_found.

Update

PATCH /api/v1/physical-pos/terminal-providers/{terminalProviderId} · physical_pos:manage

Changes the row's label or disables the row. Codes cannot be changed; disable a row with wrong codes and add a new one.

FieldTypeRequiredDescription
rowVersionintegerYesThe row's rowVersion as you read it.
labelstring | nullNoNew label; null or "" removes it.
statusstringNoACTIVE or DISABLED.

Send at least one of label and status; if neither is present: 400 physical_pos.input.empty_patch. The response is { "provider": { … } }.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/terminal-providers/00000000-0000-0000-0000-000000000351"
BODY='{"rowVersion":1,"status":"DISABLED"}'
lunixi_sign PATCH "$REQ_PATH" "$BODY"
 
curl -X PATCH "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

Errors

HTTPcodeWhen
400physical_pos.idempotency.key_required · .key_invalidOn add, Idempotency-Key missing or malformed.
400physical_pos.input.code_invalidA code or status is malformed (details.field).
400physical_pos.input.empty_patchNothing to change on update.
400physical_pos.vendor_account.vendor_not_supportedThe vendor account is not a closed-loop card provider.
403physical_pos.environment.test_key_read_onlyThe write was made with a test key.
404physical_pos.terminal.not_foundThe terminal does not exist, is not yours or lives in the other environment.
404physical_pos.terminal_provider.not_foundProvider row not found.
404physical_pos.vendor_account.not_foundVendor account not found.
409physical_pos.terminal_provider.duplicateAn active row for the same provider, or the same code pair, already exists.
409physical_pos.terminal.closedThe terminal is closed.
409physical_pos.version_conflictrowVersion is not current.
409physical_pos.idempotency_mismatchThe key was used with a different body.
429RATE_LIMITEDRate limit exceeded.

All codes: Error Codes.