API changelog
What changed in each version of the zahls.ch API.
Last updated:
The current version of the zahls.ch API is v1.19 (https://api.zahls.ch/v1.19/). The version is part of the path: existing integrations on an older version keep behaving as before. You get new fields and endpoints once you switch to the new version.
All details on fields and responses are in the API reference.
v1.19
Transactions
GET /Transaction/withfilterReference: returns only transactions whose reference (referenceId) or purpose (purpose) matches this value exactly. Matching is not case-sensitive; partial matches are not returned. An empty value or more than 255 characters returns400 Bad Request.- New field
paymentType: shows how a transaction was created:one-time,subscription,reservation,authorizationorindependent-credit. Refunds carry the type of the original transaction. Older transactions without a type returnnull. - New fields
payment.cardBinandpayment.cardLast4: BIN and last four digits of the card, also for card terminal payments.nullif the transaction was not paid by card.
Authentication
GET /SignatureCheck/: a wrong API key or signature now returns401; up to v1.18 it was403. From v1.19,403means the API is not included in your licence.
Cash register / ECR
- New endpoint
POST /ecr/{serialNumber}/payment/credit: credits a card without an original payment – the cash register equivalent of a payout. See Cash Register Integration. - New status
PAYMENT_REQUESTED: the payment was sent to the terminal but not yet accepted. Up to v1.18, NexGo terminals reported this asIN_PROGRESS. If a payment staysPAYMENT_REQUESTEDfor a few seconds, cancel it and start a new one only once the original has a final status other thanSUCCESS. lastPaymentIdin error responses: errors (400,404,501) from the ECR endpoints include the ID of the last payment you started on this terminal, so the cash register can query or cancel it after an error.- Uniform receipts:
slipis now an object with structured data (information, e.g.transactionId,maskedPan,authorizationCode) and print-ready texts (print.customer,print.merchant: 40 columns, monospace, in the merchant's language). Up to v1.18 the format depended on the terminal family. The newreversalSlipholds the receipt of a void or refund. POST /ecr/{serialNumber}/payment: the response reflects the state after a hand-off window of at most 7 seconds. Then pollGET /ecr/{serialNumber}/payment/{paymentId}until the status is final.
v1.18
- Cash register payments: the fields
transactionDescriptorandpaymentReferenceare now calledpurposeandreferenceId. - Depending on the terminal,
POST /ecr/{serialNumber}/payment/{paymentId}/cancelcan answer202: the cancellation was accepted but is not complete yet. Poll the status afterwards.