# Kiosk+ API

Power self-service kiosk experiences — card dispensing, reloading, and activity redemption. Build fully custom kiosk UIs on top of the Embed platform.

**Status:** Beta

---

## Overview

The Kiosk+ API enables integration partners to build fully custom self-service kiosk experiences on top of the Embed platform. Rather than using Embed's out-of-the-box kiosk software, the Kiosk+ API exposes the underlying card, sale, and product functionality directly so you can design and implement your own user interface and hardware integration.

### Typical Kiosk Capabilities

- Card dispensing — issue new game cards to guests
- Card reloading — add credit to an existing card at the kiosk
- Balance checking — display play, bonus, and ticket balances
- Product browsing — show available card products configured in GURU
- Activity / experience redemption — sell bookings and experiences at the kiosk
- Payment integration — connect your own payment terminal for cash or card

### Key Characteristics

| Feature | Details |
|---------|---------|
| Protocol | HTTPS only |
| Architecture | Stateless RESTful (on-premise) |
| Authentication | OAuth 2 Client Credentials Grant |
| Status | Beta — features may change between releases |
| Hardware | Compatible with card readers, RFID readers, and payment terminals via your own integration layer |

> The Kiosk+ API is currently in **beta**. Some endpoints and behaviours may change. Reach out to your Embed representative before beginning a Kiosk+ integration to confirm current capabilities and roadmap.

---

## Getting Started

To begin a Kiosk+ integration, your Embed representative will need to enable the Kiosk+ module on your Embed license and provide you with API credentials. The integration follows the same base URI and OAuth 2 pattern as the core Embed API.

### Pre-requisites

- Kiosk+ module enabled on your Embed license
- API credentials (Consumer Key and Consumer Secret) provided by Embed
- On-premise Embed server accessible from your kiosk hardware
- Physical or virtual card reader / RFID reader connected to your kiosk
- Payment terminal integration handled separately by your hardware team

### Typical Kiosk Session Flow

```
1. Authenticate         →  POST /auth/request_token
2. Idle / attract loop  →  Display branding, welcome screen
3. Guest taps card      →  GET /card/{card_id}           (check balance)
4. Guest selects product→  GET /mobile_templates          (list products)
5. Start sale           →  POST /sale/cancel              (clear any in-progress)
6. Add item             →  POST /sale/add_item
7. Guest pays           →  [Your payment terminal integration]
8. Tender sale          →  POST /current_sale/tender
9. Print/display receipt→  Show invoice number and totals
10. Return to idle
```

> The Kiosk+ API shares the same endpoints as the Embed API for card and sale operations. Consult the Embed API documentation and your Embed representative for the full endpoint list relevant to kiosk flows.

---

## Authentication

The Kiosk+ API uses the same **OAuth 2 Client Credentials Grant** as the Embed API. Every request must include a valid Bearer Token in the `Authorization` header.

### Getting a Bearer Token

```
POST https://{base-uri}/embed-api/auth/request_token HTTP/1.1
Authorization: Basic {base64(consumer_key:consumer_secret)}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
```

### Using the Bearer Token

```
Authorization: Bearer {your_access_token}
```

> Bearer Tokens expire after **1 hour**. Your kiosk application should request a new token proactively before each guest session or monitor for 401 responses and refresh on demand.

### Per-Terminal Thumbprint

Each physical kiosk must send a unique `API-Application-Thumbprint` header so that Embed can report activity per terminal:

```
API-Application-Thumbprint: {unique-guid-per-kiosk}
API-Device-Description: Lobby Kiosk 1
```