Kassen-Connect API

Für die Entwicklung erstellt der Ladenbesitzer im Dashboard einen Sandbox-Token (mw_pos_test_…). Er nutzt exakt dieselben Endpunkte wie ein echter Token, aber:

• Er bucht ausschließlich auf die auto-provisionierte Test-Karte des Ladens — die Seriennummer liefert GET /v1/pos/ping im Feld testPass. Echte Kundenkarten sind für Sandbox-Token unsichtbar.
• Er funktioniert vor dem Go-Live: der Aktivierungs-Schalter des Händlers wird übersprungen.
• Test-Buchungen laufen in einem eigenen Idempotenz-Raum und tauchen weder in der Umsatz-Statistik des Händlers noch im Abgleich echter Tokens auf — eine in der Sandbox verbrauchte Bon-Nr. blockiert nie die spätere echte Buchung.
• GET /v1/pos/transactions und GET /v1/pos/summary zeigen einem Sandbox-Token nur seine Sandbox-Bewegungen.

Zum manuellen Ausprobieren gibt es im Händler-Dashboard außerdem einen Simulator gegen die echte API.

Optional pusht Midas Ereignisse an eine URL, die der Ladenbesitzer im Dashboard unter Kassen-Connect → Webhook hinterlegt — z. B. damit das Kassendisplay von sich aus „Belohnung verfügbar!“ anzeigen kann:

• reward_available — eine Karte hat soeben die Belohnungs-Schwelle erreicht (egal ob per Kasse, Staff-Scan oder Bonus).
• reward_redeemed — eine Belohnung wurde eingelöst.
• pass_created — ein Kunde hat eine neue Karte erstellt.

Jede Zustellung ist HMAC-signiert (Header X-Midas-Signature, Secret whsec_… aus dem Dashboard). Antworte mit einer 2xx; sonst folgt genau ein Wiederholversuch nach 30 Sekunden — dedupe deshalb über die Event-ID. Zustellungen sind best-effort und blockieren nie eine Buchung; die API bleibt die verbindliche Wahrheit.

{
  "id": "evt_5f0c2e7a-…",
  "type": "reward_available",
  "createdAt": "2026-07-06T14:07:31.000Z",
  "sandbox": false,
  "merchantId": "m_abc123",
  "data": {
    "passId": "p_xyz789",
    "serialNumber": "MW-1234-5678",
    "customerName": "Max M.",
    "balance": 10,
    "threshold": 10,
    "stampsToReward": 0,
    "rewardDescription": "1 Döner gratis"
  }
}

// Express-Beispiel: Signatur prüfen (Raw-Body nötig!)
const crypto = require('node:crypto');
const SECRET = process.env.MIDAS_WEBHOOK_SECRET; // whsec_… aus dem Dashboard

app.post('/midas-hook', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.header('X-Midas-Signature') ?? ''; // t=<unix>,v1=<hex>
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header);
  if (!m) return res.sendStatus(400);

  const [, t, v1] = m;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(400); // Replay

  const expected = crypto.createHmac('sha256', SECRET)
    .update(`${t}.${req.body}`).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'))) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body); // { id, type, sandbox, data: { serialNumber, … } }
  // event.id dedupen — bei Zustell-Retry kommt dieselbe id erneut.
  res.sendStatus(200);
});

Schicke bei jeder Buchung die Bon-Nr. als externalRef mit. Sie ist der Idempotenz-Schlüssel: derselbe externalRef bucht nie doppelt — Netzwerk-Timeouts kannst (und sollst) du also gefahrlos mit einem identischen Retry beantworten. Die Antwort auf einen Retry trägt "duplicate": true und das Ursprungs-Ergebnis.

externalRef ist außerdem der Anker fürs Storno: POST /v1/pos/void bucht die Stempel des referenzierten Bons zurück. Die Rückbuchung wird auf den aktuellen Saldo geklemmt — ein Kunde, der zwischen Kauf und Storno bereits eingelöst hat, rutscht nie ins Minus. Buchungen ohne externalRef sind nicht stornierbar.

Stempeln (transaction) und Einlösen (redeem) nutzen getrennte Idempotenz-Räume — dieselbe Bon-Nr. darf also in einem Bezahlvorgang sowohl eine Einlösung als auch neue Stempel tragen.