# Operator API (Quick Guide)

Base URL: `https://sandbox.playegamenow.com`

Auth: Processor Bearer token (Authorization header).
All responses are JSON.

---

## 1) Create customer + add money
**POST** `/operator/g/create/`

Creates a new customer and immediately adds money to their balance.

### Request Body
```json
{
  "operator_id": "0f6d7d8a-7e9a-4d95-9f73-5f7d9b8327a1",
  "payment_provider_id": "ProviderBusinessName",
  "operator_wallet_id": "1231",
  "player_wallet_id":  "123",
  "amount": "25.00",
  "operator_game_id": 42,
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "date_of_birth": "1975-01-18"
  }
}
```

### Response (201)
```json
{
  "session_id": "uuid",
  "amount": "25.00",
  "operator_game_id": 42,
  "status": "pending"
}
```

---

## 2) Purchase (add money to existing customer)
**POST** `/operator/g/purchase/`

Adds money to an existing customer.

### Request Body
```json
{
  "operator_id": "0f6d7d8a-7e9a-4d95-9f73-5f7d9b8327a1",
  "payment_provider_id": "ProviderBusinessName",
  "operator_wallet_id": "1231",
  "player_wallet_id":  "123",
  "amount": "10.00",
  "operator_game_id": 42,
  "player_game_user_id": 123
}
```

### Response (201)
```json
{
  "session_id": "uuid",
  "amount": "10.00",
  "operator_game_id": 42,
  "status": "pending"
}
```

---

## 3) Redeem (withdraw money from existing customer)
**POST** `/operator/g/redeem/`

Withdraws money from an existing customer.

### Request Body
```json
{
  "operator_id": "0f6d7d8a-7e9a-4d95-9f73-5f7d9b8327a1",
  "payment_provider_id": "ProviderBusinessName",
  "operator_wallet_id": "1231",
  "player_wallet_id":  "123",
  "amount": "5.00",
  "operator_game_id": 42,
  "player_game_user_id": 123
}
```

### Response (201)
```json
{
  "session_id": "uuid",
  "amount": "5.00",
  "operator_game_id": 42,
  "status": "pending"
}
```

---

## 4) Create operator
**POST** `/operator/create/`

Creates a new operator account.

Auth: Processor Bearer token (Authorization header).

### Request Body
```json
{
  "operator_id": "0f6d7d8a-7e9a-4d95-9f73-5f7d9b8327a1"
  "username": "operator_demo_02",
  "email": "operator_demo_02@example.com",
  "business_name": "Fortune Hall",
  "contact_first_name": "John",
  "contact_last_name": "Doe",
  "address": "221B Baker Street, London",
  "contact_phone": "+380501112233",
  "operator_site_url": "https://operator.example.com"
}
```
"operator_id" - optional, The "operator_id" must be included if it was provided by us in the request as a referral ID.
### Response (201)
```json
{
  "operator_id": "0f6d7d8a-7e9a-4d95-9f73-5f7d9b8327a1"
  "username": "operator_demo_02"
}
```

### Notes
- Password is generated automatically.
- System sends password reset link to `email`.
- Returned `operator_id` is operator eWallet user id (UUID). Use it in `/operator/g/*` endpoints.

### Common Errors
- `400 Bad Request` — validation errors (for example, duplicate `username` or `email`).
- `401 Unauthorized` — missing or invalid processor token.

---

## Common Errors
- `400 Bad Request` — missing/invalid fields, amount < 0.01, invalid types.
- `401/403` — missing/invalid processor token, or service disabled.
- `404 Not Found` — operator or operator_game not found / not eligible.
- `500` — error (message: "Failed to process transaction").

---
### Fields
- `payment_provider_id` (string, required) payment provider business name
- `operator_id` (UUID string, required) operator id received when create operator
- `operator_wallet_id` (string, required) payment provider wallet id
- `player_wallet_id` (string, required) payment provider wallet id
- `amount` (decimal string, required, min 0.01)
- `operator_game_id` (integer, required) - each game will have it's unique, you will get it from operator admin
- `player_game_user_id` (integer, required)
  This is `customerId` that you will receive from webhook after call /operator/g/create/ endpoint
- `customer` (object, required)
  - `first_name` (string)
  - `last_name` (string)
  - `email` (string)
  - `date_of_birth` (string, ISO-8601, recommended `YYYY-MM-DD`)

## Notes on Async Processing
These endpoints only initiate a transaction.
The returned `session_id` is the transaction UUID for later status checks (handled separately).

## Webhook (Session Result)
after you call create, redeem or purchase you will get session_id, after this you need to wait webhook in which 
we will send you information about status of this session(success, failed) and additional information, such as created customer id

Webhook details:
we will send a POST request to the URL that operator sets in admin panel.
request body is JSON.
structure TBD (to be discussed).
authorization via processor Bearer token (Authorization header).

---

## 5) Get active operator games
**GET** `/operator/{operator_id}/games/`

Returns operator games by operator id.

Auth: Processor Bearer token (Authorization header).

### URL Param
- `operator_id` (UUID, eWallet user id)

### Response (200) - The Response below shows the case where the operator has two active games. 
```json
[
  {
    "operator_game_id": 42,
    "display_name": "Fortune 2 go  Operator Tom",
    "publish_site": true,
    "game_pos_url": "https://example.com/game-pos",
    "game_name": "Fortune 2 go"
  }
  
  {
    "operator_game_id": 43,
    "display_name": "Ultra Panda Operator Tom",
    "publish_site": true,
    "game_pos_url": "https://example.com/game-pos",
    "game_name": "Ultra Panda"
  }
]
```