# Retail checkout (ECR)

Add BaxPay to an electronic cash register as one more tender key — the way you'd add a card scheme.

A retail sale maps directly onto the [Session API](https://developers.baxpay.com/terminal-api). The cashier rings up the basket,
presses the BaxPay tender key, and your ECR opens a session for the balance due.

## Sale flow

**1. Tender selected**

The cashier hits BaxPay for the amount due. The ECR calls `POST /integration/sessions` with the
receipt number as `saleReferenceId`.

**2. The terminal takes it**

The lane's terminal (the connection's `terminalId`) wakes with the amount displayed.

**3. The customer authenticates**

Card, contactless, QR or fingerprint, then the second factor (a PIN): the standard SCA gate.

**4. The ECR finalizes**

Poll until `final: true`. On `CAPTURED`, close the line and print the receipt with the BaxPay
`authCode` on it.

## Split tender

Open **one session per tender**. A €120 basket paid €100 on BaxPay and €20 in cash is a single €100
session; your ECR keeps the split. BaxPay never needs to know about the cash portion, only what it
is being asked to collect.

## Voids and refunds

- `POST /integration/sessions/{id}/void` — before capture

A session that isn't final yet (the shopper walked away, the cashier cancelled) is **voided** from
the ECR: see [void before capture](https://developers.baxpay.com/terminal-api#void-before-capture). Once a session is
`CAPTURED`, the money has moved and the ECR can't undo it: refunds are made from the Business
dashboard (**Transactions → Refund**), and they emit no session webhook.

## nexo / ISO 20022 estates

If your estate already speaks **nexo** (ISO 20022 retail messaging), point it at the BaxPay nexo
adapter with a `NEXO` connection. It maps nexo `Payment` and `Reversal`/`Abort` requests onto the
native session engine, so your ECR keeps the integration it already has.

- `POST /integration/nexo/saleToPOI`

```bash
curl -X POST https://sandbox-api.baxpay.com/v1/integration/nexo/saleToPOI \
  -H "Authorization: Bearer $BAXPAY_CONNECTION" \
  -H "Content-Type: application/json" \
  -d '{
    "SaleToPOIRequest": {
      "MessageHeader": { "MessageCategory": "Payment", "ServiceID": "4711" },
      "PaymentRequest": {
        "SaleData": { "SaleTransactionID": { "TransactionID": "receipt-77120" } },
        "PaymentTransaction": { "AmountsReq": { "Currency": "EUR", "RequestedAmount": 23.90 } }
      }
    }
  }'
```

```bash
curl -X POST https://sandbox-api.baxpay.com/v1/integration/nexo/saleToPOI \
  -H "Authorization: Bearer $BAXPAY_CONNECTION" \
  -H "Content-Type: application/json" \
  -d '{
    "SaleToPOIRequest": {
      "MessageHeader": { "MessageCategory": "Reversal", "ServiceID": "4712" },
      "ReversalRequest": { "SaleData": { "SaleTransactionID": { "TransactionID": "receipt-77120" } } }
    }
  }'
```

The nexo response comes back inside the usual `data` envelope. `RequestedAmount` is in major units
(`23.90`), as nexo defines it.

> **An adapter, not a certification**
> The nexo adapter is a faithful message mapping onto our engine. It is **not** a certified nexo
> terminal stack, and EMV L3 / scheme certification remain separate pieces of work. Talk to us
> before you go live on a certified estate: we would rather set expectations now than during your
> audit.