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

# Wallet

> Wallet, accounts and deposits

## What is Toffee Wallet?

**Toffee Wallet** is a service that includes a mobile app providing access to the user's account, allowing them to view and top up their balance, check their transaction history, and add wallet passes, etc. It also serves as a payment provider that can be enabled for a game or group of games and provides:

* Creation of a **Toffee Wallet** account for the user (with the user's consent)
* Cashback accumulation
* Ability to pay with **Toffee Wallet** on the checkout page

<Info>
  Contact the Toffee Team to configure and enable **Toffee Wallet** functionality for your game or group of games.

  Configurable options:

  * Account asset (a card-like image that will be displayed in the **Toffee Wallet** app)
  * Wallet Pass assets
  * Cashback percentage
  * Top-up amounts and their associated rewards
</Info>

## App links

#### iOS

[https://apps.apple.com/us/app/toffee-wallet/id6751423503](https://apps.apple.com/us/app/toffee-wallet/id6751423503)

#### Android

[https://play.google.com/store/apps/details?id=com.toffee.wallet](https://play.google.com/store/apps/details?id=com.toffee.wallet)

## Configure Toffee Wallet per session

To enable or disable **Toffee Wallet** per session, you can use the `wallet_enabled` parameter in the [Create Session](/api-reference/sessions/create) request.

<Warning>
  After **Toffee Wallet** is configured and enabled for your game or group of games, it is also **enabled** by default for every session if the `wallet_enabled` parameter is skipped.
</Warning>

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const { session } = await toffee.sessions.create({
      // ...other params
      walletEnabled: true,
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = await toffee.sessions.create(CreateSessionRequest(
        # ...other params
        wallet_enabled=True,
    ))
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    resp, err := toffee.Sessions.Create(ctx, &sdk.CreateSessionRequest{
      // ...other params
      WalletEnabled: true,
    })
    ```
  </Tab>

  <Tab title="API">
    ```http theme={null}
    POST /v1/sessions
    Authorization: Bearer <your_access_token>
    Content-Type: application/json

    {
      ...other_params,
      "wallet_enabled": true
    }
    ```
  </Tab>
</Tabs>

## Accounts

Each user who activates Toffee Wallet gets an account linked to their game user(s). An account holds the user's balance, split into `real` (deposited funds) and `bonus` (cashback rewards).

### Get Account

[Retrieve account details](/api-reference/accounts/get) by ID:

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const { account } = await toffee.accounts.get({ id: "acc_xyz123" });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = await toffee.accounts.get(GetAccountRequest(id="acc_xyz123"))
    account = resp.account
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    resp, err := toffee.Accounts.Get(ctx, &sdk.GetAccountRequest{Id: "acc_xyz123"})
    account := resp.GetAccount()
    ```
  </Tab>

  <Tab title="API">
    ```http theme={null}
    GET /v1/accounts/acc_xyz123
    Authorization: Bearer <your_access_token>
    ```
  </Tab>
</Tabs>

**Response:**

```json theme={null}
{
  "id": "acc_xyz123",
  "users": [
    { "game_id": "space_shooter", "user_id": "player_42" }
  ],
  "currency": "USD",
  "balance": {
    "real": 2499,
    "bonus": 500
  }
}
```

### List Accounts

[Retrieve accounts](/api-reference/accounts/list) for a game:

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const { accounts } = await toffee.accounts.list({ gameId: "space_shooter" });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = await toffee.accounts.list(ListAccountsRequest(game_id="space_shooter"))
    accounts = resp.accounts
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    resp, err := toffee.Accounts.List(ctx, &sdk.ListAccountsRequest{
      GameId: "space_shooter",
    })
    accounts := resp.GetAccounts()
    ```
  </Tab>

  <Tab title="API">
    ```http theme={null}
    GET /v1/accounts?game_id=space_shooter&limit=100&offset=0
    Authorization: Bearer <your_access_token>
    ```
  </Tab>
</Tabs>

**Response:**

```json theme={null}
[
  {
    "id": "acc_xyz123",
    "users": [
      { "game_id": "space_shooter", "user_id": "player_42" }
    ],
    "currency": "USD",
    "balance": {
      "real": 2499,
      "bonus": 500
    }
  }
]
```

***

## Deposits

Deposits represent top-up transactions into a user's Toffee Wallet. When a user adds funds through the Toffee Wallet app, a deposit is created and processed through the configured payment method.

### Deposit Statuses

Deposits can have the following statuses:

* `processing`: Deposit is being processed by the payment provider
* `authorized`: Deposit has been authorized but not yet captured
* `succeeded`: Deposit completed successfully
* `cancelled`: Authorized deposit was cancelled before capture
* `failed`: Deposit processing failed
* `refunded`: Deposit was refunded

### Timestamp Fields

Deposits include relevant timestamp fields based on their final status:

* `created_at`: When the deposit was initiated
* `authorized_at`: When the deposit was authorized (if applicable)
* `succeeded_at`: When the deposit completed successfully (if applicable)
* `failed_at`: When the deposit failed (if applicable)
* `cancelled_at`: When the deposit was cancelled (if applicable)
* `refunded_at`: When the deposit was refunded (if applicable)

### Webhook Events

* [`deposit.succeeded`](/api-reference/webhooks/deposit.succeeded): When a deposit completes successfully
* [`deposit.failed`](/api-reference/webhooks/deposit.failed): When a deposit attempt fails

When a deposit is completed or failed, ToffeePay sends a **signed webhook** to your backend:

```json theme={null}
{
  "type": "deposit.succeeded",
  "timestamp": "2023-06-01T12:10:00Z",
  "data": {
    // Deposit object
  }
}
```

See the [Webhooks](/webhooks) page for implementation details and signature verification.

### Get Deposit

[Retrieve details](/api-reference/deposits/get) of a deposit:

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const { deposit } = await toffee.deposits.get({ id: "dep_xyz789" });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = await toffee.deposits.get(GetDepositRequest(id="dep_xyz789"))
    deposit = resp.deposit
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    resp, err := toffee.Deposits.Get(ctx, &sdk.GetDepositRequest{Id: "dep_xyz789"})
    deposit := resp.GetDeposit()
    ```
  </Tab>

  <Tab title="API">
    ```http theme={null}
    GET /v1/deposits/dep_xyz789
    Authorization: Bearer <your_access_token>
    ```
  </Tab>
</Tabs>

**Response:**

```json theme={null}
{
  "id": "dep_xyz789",
  "account_id": "acc_xyz123",
  "status": "succeeded",
  "amount": 2499,
  "currency": "USD",
  "method": "apple_pay",
  "details": "Top-up",
  "created_at": "2023-06-01T12:05:00Z",
  "succeeded_at": "2023-06-01T12:05:30Z"
}
```

### List Deposits

[Retrieve historical deposits](/api-reference/deposits/list):

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const { deposits } = await toffee.deposits.list({ accountId: "acc_xyz123" });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = await toffee.deposits.list(ListDepositsRequest(account_id="acc_xyz123"))
    deposits = resp.deposits
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    resp, err := toffee.Deposits.List(ctx, &sdk.ListDepositsRequest{
      AccountId: "acc_xyz123",
    })
    deposits := resp.GetDeposits()
    ```
  </Tab>

  <Tab title="API">
    ```http theme={null}
    GET /v1/deposits?account_id=acc_xyz123&limit=100&offset=0
    Authorization: Bearer <your_access_token>
    ```
  </Tab>
</Tabs>

**Response:**

```json theme={null}
[
  {
    "id": "dep_xyz789",
    "account_id": "acc_xyz123",
    "status": "succeeded",
    "amount": 2499,
    "currency": "USD",
    "method": "apple_pay",
    "details": "Top-up",
    "created_at": "2023-06-01T12:05:00Z",
    "succeeded_at": "2023-06-01T12:05:30Z"
  }
]
```