> For the complete documentation index, see [llms.txt](https://docs.thndr.io/integration/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thndr.io/integration/deprecated/deposits-api.md).

# Deposits API

{% hint style="info" %}
Deposits API is deprecated, we recommend to use the new [Transactions](/integration/server-webhooks/transactions.md)API for the new integrations
{% endhint %}

## Server to Server Callbacks

To receive messages on when to deduct and credit user balances based on the outcomes of matches, you should implement the following endpoints.

### Pay Entry Fee

**Method**: `POST /thndr/pay`\
**Description**: When you receive this post request from us:

* Deduct the bet amount from the user's balance.
* Associate the `depositId` with the `amount` in your database to allow for potential refunds.
* Use `depositId` as the idempotency key to ensure the same payment is not processed twice.

\
**Body**:

```json
{
  "userId": "123",
  "depositId": "abc",
  "currency": "USD",
  "amount": 50
}
```

<figure><img src="/files/bCNuCh3dsc2IVjtTOQUa" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
For tournament entries, the `tournamentId` field is included to identify the tournament the round belongs to.

```
{
  "userId": "123",
  "depositId": "abc",
  "currency": "USD",
  "amount": 50,
  "tournamentId": "tournament-123"
}
```

* `tournamentId` *-* Identifier of the tournament this round belongs to. Present only when the entry was made via a tournament flow; absent for regular duels. Format: UUID v4.
  {% endhint %}

#### Payment Errors

If you need to notify your client about any payment errors, such as "Insufficient Balance", you can return errors in the response with a status code 4XX. These errors will be sent to the client sdk via the [handleError](/integration/launch-game/custom/configure-sdk.md#callbacks) callback for your front end to handle.

**Note**: You must pass `"isClientSafe": true` in the response for it to be passed to the client.

Example 4XX response:

```
{
    "errors": [
        {
            "code": "INSUFFICIENT_BALANCE",
            "isClientSafe": true
        }
    ]
}
```

### Handle Match Results

**Method**: `POST /thndr/results`\
**Description**: Upon receiving this POST request from us, take the appropriate action based on the match outcome:

* **WIN** or **DRAW**: Credit the user's balance by `amount`.
* **LOSE**: No action required.
* **REFUND**: Retrieve the `amount` from your database and refund the user.

**Note**: Use `depositId` as the idempotency key to ensure the same result is not processed twice.

**Important**: If a system crash occurs before receiving a response from the `/thndr/pay` webhook, you may receive refund requests for deposit IDs that were never persisted in your database (i.e., the user was not credited). These requests must be ignored, and a 200 status code must be returned.

**Body (WIN or DRAW)**:

```json
{
  "result": "WIN" | "DRAW",
  "userId": "123",
  "depositId": "abc",
  "roomId": "xyz",
  "gameId": "solitaire" | "blocks" | "blackjack",
  "currency": "USD",
  "amount": 100,
  "tournamentId": "tournament-123", // optional; omitted when not applicable
}
```

**Body (LOSE)**:

```json
{
  "result": "LOSE",
  "userId": "123",
  "depositId": "abc",
  "gameId": "solitaire" | "blocks" | "blackjack",
  "roomId": "xyz",
  "tournamentId": "tournament-123", // optional; omitted when not applicable
}
```

**Body (REFUND)**:

```json
{
  "result": "REFUND",
  "userId": "123",
  "depositId": "abc",
  "gameId": "solitaire" | "blocks" | "blackjack" | null,
  "roomId": "xyz" | null,
  "currency": "USD",
  "amount": 100
}
```

<figure><img src="/files/8NzHdNhcCqJtm8erVyQi" alt=""><figcaption></figcaption></figure>

## Request Signing

To ensure the integrity and authenticity of API requests, our system signs each request payload using an HMAC (Hash-based Message Authentication Code) with the **SHA-256** algorithm. Integrators must verify the signature to authenticate requests and prevent tampering.

### Verification Process

To verify the request's authenticity, the integrator should:

1. **Recompute the signature** using the shared secret and the received payload.
2. **Compare the computed signature** with the `x-server-authorization` header value.
3. **Reject the request** if the signatures do not match.

#### Example Verification in Node.js:

```typescript
const crypto = require("crypto");

function verifySignature(receivedSignature, requestPayload, SERVER_SECRET) {
    const computedSignature = crypto
        .createHmac("sha256", SERVER_SECRET)
        .update(requestPayload)
        .digest("hex");

    return computedSignature === receivedSignature;
}
```

The `SERVER_SECRET` is a pre-shared secret key known only to THNDR server and the integrator.

### Example Signed Payload

```
Server secret: DUMMY_SECRET
Payload: {"userId":"alice","depositId":"depositA","amount":100}
x-server-authorization: 1bb9edf6131931e29957844f176dc9eaf090e9ccee5ece6ab5fb4c4fa7389513
```