# POS Dejavoo (CPP) Integration — Technical Documentation

This document describes how Dejavoo card-present payments (CPP) are integrated into the Evergreen POS application, including single payments, split payments, resume flows, cancellation handling, and the UX improvements added for staff.

---

## 1. Overview

**Dejavoo** is used as the card-present terminal provider for in-store credit/debit payments. In the UI this is labeled **CPP** (Card Present Payment) with sub-types:

| UI Label        | `dejavooPaymentType` | Stored method on sale |
|-----------------|----------------------|------------------------|
| CPP (Credit)    | `Credit`             | `CPP_Credit`           |
| CPP (Debit)     | `Debit`              | `CPP_Debit`            |
| CPP (generic)   | `CPP`                | `CPP`                  |

Payments are processed synchronously through the Dejavoo **SPIn API** (`/v2/Payment/Sale`). The terminal prompts the customer; the backend waits for approval/decline before continuing.

**Key files**

| Layer    | Path |
|----------|------|
| Service  | `evergreen_pos_be/src/services/payment/dejavoo.service.js` |
| Controller | `evergreen_pos_be/src/controllers/nursery/nursery.product.controller.js` |
| Split utils | `evergreen_pos_be/src/utils/splitPayment.utils.js` |
| Sale service | `evergreen_pos_be/src/services/nursery/sale.service.js` |
| Routes   | `evergreen_pos_be/src/routes/nursery/sale.route.js` |
| Frontend | `evergreen_pos_fe/src/pages/Nuresy/POS/PaymentComponentNew.tsx` |
| Cancel dialog | `evergreen_pos_fe/src/pages/Nuresy/POS/SplitPaymentCancelDialog.tsx` |

---

## 2. Environment Configuration

Set these in the backend `.env`:

| Variable | Purpose | Example |
|----------|---------|---------|
| `DEJAVOO_BASE_URL` | SPIn API base URL | `https://dev.spinpos.net` |
| `DEJAVOO_TPN` or `DEJAVOO_TERMINAL_ID` | Terminal ID (TPN) | Required |
| `DEJAVOO_AUTH_KEY` | Terminal auth key | Required |
| `DEJAVOO_AUTH_TOKEN` | Bearer token (optional) | |
| `DEJAVOO_REGISTER_ID` | Register ID | |
| `DEJAVOO_ISV_ID` | ISV identifier | |
| `DEJAVOO_SALE_PATH` | Sale endpoint | `/v2/Payment/Sale` |
| `DEJAVOO_STATUS_PATH` | Status endpoint | `/v2/Payment/Status` |
| `DEJAVOO_TIMEOUT_MS` | Request timeout | `120000` (2 min) |

If `DEJAVOO_TPN` or `DEJAVOO_AUTH_KEY` is missing, Dejavoo calls fail at startup with a configuration error.

---

## 3. Backend — Dejavoo Service

### 3.1 `createSale`

Sends a sale request to the terminal:

- **Amount** — must be > 0, rounded to 2 decimals in split flow
- **PaymentType** — `Credit`, `Debit`, or `CPP`
- **ReferenceId** — max **50 characters** (Dejavoo API limit)
- **InvoiceNumber** — also capped at 50 characters
- **CustomFields** — metadata sanitized (string only, max 200 chars per field)

### 3.2 Reference ID generation

Long reference IDs caused **HTTP 400** errors on split payments. A dedicated builder keeps IDs short and unique:

```
Single payment:  POS-{timestamp}
Split payment:   POS-S{splitIndex}-{timestamp}
```

Both are truncated to 50 characters via `buildSaleReferenceId()`.

### 3.3 Response parsing

`parseDejavooResponse()` normalizes terminal responses into:

- `status` — `approved` | `declined` | `pending` | `canceled`
- `transactionId` — from RRN / PNReferenceId / ReferenceId
- `authCode`, card last4, EMV data, host messages
- `failureDetails` — user-friendly messages for common decline reasons

### 3.4 Error handling

Axios failures (e.g. 400) are caught and converted to `CustomError` with messages extracted from Dejavoo’s `GeneralResponse` fields, so the frontend shows actionable text instead of generic “Request failed with status code 400”.

Known decline mappings include:

- **Host no response** (code 91 / 1015)
- **Card declined**
- **Terminal canceled**

---

## 4. API Endpoints

| Method | Route | Purpose |
|--------|-------|---------|
| `POST` | `/api/v1/nus-sale/dejavoo-payment` | Single full sale via Dejavoo |
| `GET`  | `/api/v1/nus-sale/dejavoo-payment/:transactionId` | Poll transaction status |
| `POST` | `/api/v1/nus-sale/create-split-sale` | Create pending split sale |
| `POST` | `/api/v1/nus-sale/split-payment` | Process all split methods (includes inline Dejavoo) |
| `POST` | `/api/v1/nus-sale/resume-split-payment` | Continue partial split after failure/cancel |
| `POST` | `/api/v1/nus-sale/record-split-card-paid` | Record Stripe card success on split line |
| `POST` | `/api/v1/nus-sale/cancel-reader-payment` | Cancel in-flight Stripe intents |

### Split payment design principle

For split sales, only **two main APIs** drive the flow from the frontend:

1. `create-split-sale` — creates the sale record
2. `split-payment` — processes all methods in one call; **Dejavoo is handled inline** (no separate Dejavoo API call from the frontend for each split line)

Resume uses `resume-split-payment` when some lines are already paid.

---

## 5. Single Payment Flow

```
Staff selects CPP → enters amount → Process Payment
        ↓
Frontend: POST /dejavoo-payment (products + amount + dejavooPaymentType)
        ↓
Backend: DejavooService.createSale()
        ↓
Terminal: customer taps/inserts card
        ↓
Approved → SaleService creates completed sale (paymentGateway: "dejavoo")
Declined/Canceled → 402/409 with userMessage for staff
```

**Frontend behavior**

- Shows loading: “Complete the payment on the Dejavoo terminal…”
- On success: marks line `completed`, calls `onPaymentSuccess`
- On failure: shows Dejavoo `userMessage` when available

---

## 6. Split Payment Flow (with Dejavoo)

### 6.1 Sequence

```
1. Staff allocates amounts across methods (CPP + Cash + Zelle + Card, etc.)
2. POST create-split-sale  →  saleId, status: partial
3. POST split-payment      →  { saleId, paymentMethods[], readerId? }
```

Inside `SplitPayment`, for each payment method row:

| Method | Backend action |
|--------|----------------|
| `cash` | Recorded immediately as `paid` |
| `zelle` | Recorded immediately as `paid` |
| `dejavoo` / `cpp` | **Inline** `DejavooService.createSale()` → `recordSplitPaymentDejavooSuccess()` |
| `card` | Stripe PaymentIntent created → returned in `cardPayments[]` for frontend queue |
| `card_present` | Stripe reader or SDK flow |

### 6.2 Dejavoo split metadata (important fix)

Split Dejavoo calls use **minimal metadata** (same shape as single payment):

- `dbName`, `userId`, `customerId`, `source`, `dejavooPaymentType`, `savedPaymentMethod`

Fields like `saleId`, `splitIndex`, `isSplitPayment` were **removed** from Dejavoo CustomFields to avoid API rejection.

### 6.3 Amount validation

`validateSplitPaymentMethodsBody()` ensures:

- Payment methods sum to `netAmount` (± $0.01 tolerance)
- Max 10 split lines
- Card/CPP minimum $0.50 per line
- Valid method names and Dejavoo types

### 6.4 Recording CPP success

`SaleService.recordSplitPaymentDejavooSuccess()`:

- Sets line `status: "paid"`
- Stores `transactionId`, `authCode`, `paidAt`
- Updates `amountPaid`, `remainingAmount`, `paymentGateway: "dejavoo"`
- Finalizes sale when `remainingAmount` reaches zero

---

## 7. Resume Split Payment

When some methods are already paid (e.g. CPP + Zelle + Cash) but card manual fails or is canceled:

```
POST resume-split-payment
  saleId
  paymentMethods[]  ← only NEW / unpaid / adjusted lines
```

**Backend logic**

1. Loads sale; keeps only rows with `status: "paid"`
2. Computes `remaining = netAmount - paidTotal`
3. Validates new methods sum to `remaining`
4. Appends new rows after paid rows; re-indexes `splitIndex`
5. Processes Dejavoo/Stripe for new rows only — **never re-charges paid CPP**

**Frontend logic** (`handleResumeSplitPayments`)

- Reconciles UI “Paid” state against backend snapshot (`computeReconciledLines`)
- Builds **charge units**: full amount for new/failed/cancelled lines; **delta only** for topped-up paid lines (cash/Zelle/CPP)
- Updates status chips: Paid, Failed, Cancelled per line

---

## 8. Frontend UX — Payment Status & Adjustments

### 8.1 Per-method status chips

| Status | Chip | When |
|--------|------|------|
| `completed` | Green **Paid** / **Paid $X** | Backend settled |
| `completed` + increased amount | **Pay $Y more** (warning) | Top-up pending |
| `failed` | Red **Failed** | Decline/error |
| `cancelled` | Orange **Cancelled** | Staff canceled in-flight card |
| `processing` | Loading state | Terminal/Stripe in progress |

Failed or cancelled lines **remain editable** — staff can change amounts or switch methods.

### 8.2 CPP in split UI

- Payment method button: **Card Reader** area includes Dejavoo when configured
- CPP lines show payment type toggle: **Credit** / **Debit**
- Minimum $0.50 enforced (same as Stripe card)

### 8.3 Cancel flows (two levels)

| Action | Behavior |
|--------|----------|
| **Cancel current attempt** (`cancelCurrentPaymentAttempt`) | Cancels in-flight Stripe intent; marks card line **Cancelled**; returns to payment selection; **does not** cancel whole sale |
| **Cancel entire sale** (`requestPaymentAbort` / `executePaymentAbort`) | Only when closing modal **after** money collected; shows **Cancel Payment?** dialog with refund breakdown |

### 8.4 Cancel Payment dialog (`SplitPaymentCancelDialog`)

Shows amounts staff must return to customer **as cash**:

- Via Zelle (confirmed)
- Via CPP on terminal
- Via Cash
- Via Card (Stripe)

**Totals:**

- **Total to return** — all paid methods
- **If cash was NOT collected** — Zelle + CPP + Card only (when cash was in the mix but may not have been physically collected)

### 8.5 Zelle gate

If Zelle is in the split and not yet confirmed, staff must confirm the Zelle modal before processing continues (including CPP lines).

### 8.6 Cash payment (split context)

- **Received Amount** = total cash for the line (already collected + paying now)
- Auto-syncs when amount changes unless manually overridden
- Shortage blocks **Process Payment** with tooltip + warning notification
- Paid cash lines can be increased (pay more) or decreased (return) with dynamic label:
  - `($X collected · pay $Y more)`
  - `($X collected · return $Y)`

---

## 9. Error Scenarios & Fixes

| Issue | Cause | Fix |
|-------|-------|-----|
| `AxiosError 400` on split + Dejavoo | `ReferenceId` > 50 chars; invalid CustomFields | `buildSaleReferenceId()`, `sanitizeCustomFields()` |
| CPP shows Paid but backend says $X remaining | Frontend/backend paid state drift | `computeReconciledLines()` + resume reconciliation |
| `$92 must equal $98` on resume | Skipped CPP line marked paid in UI but not on server | Reconcile before charge; include unpaid CPP in resume payload |
| Cancel card showed “Cancel Split Payment?” | Wrong handler on card cancel | `cancelCurrentPaymentAttempt` vs `requestPaymentAbort` |
| Dejavoo generic error message | Raw axios error | `extractAxiosErrorMessage` + `getDejavooFailureDetails` |

---

## 10. Data Model (split payment line)

Each entry in `sale.paymentMethods[]`:

```javascript
{
  method: "CPP_Credit" | "CPP_Debit" | "CPP" | "cash" | "zelle" | "card" | "card_present",
  amount: Number,
  status: "paid" | "pending" | "failed",
  splitIndex: Number,
  referenceId: String,      // Dejavoo transaction / Stripe PI id
  transactionId: String,
  authCode: String,
  paidAt: Date,
  // cash only:
  cashReceived: Number,
  changeReturned: Number,
  dejavooPaymentType: "Credit" | "Debit" | "CPP"  // when applicable
}
```

---

## 11. Testing Checklist

### Single CPP

- [ ] Credit sale completes and sale is `paid`
- [ ] Debit sale completes
- [ ] Declined card shows friendly message
- [ ] Terminal cancel shows canceled message
- [ ] Timeout/host-no-response shows reconnect guidance

### Split with CPP

- [ ] CPP + Cash + Zelle — all settle in one `split-payment` call
- [ ] CPP runs on terminal before cash/zelle finalize in loop order
- [ ] Reference IDs stay ≤ 50 characters
- [ ] Paid chip appears on CPP line after approval

### Split failure & resume

- [ ] CPP paid → card manual canceled → line shows **Cancelled**
- [ ] Staff adjusts amounts and resumes — only remaining charged
- [ ] CPP not double-charged on resume
- [ ] Close modal after partial pay → cancel dialog shows CPP amount to return

### Cash + CPP combinations

- [ ] Cash received auto-fills; editable manually
- [ ] Shortage disables Process Payment
- [ ] Top-up on paid cash shows collected / pay more / return labels

---

## 12. Flow Diagram (Split with Dejavoo)

```mermaid
sequenceDiagram
    participant Staff
    participant POS as PaymentComponentNew
    participant API as Backend API
    participant DJ as Dejavoo Terminal
    participant Stripe

    Staff->>POS: Allocate CPP + Cash + Card
    Staff->>POS: Process Payment
    POS->>API: POST create-split-sale
    API-->>POS: saleId
    POS->>API: POST split-payment
    API->>DJ: createSale (CPP line)
    DJ-->>API: approved
    API->>API: recordSplitPaymentDejavooSuccess
    API->>API: Record cash/zelle paid
    API->>Stripe: Create PaymentIntent (card)
    API-->>POS: cardPayments[], updated sale
    POS->>POS: Card queue / reader UI
    alt Card success
        POS->>API: record-split-card-paid
        API-->>POS: sale paid
    else Card canceled
        POS->>POS: Mark Cancelled, stay on selection
        Staff->>POS: Adjust & resume
        POS->>API: POST resume-split-payment
        API->>Stripe: New intent for remaining only
    end
```

---

## 13. Summary

The POS Dejavoo integration provides:

1. **Single-shot CPP sales** via `/dejavoo-payment`
2. **Inline CPP inside split payment** — no extra frontend Dejavoo calls per split
3. **Robust SPIn API compliance** — short reference IDs, sanitized metadata, clear errors
4. **Resume without double-charge** — paid CPP/cash/zelle preserved; only remainder processed
5. **Staff-friendly UX** — per-line status, smart cancel vs abort, refund breakdown dialog, flexible adjustments after failure

For questions or changes, start with `dejavoo.service.js` (terminal API), `nursery.product.controller.js` (`SplitPayment` / `ResumeSplitPayment`), and `PaymentComponentNew.tsx` (UI orchestration).