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/ with filterReference: 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 returns 400 Bad Request.
  • New field paymentType: shows how a transaction was created: one-time, subscription, reservation, authorization or independent-credit. Refunds carry the type of the original transaction. Older transactions without a type return null.
  • New fields payment.cardBin and payment.cardLast4: BIN and last four digits of the card, also for card terminal payments. null if the transaction was not paid by card.

Authentication

  • GET /SignatureCheck/: a wrong API key or signature now returns 401; up to v1.18 it was 403. From v1.19, 403 means 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 as IN_PROGRESS. If a payment stays PAYMENT_REQUESTED for a few seconds, cancel it and start a new one only once the original has a final status other than SUCCESS.
  • lastPaymentId in 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: slip is 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 new reversalSlip holds 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 poll GET /ecr/{serialNumber}/payment/{paymentId} until the status is final.

v1.18

  • Cash register payments: the fields transactionDescriptor and paymentReference are now called purpose and referenceId.
  • Depending on the terminal, POST /ecr/{serialNumber}/payment/{paymentId}/cancel can answer 202: the cancellation was accepted but is not complete yet. Poll the status afterwards.

Related