Skip to main content

Wallet

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

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 CreateSession 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.

POST /pay.v1.PaymentService/CreateSession
Authorization: Bearer <your_api_key>
Content-Type: application/json

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

Topup Statuses​

Topups can have the following statuses:

  • processing: Topup is being processed by the payment provider
  • authorized: Topup has been authorized but not yet captured
  • succeeded: Topup completed successfully
  • cancelled: Authorized topup was cancelled before capture
  • failed: Topup processing failed

Timestamp Fields​

Topups include relevant timestamp fields based on their final status:

  • created_at: When the topup was initiated
  • authorized_at: When the topup was authorized (if applicable)
  • succeeded_at: When the topup completed successfully (if applicable)
  • failed_at: When the topup failed (if applicable)
  • cancelled_at: When the topup was cancelled (if applicable)

Webhook Events​

ToffeePay sends webhooks for the following topup-related events:

Topup Events​

  • topup.succeeded: When topup completes successfully
  • topup.failed: When topup attempt fails

See the Webhooks page for implementation details and signature verification.

Handle Topup Notifications​

When a topup is completed or failed, ToffeePay sends a signed webhook to your backend.

Sample Payload:

{
  "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "event": "topup.succeeded",
  "timestamp": "2023-06-01T12:10:00Z",
  "data": {
    "topup_id": "wp_xyz789"
  }
}

For webhook signature verification, see the Webhooks page.

Get Topup Details​

Retrieve details of a topup:

POST /pay.v1.PaymentService/GetTopup
Authorization: Bearer <your_api_key>
Content-Type: application/json

{
  "id": "wp_xyz789"
}

Response:

{
  "topup": {
    "id": "wp_xyz789",
    "wallet_user_id": "user_xyz123",
    "game_users": [{ "game_id": "game_xyz123", "user_id": "player_32" }],
    "status": "succeeded",
    "amount": 2499,
    "reward": 500,
    "currency": "USD",
    "method": "apple_pay",
    "created_at": "2023-06-01T12:05:00Z",
    "succeeded_at": "2023-06-01T12:05:30Z"
  }
}

List Topups​

Retrieve historical topups:

POST /pay.v1.PaymentService/ListTopups
Authorization: Bearer <your_api_key>
Content-Type: application/json

{
  "game_id": "game_xyz123",
  "wallet_user_id": "user_xyz123",
  "game_user_id": "player_32",
  "limit": 100,
  "offset": 0
}

Response:

{
  "topups": [
    {
      "id": "wp_xyz789",
      "wallet_user_id": "user_xyz123",
      "game_users": [{ "game_id": "game_xyz123", "user_id": "player_32" }],
      "status": "succeeded",
      "amount": 2499,
      "reward": 500,
      "currency": "USD",
      "method": "apple_pay",
      "created_at": "2023-06-01T12:05:00Z",
      "succeeded_at": "2023-06-01T12:05:30Z"
    }
  ],
  "total": 1,
  "has_more": false
}