# Casino Staging Integration Start Here

This is the first document for the `bspin-staging` casino integration. Use this staging environment for non-production casino wallet integration. The local sandbox guide is optional demo testing only and is not the casino staging path.

## Staging Values

- Base URL: `https://staging-games.rougereels.com`
- Operator id: `bspin-staging`
- Currency: `USD`
- Callback base URL: `https://podrum.supersport.club:49165/CasinoRougeReelsApi`
- Required Vercel secret: `OPERATOR_SECRET_BSPIN_STAGING`
- Enabled games: Dice, Limbo, Plinko, Keno, Mines, Blackjack

Staging is not approved for real-money traffic. The casino remains responsible for wallet funds, KYC, AML, payments, responsible gaming, player restrictions, and jurisdiction compliance.

## Required Casino Wallet Endpoints

Rouge Reels appends these paths to the callback base URL:

- `POST /wallet/validate-session`
- `POST /wallet/balance`
- `POST /wallet/debit`
- `POST /wallet/credit`
- `POST /wallet/rollback`

Money-changing callbacks must be idempotent. Repeating the same idempotency key must return the original response and must never double-charge or double-pay.

If credit fails or times out, Rouge Reels keeps retrying `/wallet/credit` with the same idempotency key until the casino returns a positive response. If debit is ambiguous or a post-debit provider error requires reversal, Rouge Reels retries `/wallet/rollback` with the same rollback idempotency key until success. Retries run when the player starts a new session and through the protected 30-minute Vercel cron route.

## First Steps

1. Confirm the staging provider is online:

```text
GET https://staging-games.rougereels.com/health
```

2. Confirm the Bspin staging operator is ready:

```text
GET https://staging-games.rougereels.com/ready?operatorId=bspin-staging
```

3. Confirm the casino wallet endpoints are reachable from staging and verify signed requests for validation, balance, debit, credit, and rollback.

4. Generate a casino launch token for a staging player and one game. `/sandbox/launch` is local/demo only; do not use it for the `bspin-staging` path.

5. Open the game iframe with the casino launch token:

```text
https://staging-games.rougereels.com/game.html?operatorId=bspin-staging&game=dice&token=<casino-launch-token>&embed=1
```

Full-height iframe example:

```html
<iframe
  title="Rouge Reels Dice"
  src="https://staging-games.rougereels.com/game.html?operatorId=bspin-staging&game=dice&token=<casino-launch-token>&embed=1&fill=1"
  style="width: 100%; height: 100dvh; border: 0;"
  allow="fullscreen"
></iframe>
```

6. Verify the casino-provided balance appears inside the embedded game.

7. Place one Dice bet and confirm the casino sees the debit, the credit close callback, rollback behavior for failed settlement, and idempotency evidence. Winning credits carry the payout amount; losing credits carry `amount: 0`.

8. Repeat the same idempotency key with the same request and confirm the original response is returned without a second wallet movement.

## Evidence To Send Back

- Screenshot or JSON output for `/health`.
- Screenshot or JSON output for `/ready?operatorId=bspin-staging`.
- One launch URL opened successfully with `operatorId=bspin-staging`.
- One settled Dice `roundId`.
- Casino logs for validate-session, balance, debit, and credit close callbacks. Debit and credit include the original launch token so the casino can connect them to the launched session.
- One repeated idempotency request showing the original transaction result.
- One rollback or failed-settlement test when ready.
- One bet report or `/api/bets/{roundId}` response showing the dispute trail.
- One fairness verifier check after the server seed is revealed.

## Rollback Test

After creating a staging session, submit a Dice bet with an invalid target window to force the provider rollback path:

```json
{
  "sessionId": "<session-id>",
  "gameType": "dice",
  "amount": 9,
  "idempotencyKey": "bspin-rollback-test-001",
  "clientSeed": "bspin-rollback-test",
  "params": {
    "target": 99,
    "direction": "over"
  }
}
```

Expected result: the casino receives `/wallet/debit`, Rouge Reels rejects settlement, then the casino receives `/wallet/rollback` for the same round and amount. Rollback keeps its own `X-Idempotency-Key` header and includes `debitIdempotencyKey` in the JSON body with the original debit request key, so the casino can locate the debit transaction to reverse. The API response includes `roundId` and `roundStatus`; fetch `/api/bets/{roundId}` to inspect the stored debit and rollback audit.

## Partner Links

- Staging handoff package: `https://staging-games.rougereels.com/docs/casino-demo-package.md`
- API guide: `https://staging-games.rougereels.com/docs/API.md`
- OpenAPI spec: `https://staging-games.rougereels.com/docs/openapi.json`
- Postman collection: `https://staging-games.rougereels.com/docs/postman_collection.json`
- Integration checklist: `https://staging-games.rougereels.com/docs/integration-checklist.md`
- Sample callback backend: `https://staging-games.rougereels.com/docs/sample-casino-backend.js`
- Signing example: `https://staging-games.rougereels.com/docs/signing-example.js`

## Local Sandbox Note

`docs/sandbox-integration-guide.md` is for optional local/demo testing with the built-in `demo` operator and `sandbox://demo-casino`. It is useful for learning the flow, but the casino staging integration should use `bspin-staging` and the HTTPS callback endpoints listed above.