> For the complete documentation index, see [llms.txt](https://wallee.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wallee.gitbook.io/documentation/payments/in-store-payments/integrations/interfaces/cloud-till-interface.md).

# 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 {inject-brand-name} 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:

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

Example request body:

```json
{
  "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**:

```json
{
  "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.