# Overview & Concepts

In this section, you will find a set of guides that walk you through developing and launching a Payments integration with LoyaltyPlant. It is intended to accompany the [Payments API specification](/payments/api/).

## 1. What Payments is

LoyaltyPlant offers a white-label e-commerce, loyalty and marketing platform for restaurant chains. Customers make orders through the mobile or web app, collect loyalty points for online and in-store orders, and spend those points on rewards in the app.

The Payments API allows your payment gateway to be used to process customers' payments on online orders.

**Your integration is that provider.** LoyaltyPlant does not ask you to call it to "create a payment". Instead, LoyaltyPlant
**drives** every payment: it calls a small REST service that you host, one call per payment
operation (authorize, capture, refund, …). Your service translates each call into requests
to your PSP (payment service provider) and returns the outcome.

You are responsible for one thing: **a standalone HTTPS service that implements the
[Payments Integration API](#2-what-you-build)** and talks to your PSP behind it.

## 2. What you build

A standalone HTTPS service that implements the **Payments Integration API** per the
[Payments API specification](/payments/api/).

```mermaid
flowchart LR
    Customer["Customer (app)"] <--> LP["LoyaltyPlant (payments)"]
    LP <-->|HTTPS| You["YOUR integration service"]
    You <-->|HTTPS| PSP["Your PSP"]
    You -.->|"async result callback<br/>POST /gate/integration/{id}/result"| LP
    You -.->|"card token callback<br/>POST /gate/integration/{id}/enrollment-result"| LP
```

- **LoyaltyPlant → your service** — LoyaltyPlant calls your endpoints (`/v1/authorize`,
  `/v1/sale`, …) to run each operation. It authenticates with a bearer token you validate.
- **Your service → your PSP** — how you talk to your PSP is entirely up to you; LoyaltyPlant
  never sees it.
- **Your service → LoyaltyPlant (async)** — when a payment can't finish synchronously (3-D
  Secure, a redirect/hosted page), your PSP later notifies *you*, and you report the final
  result back to LoyaltyPlant with one callback. See [Payment Flows](03-payment-flows.md).
- **Your service → LoyaltyPlant (card tokens)** — if you support tokenization, the same shape
  carries a bound card back to LoyaltyPlant after the customer adds it on your hosted page. See
  [Card enrollment](03-payment-flows.md#5-card-enrollment-and-tokenization).

You only ever expose endpoints to, and call back into, LoyaltyPlant. Everything else in the
LoyaltyPlant platform is internal and out of scope for your integration.

In order to build it, you can use one of two approaches, both of which implement the same API contract:

| | **API integration** | **SDK integration (Java)** |
| --- | --- | --- |
| **How** | Implement the REST endpoints yourself | Add the `payments-integration-sdk` dependency and implement one interface |
| **Language** | Any (Node, Go, Python, .NET, Java, …) | Java / JVM only |
| **You write** | HTTP routing, (de)serialization, auth, idempotency, the endpoints | Just the `PaymentIntegration` methods — a ready-made controller exposes the endpoints |
| **Contract drift risk** | You keep your models in sync with the spec | DTOs are generated from the same spec — no drift |
| **Best when** | You aren't on the JVM, or you want full control | You're a Java shop and want the fastest path |
| **Guide** | [API Integration Guide](05-api-integration-guide.md) | [SDK Integration Guide](04-sdk-integration-guide.md) |

> **Note:** The `payments-integration-sdk` is **not publicly available** — LoyaltyPlant provides
> access to it after the project [kickoff](#31-kickoff).

## 3. Integration project stages

From the first meeting to production traffic, an integration moves through five stages, each
with a clear exit before the next begins.

```mermaid
flowchart LR
    K["1 · Kickoff"] --> D["2 · Development"]
    D --> T["3 · Testing & QA review"]
    T --> C["4 · Certification"]
    C --> P["5 · Pilot deployment"]
```

### 3.1 Kickoff

The project teams from LoyaltyPlant and your side meet. LoyaltyPlant gives a short overview of both
companies, walks through this documentation and the integration process, and agrees on a
communication channel. Afterwards, LoyaltyPlant provisions a **test environment** and shares the
**set of test cases** relevant to your integration.

### 3.2 Development

You build the integration following the [SDK Integration Guide](04-sdk-integration-guide.md) or
[API Integration Guide](05-api-integration-guide.md). Ask questions or request additional working
sessions with LoyaltyPlant whenever you need them. This stage is complete when every item on the
[Integration Checklist](07-integration-checklist.md) is satisfied.

### 3.3 Testing & QA review

You run your own testing against the test cases LoyaltyPlant provided and confirm the integration behaves
correctly, then send a **test report** mapping each test case to the **order ID(s)** you
produced for it. LoyaltyPlant's QA team reviews the integration and your report; if anything is wrong,
LoyaltyPlant flags it, you fix it, and the review repeats until everything passes.

### 3.4 Certification

With the test cases verified, LoyaltyPlant schedules a **demo** where you walk through the key flows in your
product, show where the data LoyaltyPlant needs appears, and answer any open questions. The demo is recorded
for internal training. LoyaltyPlant then officially confirms your integration as **certified**.

### 3.5 Pilot deployment

LoyaltyPlant enables the integration for a **single client at a small number of outlets** and watches it
under real traffic — confirming correct operation, monitoring for failures, and resolving any
issue as a priority. Once the pilot is stable, the integration is **fully approved** and LoyaltyPlant rolls
it out to additional clients and outlets.

---

**Next:** [General Requirements →](02-general-requirements.md)