API-Changelog

Was sich in den Versionen der zahls.ch API geändert hat.

Zuletzt aktualisiert:

Die aktuelle Version der zahls.ch API ist v1.19 (https://api.zahls.ch/v1.19/). Die Version steht im Pfad: Bestehende Integrationen auf einer älteren Version verhalten sich weiter wie bisher. Neue Felder und Endpunkte bekommst du erst, wenn du auf die neue Version wechselst.

Alle Details zu Feldern und Antworten findest du in der API-Referenz.

v1.19

Transaktionen

  • GET /Transaction/ mit filterReference: Liefert nur Transaktionen, deren Referenz (referenceId) oder Zweck (purpose) genau diesem Wert entspricht. Gross- und Kleinschreibung spielen keine Rolle, Teiltreffer werden nicht zurückgegeben. Ein leerer Wert oder mehr als 255 Zeichen ergeben 400 Bad Request.
  • Neues Feld paymentType: Zeigt, wie eine Transaktion entstanden ist: one-time, subscription, reservation, authorization oder independent-credit. Rückerstattungen tragen den Typ der ursprünglichen Transaktion. Ältere Transaktionen ohne Typ liefern null.
  • Neue Felder payment.cardBin und payment.cardLast4: BIN und die letzten vier Ziffern der Karte, auch bei Zahlungen am Kartenterminal. null, wenn nicht mit Karte bezahlt wurde.

Authentifizierung

  • GET /SignatureCheck/: Ein falscher API-Schlüssel oder eine falsche Signatur liefert neu 401. Bis v1.18 war das 403. 403 bedeutet ab v1.19, dass die API nicht in deiner Lizenz enthalten ist.

Kasse / ECR

  • Neuer Endpunkt POST /ecr/{serialNumber}/payment/credit: Gutschrift auf eine Karte ohne Ursprungszahlung, also das Gegenstück zu einer Auszahlung an der Kasse. Mehr dazu unter Kassen-Integration.
  • Neuer Status PAYMENT_REQUESTED: Die Zahlung wurde ans Terminal geschickt, aber noch nicht angenommen. NexGo-Terminals meldeten diesen Zustand bis v1.18 als IN_PROGRESS. Bleibt eine Zahlung einige Sekunden auf PAYMENT_REQUESTED, brich sie ab und starte eine neue erst, wenn die ursprüngliche einen finalen Status ausser SUCCESS hat.
  • lastPaymentId in Fehlerantworten: Fehler (400, 404, 501) der ECR-Endpunkte enthalten die ID der letzten Zahlung, die du auf diesem Terminal gestartet hast. So kann die Kasse sie nach einem Fehler abfragen oder abbrechen.
  • Belege einheitlich: slip ist jetzt ein Objekt mit strukturierten Daten (information, z. B. transactionId, maskedPan, authorizationCode) und druckfertigen Texten (print.customer, print.merchant: 40 Spalten, Monospace, in der Sprache des Händlers). Bis v1.18 hing das Format von der Terminal-Familie ab. Neu gibt es zusätzlich reversalSlip mit dem Beleg einer Stornierung oder Rückerstattung.
  • POST /ecr/{serialNumber}/payment: Die Antwort zeigt den Stand nach höchstens 7 Sekunden Übergabezeit. Frage danach den Status mit GET /ecr/{serialNumber}/payment/{paymentId} ab, bis er final ist.

v1.18

  • Kassen-Zahlungen: Die Felder transactionDescriptor und paymentReference heissen neu purpose und referenceId.
  • POST /ecr/{serialNumber}/payment/{paymentId}/cancel kann je nach Terminal mit 202 antworten: Der Abbruch wurde angenommen, ist aber noch nicht abgeschlossen. Frage den Status danach ab.

Verwandte Themen