# PHP Files & IP Whitelist — Complete Setup Guide

This guide takes you from an empty hosting account to a working, whitelisted casino API
integration. Everything can be generated automatically in **Client Panel → PHP Setup**.

---

## 0. What you need

| Item | Where to get it |
|---|---|
| API key (`token`) | Client Panel → Settings → API Credentials (auto-generated) |
| Secret key | Same page |
| Your website address | e.g. `https://your-casino.com` |
| Public IP of your **server** | `whoami.php` (below) or the PHP Setup page |
| Hosting with PHP 7.4+ and cURL | cPanel / VPS / any shared host |

---

## 1. One-click generator (fastest)

1. Open **Client Panel → PHP Setup**.
2. Type your website address and the folder you want (default `casino-api`).
3. Press **Detect browser / proxy IP** — this shows the IP our API sees from your browser.
   It is only the correct value if your site runs on the same network as the browser.
4. Press **Download all files** — `config.php`, `whoami.php`, `games.php`, `launch.php`,
   `callback.php` are generated with your API key, secret and callback URL already inside.
5. Upload them (section 3), then press **Detect server IP via whoami.php**.
6. Press **One-click whitelist + save callback**. Done — the IP and callback URL are stored.

---

## 2. Why "IP not whitelisted" happens

Our API only accepts calls coming from the IPs you listed. Common causes:

- The call is made **from the player's browser** instead of your server → the browser IP arrives.
- Your site sits behind **Cloudflare / a proxy / load balancer**, so outgoing traffic uses a
  different IP than the one shown in your hosting panel.
- Your host uses **multiple outgoing IPs** — whitelist all of them.
- You whitelisted an IPv4 but your server calls out over **IPv6** (or the reverse).

The error message always contains the exact IP we saw. Copy that value into the whitelist.

---

## 3. Upload the files

### cPanel File Manager
1. cPanel → **File Manager** → `public_html`.
2. **+ Folder** → `casino-api` → open it.
3. **Upload** → select the downloaded `.php` files → wait for 100%.
4. Set permissions to `644` for files, `755` for the folder.

### FileZilla (FTP/SFTP)
1. Host `ftp.your-casino.com`, your FTP user/password, port 21 (or SFTP 22).
2. Right panel: navigate to `public_html`, create `casino-api`.
3. Drag the files from the left panel into it.

### VPS / SSH
```bash
scp config.php whoami.php games.php launch.php callback.php \
  user@your-server:/var/www/html/casino-api/
```

---

## 4. Find the real server IP

Open `https://your-casino.com/casino-api/whoami.php` in a browser, or from your server:

```bash
curl -s https://casinoapi.shop/api/public/v1/whoami
```

Response:
```json
{ "code": 0, "data": { "ip": "203.0.113.24", "whitelist_value": "203.0.113.24" } }
```

Whitelist `whitelist_value` **exactly** (no port, no spaces, no CIDR).
**Delete `whoami.php` after setup.**

---

## 5. Whitelist and callback

Client Panel → **Settings**:
- **IP Whitelist** — one IP per line; add every outgoing IP of your host.
- **Callback URL** — `https://your-casino.com/casino-api/callback.php`
- Press **Save Settings**. Changes apply immediately.

Leaving the whitelist empty allows all IPs (fine for testing, not recommended live).

---

## 6. The files, explained

| File | Purpose |
|---|---|
| `config.php` | Your credentials + `casino_get()` / `casino_post()` helpers. Never expose publicly. |
| `whoami.php` | Temporary diagnostic — shows the IP to whitelist. Delete after use. |
| `games.php` | Fetches the game list (`game_uid` values you launch with). |
| `launch.php` | Creates a real-money game session and redirects the player. |
| `callback.php` | Receives `bet` / `win` / `rollback`, updates the player's balance, replies with the new balance. |

`callback.php` must:
- respond with JSON `{"code":0,"msg":"Success","data":{"balance":123.45}}`
- be idempotent — the same `transaction_id` must never be applied twice
- answer within 5 seconds over HTTPS

---

## 7. Test it

1. `https://your-casino.com/casino-api/games.php` → should list games.
2. Client Panel → **API Test** → **Run all tests** → all green.
3. `launch.php?game_uid=737&user_id=1001&balance=100` → the game opens.
4. Place one small bet and confirm your `casino_tx` table and the player balance update.

---

## 8. Troubleshooting

| Message | Cause | Fix |
|---|---|---|
| `IP not allowed: x.x.x.x` | Calling IP not whitelisted | Add the exact IP shown, save, retry |
| `Invalid token or inactive account` | Wrong/revoked API key | Copy the key again from Settings |
| `Provider not allowed for this account` | Provider disabled for you | Ask your account manager to enable it |
| `Balance is 0` | No GGR credit | Deposit USDT in Client Panel → Deposit |
| `game_uid required` | Missing/non-numeric game id | Use `game_uid` from `games.php` |
| Callback never arrives | HTTP, wrong path, firewall | Use HTTPS, allow our IPs, check `callback.php` returns JSON |

---

## 9. Security checklist

- Keep `config.php` outside version control; never print the secret to the browser.
- Delete `whoami.php` once the IP is whitelisted.
- Whitelist only the IPs you control and rotate keys if leaked (Settings → Regenerate Keys).
- Validate `user_id` server-side; never trust values coming from the player's browser.