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.
| Field | Type | Description |
|---|---|---|
paymentId | string (UUID) | The payment's ID. Sortable by time (UUIDv7). |
rootPaymentId | string (UUID) | The root's ID. On the root, its own ID. |
originalPaymentId | string | null | On a child payment, the original payment's ID; null on the root. |
origin | string | API: the payment was started from the API or the panel. DEVICE_DIRECT: the sale was made directly on the device. |
operation | string | Root: SALE, PREAUTH_OPEN, REFUND_UNMATCHED. Child: VOID, REFUND, PREAUTH_CLOSE, PREAUTH_CANCEL. |
paymentStatus | string | The payment's status. → Payment statuses |
statusReason | string | null | Reason of the last transition. → statusReason |
outcomeConflict | boolean | true if evidence contradicting the outcome arrived. The status does not change; review the payment in the panel. |
resolvable | boolean | true if a MANUAL_REVIEW payment can be resolved in the panel. |
deviceId | string (UUID) | The device that runs the operation. |
logicalTerminalId | string | null | The logical terminal the operation runs on. |
terminalAcquirerId | string | null | The operation's bank row. null: the device chose the bank. → Bank row |
channel | string | Communication channel with the device: APP2APP, LOCAL_REST or VENDOR_CLOUD. |
vendorReference | string | null | The payment's reference on the device side: paymentId without hyphens. You see this value on the device receipt and in the vendor's records. |
amountMinor | string | Requested amount, in minor units. |
approvedAmountMinor | string | null | Approved amount. null until an outcome arrives; lower than amountMinor on a partial approval. |
currency | string | ISO 4217 currency. |
installmentCount | integer | null | Installment count; null for a single payment. |
instrument | string | Payment 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. |
merchantReference | string | null | Your reference. |
cashier | object | null | If 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. |
reversedMinor | string | On the root: total of approved refunds, void and pre-authorisation cancel. |
capturedMinor | string | On the root: amount captured by pre-authorisation close. |
reversalReservedMinor | string | On the root: amount held by a reversal that has not completed. |
pendingReversalId | string | null | On the root: paymentId of the reversal that has not completed. |
reversalStatus | string | On the root: combined effect of reversals. → reversalStatus |
expiresAt | string | null | Last moment for the payment to start on the device. |
resultDeadlineAt | string | null | Last moment the outcome is awaited; after it the payment becomes UNKNOWN. |
completedAt | string | null | When the payment reached its final status. |
settledAt | string | null | When 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 |
settlementBatchNo | string | null | The number of the end-of-day that includes the payment; null if none. |
createdAt | string | Creation time. |
updatedAt | string | null | Last change time. |
rowVersion | integer | Record version; increases with every status change. |
historySeq | integer | Sequence number in the status history. Use it to check webhook order. → Ordering and duplicates |
tender | object | null | Card outcome; see below. |
items | array | Sale items. Filled only in the GET /payments/{paymentId} and transaction detail responses and on a sale with items; an empty array elsewhere. → Items |
refundItems | array | Lines of an item refund. Filled only in the GET /payments/{paymentId} and transaction detail responses and on an item refund. → Items |
tender object:
| Field | Type | Description |
|---|---|---|
tenderStatus | string | PENDING, APPROVED, PARTIALLY_APPROVED, DECLINED, CANCELLED or UNKNOWN. |
cardMasked | string | null | Masked card number: first 6 and last 4 digits (454360******1234) or the last 4 digits only. |
cardBrand | string | null | VISA, MASTERCARD, TROY, AMEX, UNIONPAY or OTHER. |
entryMode | string | null | How the card was read: CHIP, CONTACTLESS, SWIPE, MANUAL, QR or OTHER. |
acquirerCode | string | null | Four-digit code of the bank that processed the operation. → Catalog › Banks |
authCode | string | null | The bank's authorisation code. |
rrn | string | null | The 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:
| Form | Description |
|---|---|
{ "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_invalidorinvalid(targetis not an object). - An unknown vendor code gets
400 physical_pos.device.vendor_unknown. - If a
targetfield is not a string or exceeds its length limit (deviceId64,vendorCode32,serialNumberandexternalRef128 characters), the request gets the field's typed code:physical_pos.payment.target_invalidfordeviceId(device_id_invalid),physical_pos.payment.target_invalidforexternalRef(external_ref_invalid),physical_pos.device.vendor_unknownforvendorCode(invalid),physical_pos.input.serial_invalidforserialNumber(invalidif not a string,too_longif too long).details.fieldgives the field's dotted path (such astarget.serialNumber). An undefined field insidetargetgets400 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"andownershipStatus: "VERIFIED"; otherwise409 physical_pos.payment.device_not_payable(details.reason:ownership_unverified,lifecycle_<status>, orpairing_holdwithdetails.retryAfterSeconds); - the device's communication channel must be set; a device with
integrationChannel: "UNSET"gets422 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>orownership_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 inpresence.notReadyReasonon the device detail. → Device readiness
Bank row
You decide which bank the payment goes through in one of two ways:
- You send
terminalAcquirerId: theidof one of the terminal's bank rows. The row must beacquirerStatus: "ACTIVE"andmappingStatus: "MAPPED", and must list the payment's currency incurrencies. Otherwise422 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
terminalAcquirerIdisnull.
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.reason | Meaning |
|---|---|
disabled | Identity is disabled. |
key_missing | No key is selected, or it does not match the device's environment. |
key_not_owned, key_inactive, key_product_missing | The selected key is not yours, is not active, or does not have the Physical POS product. |
key_changed | The 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.