Physical POS
Payment Operations
Meal Card Sale

Meal Card Sale

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:payments. 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.

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:

  1. Add the card provider's vendor account on the Integrations screen in the panel.
  2. Add the provider row to the logical terminal the device is linked to. → Card Provider Rows
  3. 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

ValueWhat happens on the device
INSTRUMENT_READThe device asks for the card to be tapped (contactless).
CODE_DISPLAYThe 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:

FieldTypeRequiredDescription
operationstringYesSALE only.
instrumentstringYesMEAL_CARD.
interactionstringYesINSTRUMENT_READ or CODE_DISPLAY. Not sent on a card sale.
terminalProviderIdstring (UUID)ConditionalThe 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).

SituationResult (422 physical_pos.payment.operation_unsupported)
No matching rowdetails.reason: provider_terminal_missing
More than one matching rowprovider_terminal_ambiguous — send terminalProviderId.
The row you sent is on another terminal, not active, or does not offer this methodprovider_terminal_not_found
The row's vendor account is not activeprovider_account_inactive
For a card read, the provider's card types are not definedinstrument_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:

SituationpaymentStatusstatusReason
The customer approvedAPPROVED—
The code expired, no payment was madeEXPIREDPROVIDER_CODE_EXPIRED
The query period ended without a definite outcomeUNKNOWNPROVIDER_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_missingThe sale's provider row information was not found.
original_terminal_closedThe 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:

HTTPcodeWhen
400physical_pos.validation.invalidinteraction missing or invalid; interaction or terminalProviderId sent on a card sale; terminalAcquirerId sent on a meal card; terminalProviderId not a UUID (details.field).
400physical_pos.payment.installment_unsupportedInstalments on a meal card (details.reason: instrument).
422physical_pos.payment.operation_unsupportedinstrument_unsupported, instrument_operation_unsupported (operation other than SALE), items_instrument_unsupported (items sent) or the provider row reasons.

All codes: Error Codes.