Physical POS
Payment Operations
Sale Application Identity

Sale Application Identity

This registration primarily identifies restaurant, café, order-management and checkout software integrating with the Lunixi API. When a restaurant system initiates a payment, the source application is that system's registered name and the version that initiated the request.

Implemented, awaiting release. The fields below describe the prepared OS-02 contract. This page does not establish production availability; do not add these fields to existing requests before the release is announced. Invoice, buyer and fiscal-document work has a separate status: Sales data and support status.

Whose name and version?

InitiatorSource applicationVersion source
Your restaurant/café software, through the Lunixi APIYour registered restaurant/café softwareThe software version initiating the request
The Lunixi Android app's own cashier screen, with a cashier PINRegistration selected for that native sale flowThe running Android app's build version
An Android agent transporting an API request to the POSThe original API clientThe original client's version; the bridge version must not replace it

Android agent, Pavo/Castles/PlusPay SDK and fiscal application (GMU) versions are separate execution facts. They do not replace the originating restaurant software's name/version. Forwarding the source identity into every vendor SDK and recording additional execution evidence are not completed by this package.

Panel registration

The existing form remains available in the implementation: Physical POS → Sale Applications. A merchant panel user with physical_pos:manage registers the official software name; reading requires physical_pos:view.

  • Each registration has a permanent UUID and official name. The UUID is not an API key or authentication secret.
  • Registrations are merchant-scoped; another merchant's registration cannot be used.
  • Up to 32 registrations are supported. Disable a registration to stop using it; IDs cannot be deleted or reused.
  • Versions are not entered in this form. The initiating software supplies its version with the payment request.
  • Registered source details can be required for new requests. Removing that requirement additionally requires physical_pos:identity.

This form does not establish a completed central partner/publisher portal for managing all of an integrator's merchants.

Request context

Example of the extension awaiting release: add this fragment to the existing required payment fields once released; it is not a complete payment request.

{
  "sourceApplication": {
    "applicationId": "a1234567-1234-4234-8234-123456789abc",
    "version": "4.2.1+20261106"
  }
}

Here, version belongs to the example restaurant system. The request does not supply a free-form official name: the server resolves it from an enabled registration belonging to the same merchant. Normal merchant API authentication and payment authorization are still required.

The version has 1–64 ASCII characters: the first is alphanumeric; subsequent characters may be alphanumeric or ., _, +, -. Semver is not required. Do not put card data, PINs, tokens or personal data into this field. The version is a declaration, not remote attestation or a regulatory compliance approval.

Historical facts and retries

At payment admission, the registration ID, registered name, declared version and registration revision are preserved as immutable facts. Renaming a registration does not change historical payments. Reusing an idempotency key with a different version is a mismatch; never restart an uncertain payment with a fresh key.

Current registrations are not used to backfill old payments. An uncertain device outcome requires querying the original payment, not automatic new collection or execution-channel switching.

For new fiscal requests, the registered snapshot is also bound into device content v2; the Android bridge must not replace the original software identity with its own name/version. This requires the fiscal data capability and new reader. Actual SDK delivery and agent/SDK/fiscal software execution evidence require separate acceptance; current identities are not backfilled into historical requests.

Integration origin: serial, fingerprint, sequence and time

Implemented in source; use after production rollout and the compatible Android reader: optional sourceApplication.integrationHandle carries a restaurant/ERP application's original request context across vendors. Add the complete object to normal payment or reversal requests:

{
  "sourceApplication": {
    "applicationId": "a1234567-1234-4234-8234-123456789abc",
    "version": "4.2.1",
    "integrationHandle": {
      "serialNumber": "TEST-SN",
      "fingerprint": "checkout-a",
      "transactionSequence": "9007199254740993",
      "transactionDate": "2026-11-08T00:00:00.000Z"
    }
  }
}
FieldContract
serialNumberExact registered vendor serial/device identity of the resolved merchant-scoped target; 1–128 printable ASCII characters without spaces. It cannot select a different target.
fingerprintStable, non-secret software-instance identifier; 1–256 alphanumeric/./_/:/- characters. Not biometrics, card data or authentication.
transactionSequenceCanonical positive int64 decimal string, at most 9223372036854775807. JSON numbers, leading zeroes, fractions and exponents are rejected. Declared correlation, not a centrally enforced monotonic counter.
transactionDateOriginal business-request time in exact UTC YYYY-MM-DDTHH:mm:ss.SSSZ. Preserve it on retries; it is separate from the fresh API-signature timestamp.

Unknown fields and explicit null are rejected. Do not send credentials, PINs, personal data or card data. Existing authentication and Idempotency-Key requirements remain. Changing any origin fact with the same key conflicts. The sequence alone does not deduplicate a new idempotency key: query/retry the original uncertain payment using its original key.

The immutable registered-application snapshot preserves the origin and returns it only in the authorized merchant payment view. For supported MQTT SALE execution, command-bound encrypted device context v3 also carries it without requiring a fiscal request or creating a fiscal document. Reversal HTTP/server snapshots retain it; command v6 remains SALE-only, so new reversal device-context distribution is outside this extension. A provider's paired REST fingerprint and durable outbound counter remain separate from caller declarations.

Update all backend readers and the relevant Android reader before sending this field. Existing clients continue using the unchanged handle-free contract.