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/mitfilterReference: 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 ergeben400 Bad Request.- Neues Feld
paymentType: Zeigt, wie eine Transaktion entstanden ist:one-time,subscription,reservation,authorizationoderindependent-credit. Rückerstattungen tragen den Typ der ursprünglichen Transaktion. Ältere Transaktionen ohne Typ liefernnull. - Neue Felder
payment.cardBinundpayment.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 neu401. Bis v1.18 war das403.403bedeutet 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 alsIN_PROGRESS. Bleibt eine Zahlung einige Sekunden aufPAYMENT_REQUESTED, brich sie ab und starte eine neue erst, wenn die ursprüngliche einen finalen Status ausserSUCCESShat. lastPaymentIdin 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:
slipist 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ätzlichreversalSlipmit 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 mitGET /ecr/{serialNumber}/payment/{paymentId}ab, bis er final ist.
v1.18
- Kassen-Zahlungen: Die Felder
transactionDescriptorundpaymentReferenceheissen neupurposeundreferenceId. POST /ecr/{serialNumber}/payment/{paymentId}/cancelkann je nach Terminal mit202antworten: Der Abbruch wurde angenommen, ist aber noch nicht abgeschlossen. Frage den Status danach ab.