Registrieren

Kassen-Integration

Kartenlesegeräte über die zahls.ch Cash Register API integrieren.

Da zahls.ch seine Unterstützung für Point-of-Sale (POS)-Lösungen ausbaut, wächst auch die Vielfalt der Hardware-Terminals, die wir anbinden. Die Entwicklung für unterschiedliche Hardware-Anbieter kann anspruchsvoll sein – jedes Terminalmodell bringt oft eigene Integrationslogik, Abläufe und Besonderheiten mit.

Um die Entwicklung zu vereinfachen und die Hardware-Anbindung zu standardisieren, haben wir die zahls.ch Cash Register API auf Basis unserer Merchant API entwickelt.

Unsere Philosophie: Standardisierungsschicht

Die Cash Register API bietet eine einheitliche Schnittstelle, über die deine Software mit jedem von zahls.ch unterstützten Hardware-Terminal kommunizieren kann.

Statt dass deine Anwendung für jedes Terminal eine andere «Sprache» lernen muss, reicht eine: die zahls.ch Cash Register API.

Du implementierst deine Integration einmal gegen unsere API. Wir übernehmen die Übersetzung deiner Anfrage auf das konkrete Terminal.

So bleibt deine bestehende Integration auch dann stabil, wenn wir neue Hardware-Anbieter ins Ökosystem aufnehmen – mit minimalen oder keinen Anpassungen bei dir.

Aktuelle Unterstützung

Derzeit unterstützt die Cash Register API NexGo-Geräte vollständig. Weitere Anbieter werden über dieselbe standardisierte API verfügbar gemacht.

So funktioniert es: Kurzüberblick

Die API gliedert sich in drei Hauptgruppen von Endpunkten – über den gesamten Lebenszyklus eines Terminals.

1. 🤝 PAIRING: Der «Handshake»

Bevor du eine Zahlung an ein Terminal senden kannst, muss dein System es kennen. Pairing verknüpft ein physisches Terminal (über die Seriennummer) mit der API.

Für eine Pairing-Anfrage über die API musst du am Terminal physisch ein One-Time Password (OTP) erzeugen. So stellen wir sicher, dass du physischen Zugriff auf das Gerät hast.

Unterstützte Geräte: NexGo N5, N6, N86

  1. Menü öffnen: Auf dem Zahlungsbildschirm oben links auf das Menü-Symbol (≡) tippen.

  2. Pairing wählen: In der Liste «Connect to cash register» auswählen.

  3. Code ablesen: Es erscheint ein alphanumerischer Code mit 6 Zeichen (z. B. QP3U58).

    Hinweis: Verlässt du den Bildschirm vor Abschluss des Pairings, ändert sich der Code.

Mit diesem Code schliesst du Pairing in deiner Software ab.

  • pair GET: Pairing-Status eines Terminals (z. B. gepairt und bereit?).
  • pair POST: Neues Terminal registrieren – Seriennummer übergeben, API verknüpft es mit deinem Konto.
  • pair DELETE: Terminal vom API-Pairing lösen (z. B. bei Ausserbetriebnahme).

Pairing-Flow

Unpair-Flow

2. 💳 PAYMENT: Der Kern

Hier verarbeitest du Transaktionen – von Zahlungsstart über Status bis Storno.

  • payment GET: Status und Details einer Zahlung anhand der ID (z. B. erfolgreich? abgelehnt?).
  • payment POST: Zahlung auslösen (z. B. «25.50 belasten») an ein gepairtes Terminal.
  • payment/cancel POST: Laufende Zahlung am Terminal abbrechen.
  • payment/void POST: Bereits abgeschlossene Zahlung stornieren (typisch am selben Tag vor Batch-Settlement).

Zahlungs-Flow (gepairt)

3. ⚙️ ADDITIONAL: Zusatzfunktionen

Endpunkte mit Kontext zu den Fähigkeiten eines Terminals.

  • paymentMethods POST: Welche Zahlungsmittel das Terminal akzeptiert – hilfreich für die Kassenkonfiguration.

Nächste Schritte

Dieser Überblick skizziert die Cash Register API. Für Felder, Request-/Response-Beispiele und Fehlercodes siehe die technische API-Referenz.