Meal Card Sale
- 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:payments. 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.
A meal card payment is started from the same endpoint as a bank card sale: POST /api/v1/physical-pos/payments. The difference is in three fields: instrument: "MEAL_CARD", interaction, which says how the payment is taken on the device, and the card provider row to use (terminalProviderId). The payment runs on the Lunixi server through the card provider rather than a bank; statuses, webhooks and getting the outcome work as for a card sale. → Sale (Charge a Card)
Setup:
- Add the card provider's vendor account on the Integrations screen in the panel.
- Add the provider row to the logical terminal the device is linked to. → Card Provider Rows
- The device model must support meal cards. A device that does not gets
422 physical_pos.payment.operation_unsupported(details.reason:instrument_unsupported).
Payment method: interaction
| Value | What happens on the device |
|---|---|
INSTRUMENT_READ | The device asks for the card to be tapped (contactless). |
CODE_DISPLAY | The device shows a QR or short code on its screen; the customer scans and approves it in their card app. The code is sent only to the device and is not in the API response. |
Lunixi Android application
Terminal app 0.1.4 (5) consumes the cashier provider extension in protocol package 3.6.0. It retains Metropol QR display, NFC UID reading and server-issued outcome display from 0.1.3. The API request's CODE_DISPLAY value becomes a signed DISPLAY_CODE device command. The app renders the QR locally and shows the short code and remaining time. INSTRUMENT_READ reads only the UID of supported MIFARE cards through the standard Android NFC service. Provider credentials and calls that charge through Metropol stay on the server.
A debug device test requires a LIVE device with an operator sandbox lock, a sandbox provider account, signed device configuration enabling the payment method and a terminal provider link. The provider must also configure the product pool.
In cashier mode, an authorized cashier can sign in with a PIN and select an offered provider row and QR/NFC interaction. Options come from providerPaymentOptions in the signed device GET cashiers response, refreshed when the screen opens and at sign-in. An empty or missing list offers no provider API method. The device adds instrument: MEAL_CARD, interaction and the selected terminalProviderId to POST cashier-payments; it omits installments and items. Bank-card and reversal requests omit provider-selection fields. These endpoints use device identity and cashier authorization; external integrations continue using the merchant API on this page.
The selection is persisted before the first request. Removing an offer never switches the payment method automatically. A missing response leads to a lookup of the same idempotency record, without another charge request. Discovery is not authorization; the server checks permissions, limits, terminal eligibility and sandbox alignment again at payment time. This delivery does not claim v8 scoped settlement or DEVICE_INFO support; those remain separate work.
This Android source delivery does not establish physical-device or financial acceptance. A vendor reader integration is needed when the POS does not expose standard Android NFC; a device without NFC can display QR. These flows remain disabled in the SoftPOS composition until mandatory device trust is accepted. Test balance, customer QR approval, physical card UID byte order and the provider outcome must be verified on a device.
Each command can produce at most one NFC reading event. The encrypted device outbox retains the event until delivery is acknowledged; the card UID is excluded from the screen and logs. Expiry, network loss or moving the app to the background closes QR/reading; none proves that the payment failed. Do not charge the same payment again; query its outcome. The server's OUTCOME_DISPLAY command displays the result.
Request
All rules of a sale request apply; these fields are added or changed:
| Field | Type | Required | Description |
|---|---|---|---|
operation | string | Yes | SALE only. |
instrument | string | Yes | MEAL_CARD. |
interaction | string | Yes | INSTRUMENT_READ or CODE_DISPLAY. Not sent on a card sale. |
terminalProviderId | string (UUID) | Conditional | The provider row to use. May be omitted when exactly one active row on the terminal fits this payment. Not sent on a card sale. |
Do not send installmentCount, items or terminalAcquirerId on a meal card payment.
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments"
BODY='{"operation":"SALE","target":{"deviceId":"00000000-0000-0000-0000-000000000401"},"amountMinor":"4450","currency":"TRY","instrument":"MEAL_CARD","interaction":"CODE_DISPLAY","terminalProviderId":"00000000-0000-0000-0000-000000000351","merchantReference":"ORD-2026-000124"}'
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: 9d1e3b5a-7c2f-4e8b-a6d0-1f4c8b2e6a93" \
--data-raw "$BODY"As with a card sale, the response returns 202 with paymentStatus: "NOT_STARTED"; the payment's instrument field is MEAL_CARD. → The Payment Object
Choosing the provider row
If you do not send terminalProviderId, Lunixi picks the single active row on the device's linked terminal whose provider offers this payment method (interaction).
| Situation | Result (422 physical_pos.payment.operation_unsupported) |
|---|---|
| No matching row | details.reason: provider_terminal_missing |
| More than one matching row | provider_terminal_ambiguous — send terminalProviderId. |
| The row you sent is on another terminal, not active, or does not offer this method | provider_terminal_not_found |
| The row's vendor account is not active | provider_account_inactive |
| For a card read, the provider's card types are not defined | instrument_types_undefined |
Code expiry and outcome
With CODE_DISPLAY the code has a validity period that depends on the provider. Lunixi queries the provider during that time:
| Situation | paymentStatus | statusReason |
|---|---|---|
| The customer approved | APPROVED | — |
| The code expired, no payment was made | EXPIRED | PROVIDER_CODE_EXPIRED |
| The query period ended without a definite outcome | UNKNOWN | PROVIDER_CODE_WINDOW_ELAPSED |
Do not restart an UNKNOWN payment; money may have been taken. → Uncertain Outcome If an approval arrives later for an expired payment, the status does not change; the payment gets outcomeConflict: true and you review it in the panel.
Void and refund
A meal card sale can be voided, refunded and partially refunded. The reversal is started from the same endpoint as for a card sale and runs through the sale's provider row; you do not send interaction or terminalProviderId on a reversal request.
details.reason (422 physical_pos.payment.operation_unsupported) | Meaning |
|---|---|
original_provider_link_missing | The sale's provider row information was not found. |
original_terminal_closed | The sale's terminal is closed. |
A payment that has not reached the device can be cancelled before it starts; the card read or code screen on the device closes.
Payment webhooks do not carry the payment instrument. To tell a meal card payment from a card payment, read the payment (instrument). → Retrieve a Payment
Errors
In addition to sale errors:
| HTTP | code | When |
|---|---|---|
400 | physical_pos.validation.invalid | interaction missing or invalid; interaction or terminalProviderId sent on a card sale; terminalAcquirerId sent on a meal card; terminalProviderId not a UUID (details.field). |
400 | physical_pos.payment.installment_unsupported | Instalments on a meal card (details.reason: instrument). |
422 | physical_pos.payment.operation_unsupported | instrument_unsupported, instrument_operation_unsupported (operation other than SALE), items_instrument_unsupported (items sent) or the provider row reasons. |
All codes: Error Codes.