> ## 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.

# Store enrollment

> How a BAX (terminal setup) is enrolled with Nexi Engage so that Viking terminals can look up members: Option 1, decided 2 Sep 2026.

<Check>
  **Agreed 2 Sep 2026 (Option 1).** OnlinePOS adds an "Integrations" tab in Backoffice
  terminal setup with a **"Nexi Engage Store ID"** field. REKOM fills it with the
  venue's **BAX ID**. The OnlinePOS terminal runs store enrollment (`registerstore`,
  BAXI action 114) for all terminal IDs (TIDs) of that terminal setup at every
  terminal startup.
</Check>

## Why enrollment exists

Viking terminals on Windows reach Nexi Engage through Nexi's DAM. DAM only answers
lookups for stores that are enrolled. Softpay on Android calls the Nexi Engage
backend directly and needs no enrollment (Nexi, 31 Aug 2026). Enrollment is
therefore a Windows-only, per-BAX setup step.

## Decisions

| Point | Decision | Agreed |
| - | - | - |
| Store ID value | `storeId` = the **BAX ID** directly, with no prefix for environment or operator. One BAX corresponds to one OnlinePOS terminal setup. | 31 Aug 2026 (REKOM, confirmed by Nexi that `storeId` is free text bound one-to-one to a BAX) |
| Where it lives | A "Nexi Engage Store ID" field on the terminal setup in OnlinePOS Backoffice, entered manually by REKOM. | 2 Sep 2026 |
| Who enrolls | The OnlinePOS terminal itself, at every startup, for all TIDs on that setup. Chosen because it is the least complex option: nothing to schedule, nothing to remember when a BAX is added or a terminal replaced, and a repeat call is harmless. | 2 Sep 2026 |
| Repeated enrollment | Harmless. A second `registerstore` for the same store returns error **212 "Store already registered"**, which the terminal ignores. | 27 and 31 Aug 2026 (Nexi) |
| Lookup | BAXI action 193 (`getasset`) with `cardref` only. No token on terminals. | Implicit in the thread; stated here |

## Alternatives that were not chosen

<Warning>
  **Not chosen.** The options below were on the table between 17 Aug and 2 Sep 2026 and
  were rejected when Option 1 was agreed. They are kept here, with the reason, so that
  nobody re-proposes them without knowing why they were dropped. None of them is part
  of the design.
</Warning>

| Alternative | What it would have meant | Why it was not chosen |
| - | - | - |
| ❌ **Option 2 — REKOM enrolls through an HQ terminal; OnlinePOS does nothing** | REKOM would run `registerstore` for every BAX from a central terminal, and OnlinePOS would assume stores are already enrolled. | More complexity for no gain: a separate enrollment step per BAX, owned by a different party from the one operating the terminals, and nothing self-heals when a BAX is added or a terminal replaced. Letting every terminal enroll at every boot is simpler, and a repeat call is harmless (error 212). Rejected 2 Sep 2026. |
| ❌ **Manual enrollment by Nexi, per store** | Nexi staff add the BAX and terminal IDs plus store name in DAM and in the Nexi Engage database, and activate tokens in Baxbis, for every store (around 20 manual steps). | Manual work for every new BAX, dependent on Nexi's availability. Nexi's own assessment on 20 Aug 2026 was that it is "in no way optimal" and invites ongoing errors. Rejected 2 Sep 2026. |
| ❌ **Composite store ID with operator and environment prefix** | A `storeId` built from an operator code, the BAX ID and the environment. | Dropped the same day it was proposed (31 Aug 2026). One BAX is already one terminal setup and one environment, so the prefix added nothing; the plain BAX ID is used. |
| ⏸ **REKOM-owned enrollment through a DAM API** | A new Nexi API letting the REKOM backend enroll stores without any terminal. | **Parked, not rejected.** Nexi estimated about two months of work; REKOM chose not to wait for it (31 Aug 2026). It may return for non-terminal channels; it is not part of Phase 1 or 2. |

## Flow

```mermaid theme={null}
sequenceDiagram
  participant K as REKOM
  participant BO as OnlinePOS Backoffice
  participant T1 as Terminal TID 1001
  participant T2 as Terminal TID 1002
  participant D as Nexi DAM / Engage

  K->>BO: Enter Nexi Engage Store ID = BAX ID on the terminal setup
  Note over T1,T2: Every terminal startup
  T1->>D: registerstore(storeId = BAX ID)
  D-->>T1: Store registered successfully
  T2->>D: registerstore(storeId = BAX ID)
  D-->>T2: Error 212 Store already registered (ignored)
  Note over T1,T2: Lookups (getasset) now work on every TID of the BAX
```

A terminal added later to the same BAX is already enrolled and needs no action.

## Operational notes

* **Test environments:** test BAX IDs used by OnlinePOS test venues must be
  registered as Nexi **test** stores, and they map to the REKOM staging host.
* **Replacing a terminal** does not change the BAX, so nothing changes in Backoffice.
* **Moving to one BAX per venue** is a REKOM-internal consolidation and does not
  affect this design; whatever BAX a terminal setup uses is the value in the field.

## Open point: the one-time store token

<Warning>
  **Open — OnlinePOS + Nexi.** Nexi's original enrollment flow (17 Aug 2026) had the
  REKOM backend fetch a one-time JWT store token from the Nexi Engage API, keyed by
  `storeId`, and pass it to the ECR for `registerstore`. Option 1 only describes
  entering the Store ID in Backoffice. Still to be settled:

  1. Whether `registerstore` from the terminal needs that token at all, or whether DAM
     accepts the call for a known BAX without it.
  2. If a token is needed: who fetches it (REKOM backend or OnlinePOS backend), how it
     reaches the terminal, and whether every startup needs a fresh one, given that
     the call repeats at each startup and the error 212 path was only discussed for
     an already-registered store name.
  3. Endpoint, credentials and test environment for the store-token API (from Nexi's
     documentation).

  REKOM's proposal: if a token is required, the OnlinePOS backend obtains it from
  Nexi at startup using credentials REKOM provides per environment, so that no
  REKOM call sits in the terminal boot path. Nexi to confirm whether a token is
  needed at all.
</Warning>

A DAM API that would let the REKOM backend enroll stores without a terminal was
estimated by Nexi at roughly two months of work and is **parked** (31 Aug 2026).


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