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

# Integration Description, Version 2

> OnlinePOS × Nexi Engage × REKOM Loyalty — the REKOM-authored Version 2 of the integration description, for OnlinePOS review.

<Warning>
  **This document is directional, and it will be kept up to date as the project moves.**

  Some of the fields, names, structures and flows in it are suggestions, written down
  so there is something concrete to react to. They are not requirements. OnlinePOS
  knows its own system; REKOM asks OnlinePOS to use that expertise to guide the
  implementation: which names fit what already exists, which flows make sense and
  which do not. REKOM is not married to any specific naming or flow. The goal is the
  common, easiest, least complex solution for both sides.

  A concrete example: if this document asks for a `totalDiscount` and OnlinePOS already
  has an `orderDiscount` that works, REKOM wants to be told to use that instead, not to
  have a `totalDiscount` built specifically for REKOM.

  This matters for the success of the project. The question both sides should keep
  asking is **"What would I do if this were my company?"** That is how the solution
  becomes the best possible one.
</Warning>

<Info>
  **Version 2 — 8 October 2026.** This document replaces OnlinePOS's Version 1
  (28 Aug 2026, asynchronous model) and its 4 Sep 2026 update (synchronous model).
  It was agreed on 7 Oct 2026 that REKOM rewrites the description with the clarified
  points and sends it back to OnlinePOS for review. This is that rewrite.
</Info>

## Purpose

REKOM operates a loyalty programme for its guests. When a guest pays by card at an
OnlinePOS till in a REKOM venue, the card is recognised through **Nexi Engage**,
the basket is sent to the **REKOM backend**, and the REKOM backend returns the
basket with the guest's loyalty benefits applied as discounts. The guest approves
one payment on the final amount. OnlinePOS keeps its audit trail unchanged; loyalty
and discount reporting live in REKOM.

This document describes the integration end to end: the systems involved, what
each party is responsible for, the decisions that are already settled, REKOM's
proposals for everything that is not, and a draft API contract for the two
endpoints the REKOM backend exposes to OnlinePOS.

## Parties

| Party | Role in this integration |
| - | - |
| **OnlinePOS** | POS (Windows) and mPOS (Android) software, the OnlinePOS backend and Backoffice, the REST API REKOM already consumes. |
| **Nexi Engage** (formerly Storebox) | Card-based member recognition: store enrollment, member lookup via the payment terminal (BAXI/Viking on Windows) or Softpay (Android). |
| **REKOM** | Owner of the loyalty programme and of the **REKOM backend**: member registry, benefit rules, discount calculation, reporting and reconciliation. |

## How to read this document

Every statement carries one of four statuses, so OnlinePOS can tell at a glance
what is settled and what needs an answer.

<CardGroup cols={2}>
  <Card title="Agreed" icon="check">
    Settled between the parties. The date it was agreed is given in-line, e.g.
    *agreed 7 Oct 2026*. Sources are the shared Google Doc, the
    "Rekom Loyalty Beskrivelse" thread and the "Rekom | Nexi Engage integration" thread.
  </Card>

  <Card title="Proposed" icon="lightbulb">
    REKOM's Version 2 proposal. Marked *proposed — for OnlinePOS confirmation*
    (or Nexi, where relevant). Silence is not acceptance; each one is listed in
    the open points.
  </Card>

  <Card title="Open" icon="circle-question">
    Not yet resolved. Each open point names an owner and, where REKOM has a view,
    REKOM's proposal. See the [open points](/reference/open-points).
  </Card>

  <Card title="Not chosen" icon="ban">
    An alternative that was on the table and was rejected, marked ❌ with the date
    and the reason. Kept so nobody re-proposes it without knowing why it was dropped.
    Example: Option 2 for [store enrollment](/architecture/store-enrollment#alternatives-that-were-not-chosen).
  </Card>
</CardGroup>

<Note>
  **Directional** (see the banner at the top of this page). Wherever this document
  names a field, header, enum value or JSON structure (`calculationId`, `loyaltyId`,
  `noDiscount`, `lineDiscountCode`, the context block, the totals block, the error
  codes, and so on), the name shows *which* information is exchanged, not its spelling.
  REKOM adopts whatever OnlinePOS has by default and does not require any specific
  name. Pages that rely on such names repeat this as a "Directional" note.
</Note>

## Where to start

<CardGroup cols={2}>
  <Card title="Architecture overview" icon="diagram-project" href="/architecture/overview">
    The systems, the two integration surfaces and the context diagram.
  </Card>

  <Card title="Loyalty basket flow" icon="arrow-right-arrow-left" href="/architecture/loyalty-basket-flow">
    The synchronous call, its latency contract, timeouts, fallback and statuses.
  </Card>

  <Card title="Basket rules" icon="receipt" href="/architecture/basket-rules">
    What the REKOM backend may change, the discount code, receipt text, rounding and validation.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Draft OpenAPI 3.1 contract for `POST /v1/onlinepos/basket` and `POST /v1/onlinepos/sale`.
  </Card>

  <Card title="Decision log" icon="list-check" href="/reference/decision-log">
    Every decision with date, status and source.
  </Card>

  <Card title="Open points" icon="clipboard-question" href="/reference/open-points">
    What still needs an answer, who owns it, and what REKOM proposes.
  </Card>
</CardGroup>

## Status of this document

| Item | Status |
| - | - |
| Architecture and phase split | Agreed (14–17 Aug 2026), restated here |
| Synchronous model | Agreed (REKOM request 31 Aug, OnlinePOS acceptance 4 Sep 2026) |
| Store enrollment approach | Agreed (Option 1, 2 Sep 2026). Option 2 and manual enrollment by Nexi **not chosen**; token hand-over open |
| Basket semantics, GUID as a meta attribute, discount code, receipt rules, BAX and terminal identifiers | Agreed (6–7 Oct 2026 and follow-up) |
| Phase 2 scope (every V1 §7 operation) | Agreed, kept from Version 1 |
| One post-sale event, auth, money, latency numbers | Proposed by REKOM in this version |
| Field names, enum values, headers, JSON structures | Directional; not aligned, OnlinePOS defaults win |
| API contract | Draft v0.1, directional: names and structures will follow OnlinePOS defaults |
| Hosts `loyalty.xeniamoments.com` / `loyalty-staging.xeniamoments.com` | TBC |

<Note>
  Commercial terms (estimates, billing) are deliberately outside this document and
  are handled separately between the parties.
</Note>


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