Physical POS
Payment Operations
The Payment Object

The Payment Object

For invoice, buyer and fiscal-document fields, and the sale application registration awaiting release, see Sales data and support status. merchantReference does not provide an invoice number or fiscal validation.

Every payment endpoint returns the payment as the same object. This page describes its fields, which device the payment runs on (target) and which bank it goes through (terminalAcquirerId).

Payment object

Every endpoint returns the payment as the same object. Reversals (void, refund, pre-authorisation close and cancel) are separate payment records linked to the original payment (child payments); the original payment is the root.

FieldTypeDescription
paymentIdstring (UUID)The payment's ID. Sortable by time (UUIDv7).
rootPaymentIdstring (UUID)The root's ID. On the root, its own ID.
originalPaymentIdstring | nullOn a child payment, the original payment's ID; null on the root.
originstringAPI: the payment was started from the API or the panel. DEVICE_DIRECT: the sale was made directly on the device.
operationstringRoot: SALE, PREAUTH_OPEN, REFUND_UNMATCHED. Child: VOID, REFUND, PREAUTH_CLOSE, PREAUTH_CANCEL.
paymentStatusstringThe payment's status. → Payment statuses
statusReasonstring | nullReason of the last transition. → statusReason
outcomeConflictbooleantrue if evidence contradicting the outcome arrived. The status does not change; review the payment in the panel.
resolvablebooleantrue if a MANUAL_REVIEW payment can be resolved in the panel.
deviceIdstring (UUID)The device that runs the operation.
logicalTerminalIdstring | nullThe logical terminal the operation runs on.
terminalAcquirerIdstring | nullThe operation's bank row. null: the device chose the bank. → Bank row
channelstringCommunication channel with the device: APP2APP, LOCAL_REST or VENDOR_CLOUD.
vendorReferencestring | nullThe payment's reference on the device side: paymentId without hyphens. You see this value on the device receipt and in the vendor's records.
amountMinorstringRequested amount, in minor units.
approvedAmountMinorstring | nullApproved amount. null until an outcome arrives; lower than amountMinor on a partial approval.
currencystringISO 4217 currency.
installmentCountinteger | nullInstallment count; null for a single payment.
instrumentstringPayment instrument. CARD or MEAL_CARD (meal card) on a payment started from the API or the panel. On a sale made directly on the device (origin: "DEVICE_DIRECT") one of CARD, MEAL_CARD, QR, WALLET, CASH, BANK_TRANSFER or OTHER; the value set can grow; your code should not fail on a value it does not recognise.
merchantReferencestring | nullYour reference.
cashierobject | nullIf the payment was started on the device in a cashier session, the cashier: { "cashierId": "…", "cashierCode": "…", "displayName": "…" }. displayName is the cashier's current name. Cashiers are managed in the panel. null if there is no cashier.
reversedMinorstringOn the root: total of approved refunds, void and pre-authorisation cancel.
capturedMinorstringOn the root: amount captured by pre-authorisation close.
reversalReservedMinorstringOn the root: amount held by a reversal that has not completed.
pendingReversalIdstring | nullOn the root: paymentId of the reversal that has not completed.
reversalStatusstringOn the root: combined effect of reversals. → reversalStatus
expiresAtstring | nullLast moment for the payment to start on the device.
resultDeadlineAtstring | nullLast moment the outcome is awaited; after it the payment becomes UNKNOWN.
completedAtstring | nullWhen the payment reached its final status.
settledAtstring | nullWhen the end-of-day that includes the payment ran; null if the payment is not in an end-of-day. When it is filled on a root, a void is not possible; refund instead. → End of day and voids
settlementBatchNostring | nullThe number of the end-of-day that includes the payment; null if none.
createdAtstringCreation time.
updatedAtstring | nullLast change time.
rowVersionintegerRecord version; increases with every status change.
historySeqintegerSequence number in the status history. Use it to check webhook order. → Ordering and duplicates
tenderobject | nullCard outcome; see below.
itemsarraySale items. Filled only in the GET /payments/{paymentId} and transaction detail responses and on a sale with items; an empty array elsewhere. → Items
refundItemsarrayLines of an item refund. Filled only in the GET /payments/{paymentId} and transaction detail responses and on an item refund. → Items

tender object:

FieldTypeDescription
tenderStatusstringPENDING, APPROVED, PARTIALLY_APPROVED, DECLINED, CANCELLED or UNKNOWN.
cardMaskedstring | nullMasked card number: first 6 and last 4 digits (454360******1234) or the last 4 digits only.
cardBrandstring | nullVISA, MASTERCARD, TROY, AMEX, UNIONPAY or OTHER.
entryModestring | nullHow the card was read: CHIP, CONTACTLESS, SWIPE, MANUAL, QR or OTHER.
acquirerCodestring | nullFour-digit code of the bank that processed the operation. → Catalog › Banks
authCodestring | nullThe bank's authorisation code.
rrnstring | nullThe bank's retrieval reference number (RRN).

The full card number, the expiry date and the security code never appear in any response.

Target device

A payment always runs on a device. In the target object you name the device in exactly one of these forms:

FormDescription
{ "deviceId": "…" }The device's ID. → Devices
{ "vendorCode": "…", "serialNumber": "…" }Vendor code and serial number. The vendor code is required (PAVO, CASTLES or PLUSPAY); the serial is compared with the rule of the device record. → Serial number format
{ "externalRef": "…" }The externalRef you gave when registering the device.
  • A missing, multiple or malformed target gets 400 physical_pos.payment.target_invalid; details.reason: none, multiple, vendor_code_required, device_id_invalid, external_ref_invalid or invalid (target is not an object).
  • An unknown vendor code gets 400 physical_pos.device.vendor_unknown.
  • If a target field is not a string or exceeds its length limit (deviceId 64, vendorCode 32, serialNumber and externalRef 128 characters), the request gets the field's typed code: physical_pos.payment.target_invalid for deviceId (device_id_invalid), physical_pos.payment.target_invalid for externalRef (external_ref_invalid), physical_pos.device.vendor_unknown for vendorCode (invalid), physical_pos.input.serial_invalid for serialNumber (invalid if not a string, too_long if too long). details.field gives the field's dotted path (such as target.serialNumber). An undefined field inside target gets 400 VALIDATION_ERROR.
  • A device that is not found, belongs to another organization or the other environment, or is retired gets the same answer: 404 physical_pos.device.not_found.
  • The payment runs on the logical terminal the device is linked to. If the device is not linked to a terminal: 409 physical_pos.payment.terminal_not_payable (details.reason: not_linked). → Device Link
  • Targeting by store, register or terminal ID is not available.

To take payments:

  • the device must be lifecycleStatus: "ACTIVE" and ownershipStatus: "VERIFIED"; otherwise 409 physical_pos.payment.device_not_payable (details.reason: ownership_unverified, lifecycle_<status>, or pairing_hold with details.retryAfterSeconds);
  • the device's communication channel must be set; a device with integrationChannel: "UNSET" gets 422 physical_pos.payment.operation_unsupported (details.reason: channel_unset);
  • the terminal must be open and active; otherwise 409 physical_pos.payment.terminal_not_payable (details.reason: status_<status> or ownership_unverified);
  • the device must be ready for payment: connected, with the Lunixi app and the payment app on the device working. Otherwise 409 physical_pos.payment.device_offline (details.retryable: true); if Lunixi cannot verify the device's status at that moment, 503 physical_pos.presence.unavailable. The payment is not queued; start it again when the device is ready. You can see why the device is not ready in presence.notReadyReason on the device detail. → Device readiness

Bank row

You decide which bank the payment goes through in one of two ways:

  • You send terminalAcquirerId: the id of one of the terminal's bank rows. The row must be acquirerStatus: "ACTIVE" and mappingStatus: "MAPPED", and must list the payment's currency in currencies. Otherwise 422 physical_pos.payment.operation_unsupported (details.reason: terminal_acquirer_not_eligible).
  • You do not send it: the device or the payment application on the device chooses the bank; Lunixi does not choose, even when the terminal has a single bank row. The payment's terminalAcquirerId is null.

Reversals do not take terminalAcquirerId; the bank follows the reversal rules.

App identity

On SoftPOS devices and devices connected through an app (APP2APP and LOCAL_REST channels), payments and reversals require identity to be enabled in the App Appearance settings in the panel, with an active publishable key that matches the device's environment selected. Otherwise the request gets 422 physical_pos.payment.identity_required:

details.reasonMeaning
disabledIdentity is disabled.
key_missingNo key is selected, or it does not match the device's environment.
key_not_owned, key_inactive, key_product_missingThe selected key is not yours, is not active, or does not have the Physical POS product.
key_changedThe selected key changed during the request; retry.

Cancel before start is not subject to this check. If the key state cannot be read, 503 physical_pos.dependency.unavailable is returned.