Last Updated: 7/22/2021, 6:58:04 AM

# Wallet

# Overview

Wallets are containers that hold virtual currency, referred to here as Coins, for your players. Players can purchase virtual currency using any real currency your payment aggregator supports, and you can have multiple virtual currencies in your game. Each wallet can hold only one currency, so if your game contains multiple virtual currencies, players will have multiple wallets.

From the Admin Portal, you can credit coins to or debit coins from a wallet or view a wallet’s transaction history.

# Prerequisites and Permissions

# Prerequisites

  • If you don’t have a virtual currency yet, you should create one before working with wallets. You can check the Currency page in the Admin Portal to see if a virtual currency already exists or not.

    wallet

  • Virtual currency is treated like an in-game item by our backend services, so you should create an item for your currency before working with wallets.

    • If you don’t have an in-game store yet, first you’ll need to create a draft store and then create an item in the new store for your currency. You can check whether or not an in-game draft store has been created in the Stores page in the Admin Portal.

      wallet

    • If you already have an in-game draft store, you’ll just need to create an item in it for the currency if one doesn’t exist yet. To check whether or not an item already exists for your virtual currency, click View in the Action menu next to your in-game draft store in the Stores menu. Then, open the Items tab to search for the item. Select Filter by categories in the dropdown menu, and select Coins in the second dropdown menu that appears to narrow your search for items created for virtual currency. If no items are returned by the search, you’ll need to create an item for your currency.

      wallet

# Permissions

Permissions are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage wallets in the Admin Portal. For a full list of permissions that impact wallet management, see the Platform/Commerce tab of the permissions reference (opens new window).

Usage Resource Action
Get User’s Entitlement ADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENT Read
List User’s Wallet Transaction ADMIN:NAMESPACE:{namespace}:USER:{userId}:WALLET Read
Debit a User’s Wallet ADMIN:NAMESPACE:{namespace}:USER:{userId}:WALLET Update
Credit a User’s Wallet by Currency Code ADMIN:NAMESPACE:{namespace}:USER:{userId}:WALLET Update

# Managing Wallets in the Admin Portal

The Admin Portal gives community managers and game admins an easy way to manage players’ wallets.

# View a Player’s Transaction History

  1. In the Admin Portal, expand the Users Management section and open Users.

    wallet

  2. Select the search filter from the dropdown menu in the Search User panel that corresponds to the player’s account information that you have on hand. Then type that information in the text box and press Enter to search.

    wallet

TIP

Fuzzy search is allowed here, so you can find the player you’re looking for by typing just the first few characters of the player’s credential that you have.

  1. The results of your search will appear. Browse the list to find the account you’re looking for and click View in the Action column of the account listing to open it.

    wallet

  2. The User Overview will appear, giving you a quick look at player data such as wallet balance, ban status, and linked accounts, as well as more detailed records of the player’s activity. From here, open the Wallets tab from the ribbon at the top of the page.

    wallet

NOTE

If the Wallets tab is empty when you open it, it means that the player has never received or performed any transactions with virtual currency. Wallets are created for players the first time they purchase or otherwise receive coins.

  1. The player’s wallets will appear. Click View in the History column of a wallet to view it’s transaction history. The history is listed in descending order.

    wallet

    wallet

NOTE

You can also search for a player’s wallet on the Wallets page in the E-Commerce section on the Admin Portal. Searching for a player here requires that you have their full User ID or email address, or their Wallet ID. Like in the Users menu, no wallet will appear here if the player you search for has never received or made any transactions with coins.

# Credit or Debit Coins to or from a Player’s Wallet

  1. In the Admin Portal, expand the Users Management section and open Users.

    wallet

  2. Select the search filter from the dropdown menu in the Search User panel that corresponds to the player’s account information that you have on hand. Then type that information in the text box and press Enter to search.

    wallet

TIP

Fuzzy search is allowed here, so you can find the player you’re looking for by typing just the first few characters of the player’s credential that you have.

  1. The results of your search will appear. Browse the list to find the account you’re looking for and click View in the Action column of the account listing to open it.

    wallet

  2. The User Overview will appear, giving you a quick look at player data such as wallet balance, ban status, and linked accounts, as well as more detailed records of the player’s activity. From here, open the Wallets tab from the ribbon at the top of the page.

    wallet

    TIP

    If the Wallets tab is empty when you open it, it means that the player has never received or performed any transactions with virtual currency. If this happens when you’re trying to credit coins to a player, you should grant the coins to the player as an entitlement instead.

  3. The player’s wallets will appear. Click Credit or Debit in the Action column of a wallet to credit coins to or debit coins from that wallet.

    wallet

    • When you click Credit, the Credit Wallet form appears. All fields are required.

    • Input the Amount of coins you want to credit to the player’s wallet.

    • Select the Source of the credit from the dropdown menu. This is a memo field to help you keep track of where credits originated.

      • Purchase: Credit from player purchase of virtual currency
      • Promotion: Credit from promotional giveaway
      • Achievement: Credit from the player earning an achievement
      • Referral_Bonus: Credit from a referral bonus
      • Redeem Code: Credit from a redemption code
      • Other: Any other source of credit
    • Type the Reason for the credit.

      wallet

    • When you click Debit, the Debit Wallet form appears. All fields are required.

      • Input the Amount you want to debit from the player’s wallet.
      • Type the Reason for the debit.

      wallet

  4. When you’re finished filling out either form, click the Credit or Debit button. The player’s balance will immediately reflect the change.

wallet

NOTE

You can also search for a player’s wallet on the Wallets page in the E-Commerce section on the Admin Portal. Searching for a player here requires that you have their full User ID or email address, or the Wallet ID of the wallet. Like in the Users menu, no wallet will appear here if the player you search for has never received or made any transactions with coins.

# Managing Wallets Using the SDK

Our SDK can also be used to allow a game client to retrieve wallet data.

# Get Wallet Data

Calling GetWalletInfoByCurrencyCode will retrieve a wallet’s transaction data based on the currency it uses. The Currency parameter determines the currency retrieved.

# Managing Wallets Using API

You can also use our API endpoints to manage players’ wallets.

# Get Wallet Data

You can retrieve wallet data such as its associated User ID, balance, and currency. Results are sorted by currency that is used by the wallet.

  1. Use the Get a User Wallet: GET - /admin/namespaces/{namespace}/users/{userId}/wallets/{walletId} endpoint.
  2. Input the Namespace field with the namespace the wallet can be found in. This could be your Publisher Namespace if you are accessing a wallet on your publishing platform, or your Game Namespace if the wallet is in your game..
  3. Input the Wallet ID of the wallet you want to retrieve.

INFO

A wallet ID is 32 characters long, in UUID format without hyphens. You can find it by looking up a player in the Users menu, opening their account information, and clicking the Wallets tab. Here’s an example: 8a8b9152791b43e201795c8be91d00f4

Upon successful request, the player’s wallet information will appear. Here is an example of a response to a successful request:

# View a Wallet’s Transaction History

You can retrieve a wallet’s transaction history. Transactions will be listed in descending order.

  1. Use the List User Wallet Transactions: GET - /admin/namespaces/{namespace}/users/{userId}/wallets/{walletId}/transactions endpoint.
  2. Input the Namespace field with the namespace the wallet can be found in. This could be your Publisher Namespace if you are accessing a wallet on your publishing platform, or your Game Namespace if the wallet is in your game..
  3. Input the User ID associated with the wallet you want to retrieve.
  4. Input the Wallet ID of the wallet you want to retrieve.
  5. Input the desired values into the Offset and Limit fields if you want the results to be paginated.

Upon successful request, the player’s transaction history will appear. Here is an example of a response to a successful request:

# Credit Coins to a Wallet

If the player you’re crediting doesn’t have a wallet yet, one will be created for them automatically when this endpoint is called.

  1. Use the Credit a User Wallet by Currency Code: PUT - /admin/namespaces/{namespace}/users/{userId}/wallets/{currencyCode}/credit endpoint.
  2. Input the Namespace field with the namespace the wallet can be found in. This could be your Publisher Namespace if you are accessing a wallet on your publishing platform, or your Game Namespace if the wallet is in your game..
  3. Input the User ID of the player whose wallet you want to credit.
  4. Input the Currency Code of the currency you want the credited coins to be in.
  5. Fill in the Request Body with following information:
    • Input the Amount you want to credit.
    • Input the Source of the credit. These are labels you can apply to your records to keep track of why credits were made.
      • Purchase: Credit from player purchase of virtual currency
      • Promotion: Credit from promotional giveaway
      • Achievement: Credit from the player earning an achievement
      • Referral_Bonus: Credit from a referral bonus
      • Redeem Code: Credit from a redemption code
      • Other: Any other source of credit
    • Input the Reason for the credit.

Upon successful request, the coins will be credited to the wallet. Here is an example response of a successful request:

# Debit Coins from a Wallet

  1. Use the Debit a User Wallet: PUT - /admin/namespaces/{namespace}/users/{userId}/wallets/{walletId}/debit endpoint.
  2. Input the Namespace field with the namespace the wallet can be found in. This could be your Publisher Namespace if you are accessing a wallet on your publishing platform, or your Game Namespace if the wallet is in your game.
  3. Input the User ID of the player whose wallet you want to debit coins from.
  4. Input the Wallet ID of the wallet you want to debit coins from.
  5. Fill in the Request Body with the following information:
    • Input the Amount you want to debit from the wallet.
    • Input the Reason for the debit.

Upon successful request, coins will be debited from the wallet. Here is an example response of a successful request: