Zum Hauptinhalt springen

Cloud-Till-Schnittstelle

Cloud-Kassenschnittstelle: Bei der Nutzung der Cloud-Schnittstelle verwenden Sie eine öffentlich zugängliche API, um mit dem Endgerät zu kommunizieren. Der Vorteil besteht darin, dass Sie nicht wissen müssen, wo sich das Gerät befindet, und dass die Verbindung über jedes beliebige Netzwerk funktioniert. Allerdings kommt es im Vergleich zu anderen Integrationsmethoden zu einer höheren Verzögerung, da die Kommunikation über einen zentralen Server erfolgt. Die Einrichtung der Cloud-Till-Schnittstelle finden Sie weiter unten.

1. Voraussetzungen​

  • Ein registriertes Terminal (mit zugewiesener TID, PayDroid-Betriebssystem und Wallee-App auf dem neuesten Stand).
  • Die Cloud-Till-API-Funktion muss für Ihr Händlerkonto aktiviert sein.
  • API-Zugangsdaten (API-Schlüssel oder OAuth2-Client).
  • Ein Webhook-Endpunkt, der für den Empfang von Transaktionsaktualisierungen eingerichtet ist.

2. Eine Transaktion starten​

Um eine Zahlung an einem Terminal auszulösen, senden Sie eine POST-Anfrage an die Cloud Till-API:

POST https://api.wallee.com/cloud-till/v1/transactions/start
Content-Type: application/json
Authorization: Bearer <API_KEY>

Beispiel für den Request-Body:

{
  "terminalId": "32875518",
  "amount": {
    "currency": "CHF",
    "value": "23.60"
  },
  "transactionType": "PURCHASE",
  "reference": "ORDER-12345"
}

Die API gibt eine JSON-Antwort zurück, die die Transaktions-ID und den aktuellen Status enthält.

3. Statusaktualisierungen erhalten​

Sobald der Kunde eine Karte vorlegt, wickelt das Terminal die Zahlung ab.
Änderungen des Transaktionsstatus werden über Webhook zurückgemeldet:

{
  "transactionId": "abc123",
  "status": "APPROVED",
  "amount": {
    "currency": "CHF",
    "value": "23.60"
  },
  "reference": "ORDER-12345",
  "timestamp": "2025-09-25T10:24:00Z"
}

Mögliche Statuswerte:

  • APPROVED
  • DECLINED
  • CANCELLED
  • ERROR

4. Testen der Integration​

  1. Führen Sie eine kleine Testtransaktion durch (z. B. 1,00 CHF).
  2. Stellen Sie sicher, dass das Terminal den Kunden dazu auffordert.
  3. Schließen Sie die Zahlung per Chip oder kontaktlos ab.
  4. Vergewissern Sie sich, dass die Antwort des Webhooks empfangen wurde und Ihr System die Bestellung entsprechend aktualisiert.