Skip to main content

Cloud Till Interface

Cloud Till Interface: By using the cloud interface you are using a public reachable API to interact with the terminal device. The benefit is you do not need to know where the device is located and it works from any network. However there is a higher delay compared to other integration methods because the communication happens via a central server. The Cloud Till Interface setup can be found below.

1. Prerequisites​

  • A registered terminal (TID assigned, PayDroid OS and Wallee App up to date).
  • Cloud Till API feature enabled for your merchant account.
  • API credentials (API key or OAuth2 client).
  • Webhook endpoint prepared to receive transaction updates.

2. Starting a Transaction​

To trigger a payment on a terminal, send a POST request to the Cloud Till API:

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

Example request body:

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

The API returns a JSON response containing the transaction ID and current status.

3. Receiving Status Updates​

Once the customer presents a card, the terminal processes the payment.
The transaction state changes are sent back via Webhook:

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

Possible status values:

  • APPROVED
  • DECLINED
  • CANCELLED
  • ERROR

4. Testing the Integration​

  1. Start a small test transaction (e.g. 1.00 CHF).
  2. Ensure the terminal prompts the customer.
  3. Complete the payment with chip/contactless.
  4. Verify the Webhook response is received and your system updates the order accordingly.