Kassenintegration

Mit der Kassenintegration schickt dein Kassensystem den Betrag ans Terminal. Die Kundschaft hält Karte oder Telefon hin, deine Kasse bekommt das Ergebnis. Kein Abtippen, keine Differenzen.

Zahlung am Terminal starten

curl https://api.freika.com/v1/terminals/trm_theke_links/payments \
  -H "Authorization: Bearer $FREIKA_API_KEY" \
  -H "Idempotency-Key: bon-20260910-0042" \
  -d amount=2450 -d currency=CHF \
  -d reference="Bon 42" \
  -d tip_prompt=true

{
  "id": "pay_01J9XT8",
  "status": "pending",
  "terminal_id": "trm_theke_links",
  "amount": 2450,
  "expires_at": "2026-09-10T12:02:00Z"
}

Das Terminal zeigt den Betrag an. Ist es gerade beschäftigt, bekommst du 409 terminal_busy; ist es nicht erreichbar, 409 terminal_offline.

Ergebnis erhalten

Drei Wege, je nach Kasse:

Long-Polling (einfach)

curl "https://api.freika.com/v1/payments/pay_01J9XT8?wait=30" \
  -H "Authorization: Bearer $FREIKA_API_KEY"

Die Anfrage bleibt bis zu 30 Sekunden offen und antwortet, sobald sich der Status ändert.

WebSocket (Echtzeit)

const ws = new WebSocket(
  "wss://api.freika.com/v1/terminals/trm_theke_links/events?token=fk_live_...",
);
ws.onmessage = (m) => {
  const event = JSON.parse(m.data);
  // event.type: payment.pending | payment.succeeded | payment.failed | payment.canceled | terminal.message
};

Über terminal.message bekommst du Zwischenstände wie «Karte einstecken» oder «PIN-Eingabe», die du auf dem Kassendisplay anzeigen kannst.

Webhook

Für Kassen mit Server-Anbindung: das Ereignis payment.succeeded kommt an deinen Endpunkt, siehe Webhooks.

Zahlung abbrechen

curl -X POST https://api.freika.com/v1/terminals/trm_theke_links/cancel \
  -H "Authorization: Bearer $FREIKA_API_KEY"

POST /v1/terminals/{id}/close_batch löst den Tagesabschluss aus und liefert die Summen nach Zahlungsmethode. Belege holst du mit GET /v1/payments/{id}/receipt als Text, HTML oder ESC/POS für deinen Bondrucker.

Für Kassenhersteller

Du integrierst Freika in dein Produkt? Im Partnerprogramm legst du Organisationen für deine Kundschaft per API an und erhältst 10 % der prozentualen Gebühren, laufend.