Card Provider Rows
- Base path
/api/v1/physical-pos- Identity
- Ed25519 request signature on every request —
X-Key-Id,X-Date,X-Nonce,X-Signature, plusDigeston 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 gets403 PRODUCT_NOT_ENABLED; without the scope403 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.
| Method | Path | Scope |
|---|---|---|
GET | /api/v1/physical-pos/terminals/{terminalId}/providers | physical_pos:view |
POST | /api/v1/physical-pos/terminals/{terminalId}/providers | physical_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
| Field | Type | Description |
|---|---|---|
id | string | The row's ID. You send it as terminalProviderId on a payment. |
terminalId | string | Logical terminal. |
environment | string | LIVE or TEST. |
providerCode | string | Card provider, e.g. METROPOL. Comes from the linked vendor account. |
vendorAccountId | string | The provider's vendor account. |
merchantCode | string | Merchant code at the provider. |
terminalCode | string | Terminal code at the provider. |
productCode | string | null | Product code at the provider. |
label | string | null | Your own description. |
providerStatus | string | ACTIVE or DISABLED. Payments are taken only with an ACTIVE row. |
rowVersion | integer | The record's version; you send it when updating. |
createdAt, updatedAt | string | Creation 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.
| Field | Type | Required | Description |
|---|---|---|---|
vendorAccountId | string (UUID) | Yes | The provider's vendor account in the same environment. |
merchantCode | string | Yes | Merchant code. METROPOL: 10 digits. |
terminalCode | string | Yes | Terminal code. METROPOL: 10 digits. |
productCode | string | Depends on provider | Product code. Required for METROPOL: 1–5 digits, not starting with zero. |
label | string | No | Up 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.
| Field | Type | Required | Description |
|---|---|---|---|
rowVersion | integer | Yes | The row's rowVersion as you read it. |
label | string | null | No | New label; null or "" removes it. |
status | string | No | ACTIVE 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
| HTTP | code | When |
|---|---|---|
400 | physical_pos.idempotency.key_required · .key_invalid | On add, Idempotency-Key missing or malformed. |
400 | physical_pos.input.code_invalid | A code or status is malformed (details.field). |
400 | physical_pos.input.empty_patch | Nothing to change on update. |
400 | physical_pos.vendor_account.vendor_not_supported | The vendor account is not a closed-loop card provider. |
403 | physical_pos.environment.test_key_read_only | The write was made with a test key. |
404 | physical_pos.terminal.not_found | The terminal does not exist, is not yours or lives in the other environment. |
404 | physical_pos.terminal_provider.not_found | Provider row not found. |
404 | physical_pos.vendor_account.not_found | Vendor account not found. |
409 | physical_pos.terminal_provider.duplicate | An active row for the same provider, or the same code pair, already exists. |
409 | physical_pos.terminal.closed | The terminal is closed. |
409 | physical_pos.version_conflict | rowVersion is not current. |
409 | physical_pos.idempotency_mismatch | The key was used with a different body. |
429 | RATE_LIMITED | Rate limit exceeded. |
All codes: Error Codes.