> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smatvirtual.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Player Authentication

> How smatvirtual retrieves player info and wallet balances from your system.

Before a game session begins, the **smatvirtual** gateway needs to verify the player's identity and their current wallet balance. To do this, you must provide a **Details URL** in your Merchant Dashboard.

## The Handshake Flow

1. **Trigger:** A player clicks "Play" and your system calls our `/games/generate-launch-url` API.
2. **Verification:** Our system immediately makes a `GET` request to your **Details URL**.
3. **Response:** Your server returns the player's balance and currency.
4. **Launch:** If successful, the game loads with the player's actual funds.

## Your Endpoint Specification

Our server will call your provided endpoint with the following query parameters:

| Parameter   | Type     | Description                                            |
| :---------- | :------- | :----------------------------------------------------- |
| `playerId`  | `string` | The unique ID of the player in your system.            |
| `sessionId` | `string` | The session ID you provided during the launch request. |

### Expected Response

Your server must return a JSON object in the following format:

```json theme={null}
{
  "success": true,
  "data": {
    "playerId": "unique-player-id",
    "sessionId": "player-session-id",
    "balance": 5000.5,
    "currency": "USD"
  }
}
```

<Note>
  Currency Format: Use standard ISO shortcodes (e.g., NGN, USD, GHS). Ensure the
  balance is returned as a number or a high-precision string to avoid rounding
  errors.
</Note>

## Security & Reliability

* Whitelist our IP: Ensure your firewall allows incoming requests from the smatvirtual gateway.
* Latency: This request happens in real-time while the player is waiting for the game to load. Your endpoint should respond in under 200ms.