Skip to main content

​
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
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

​
iOS

https://apps.apple.com/us/app/toffee-wallet/id6751423503

​
Android

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 request.
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.
POST /v1/sessions
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  ...other_params,
  "wallet_enabled": true
}

​
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 by ID: 
GET /v1/accounts/acc_xyz123
Authorization: Bearer <your_access_token>
Response: 
{
  "id": "acc_xyz123",
  "users": [
    { "game_id": "space_shooter", "user_id": "player_42" }
  ],
  "currency": "USD",
  "balance": {
    "real": 2499,
    "bonus": 500
  }
}

​
List Accounts

Retrieve accounts for a game: 
GET /v1/accounts?game_id=space_shooter&limit=100&offset=0
Authorization: Bearer <your_access_token>
Response: 
[
  {
    "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

When a deposit is completed or failed, ToffeePay sends a signed webhook to your backend: 
{
  "type": "deposit.succeeded",
  "timestamp": "2023-06-01T12:10:00Z",
  "data": {
    // Deposit object
  }
}
See the Webhooks page for implementation details and signature verification.

​
Get Deposit

Retrieve details of a deposit: 
GET /v1/deposits/dep_xyz789
Authorization: Bearer <your_access_token>
Response: 
{
  "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: 
GET /v1/deposits?account_id=acc_xyz123&limit=100&offset=0
Authorization: Bearer <your_access_token>
Response: 
[
  {
    "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"
  }
]