> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loyalty.xeniamoments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Member identification

> How a card becomes a loyalty ID through Nexi Engage, what the loyalty ID is, and what happens when no member is found.

## Lookup

The lookup is part of the card payment itself. There is no separate tap.

<Tabs>
  <Tab title="Windows POS (BAXI / Viking)">
    The POS calls the Viking terminal through BAXI. The lookup is **action 193
    (`getasset`)** with the card reference (`cardref`) only. The terminal reaches
    Nexi Engage through Nexi's DAM, which requires the store (BAX) to be enrolled;
    see [Store enrollment](/architecture/store-enrollment). No Nexi token is
    distributed to terminals.
  </Tab>

  <Tab title="Android mPOS (Softpay)">
    Softpay calls the Nexi Engage backend directly. No store enrollment is needed
    (Nexi, 31 Aug 2026). The result is the same loyalty ID.
  </Tab>
</Tabs>

The result is either a **loyalty ID** or "not found". OnlinePOS stores the loyalty
ID on the order (tag, Phase 1) and, when the REKOM module is active, includes it in
the basket call.

## The loyalty ID

Version 1 used `memberID` in prose and `loyaltyID` in the 4 Sep lookup example.
Version 2 says "loyalty ID" in prose and writes `loyaltyId` in payload examples.
The payload name is directional: REKOM adopts whatever OnlinePOS uses by default.

| Property | Value |
| - | - |
| Meaning | The identifier Nexi Engage returns for a recognised card. It is REKOM's member identifier for that guest, as registered by REKOM with Nexi Engage. |
| Format | Opaque string. Exact length and character set follow Nexi's `getasset` constraints and are **open** (owner: Nexi). OnlinePOS should treat it as an opaque string of up to 64 characters. |
| PII | None. The loyalty ID carries no name, email, phone or card data. |
| Stability | Stable per member. One member may have several cards; all resolve to the same loyalty ID. |
| Ownership | REKOM creates and manages members and their cards. OnlinePOS never creates members in Nexi Engage (*agreed 12 Aug 2026*). |

## Not-found path

```mermaid theme={null}
sequenceDiagram
  participant S as Staff
  participant P as POS/mPOS
  participant T as Terminal / Softpay
  participant N as Nexi Engage
  participant B as OnlinePOS backend
  participant R as REKOM backend

  S->>P: Card payment
  P->>T: Start payment (prepurchase)
  T->>N: getasset(cardref)
  alt Member found
    N-->>T: loyaltyId
    T-->>P: loyaltyId
    P->>B: basket + loyaltyId + calculationId
    B->>R: POST /v1/onlinepos/basket
    R-->>B: applied / unchanged / member_not_found
  else No member
    N-->>T: not found
    T-->>P: no loyaltyId
    Note over P: status member_not_found<br/>no REKOM call
  end
  P->>T: Authorise final amount (single approval)
```

* **Lookup returns no member:** OnlinePOS sets the order's loyalty status to `member_not_found` and
  completes the sale with the original basket. No REKOM call is made.
* **Lookup fails technically** (terminal offline, DAM unreachable): same as above
  from the guest's point of view; the order's loyalty status is `member_not_found` or
  `failed` depending on what OnlinePOS can distinguish. The lookup "fails in a
  controlled way without blocking payment" (V1 §14, carried over).
* **Lookup returns a loyalty ID the REKOM backend does not know:** the REKOM
  backend answers `200` with status `member_not_found`. This can happen when a
  card was enrolled in Nexi Engage but the member was later deleted in REKOM.

## Enrolling guests and cards

Enrolling a guest into the programme, and linking their payment card to their
loyalty ID in Nexi Engage, is REKOM's concern and happens in REKOM's channels. It
is out of scope for OnlinePOS. The channel REKOM uses (Nexi Engage API versus a
terminal action) is a REKOM-internal decision and is listed in the open points for
completeness only.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.