Managing wallets

Last updated on September 6, 2024

Overview

The AccelByte Gaming Services (AGS) Wallet service provides a way for your players to hold virtual currency within their profiles. This guide will teach you how to configure wallets in your game, and how to manage your players' wallets once configured.

This article walks you through how to:

• Add the origin of virtual currency
• Sort payment rules
• View, credit, and debit player wallets

Prerequisites

• You must create an IAM Client for each third-party platform virtual currency you want to support. You can set this up by entering each selected third-party platform into the Platform field when you create an IAM Client.

  • On the sidebar, go to Game Setup > Games and Apps > IAM Clients.

  • Click on the +Create New button.

  • Fill in the form and make sure to enter the selected third-party platform into the Platform field.

    

• You must create a virtual currency (in Manage Virtual Currencies) before you can begin working with wallets. You can check the Currency page in the Admin Portal to see if any virtual currencies already exist in your publisher or game namespace.

  

• (Optional) Virtual currency cannot be directly sold to players. If you would like to sell virtual currencies, you will need to create an item, with Item Type as Coin, for your currency. You can still credit and debit virtual currencies to players' wallets without creating Coins.

  • 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 virtual currency. For more information, refer to Set Up, Configure and Prepare a Store.

  • If you already have a Draft Store, you'll need to create an item in it for the virtual 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. If no items are returned by the search, you'll need to create one.

    

Manage payment rules

You can cross-add virtual currency sources to another in the In-App Purchase platform. For example, you can add PlayStation and Steam as a source of payment to Xbox, so you can make purchases on Xbox using your PlayStation or Steam balance. Below is a list of the default settings in the Admin Portal which you can adjust at any time.

Playing on Platform	Source of Balance
PlayStation	PlayStation + System
Xbox	All
Steam	All
Epic	All
Apple	All
Google Play	All
Nintendo	Nintendo + System
Other	All

note

System (virtual currency) lets you use the balance from another service, such as Entitlements, or Rewards, to make purchases.

After adding a virtual currency source, you can sort these sources to prioritize which balance is used first when making purchases. For example, you can make PlayStation top priority, followed by Steam, meaning that the cost of any purchase will be debited first from a player's PlayStation balance and then Steam (if there are insufficient funds in the player's PlayStation balance to cover the total purchase cost).

Wallets can hold two types of balances: a Permanent Balance and a Time-Limited Balance. Time-limited balances come with an expiration date, after which the player will lose this balance if it has not been spent. Permanent balances have no expiration date.

Time-limited balances are prioritized in purchases and will be used to make purchases even if the source of the balance is not as highly-prioritized as another permanent balance. In other words, if PlayStation is prioritized as the first source of currency but a player has a time-limited balance in their Steam wallet, the time-limited Steam balance will be used first, with any remaining costs then being taken from their PlayStation wallet.

note

Time-limited balance only applies to virtual currencies purchased using real money, and is only enabled by default for Japan but turned off by default for other regions.

Add Origin of Virtual Currency to Wallet

Under the Platform Wallet configuration, you can configure the Origin of Virtual Currency. The Origin of Virtual Currency added to a platform will determine whether a player can spend the virtual currency in the wallet on that specific platform. For example, under the PlayStation tab, if Epic is added as an Origin of Virtual Currency, then it means players can use their virtual currency balance from Epic on PlayStation.

1. On the Admin Portal sidebar, go to Commerce > Wallets > Configurations.

2. Choose the platform you want to add from the tabs at the top of the page.

3. On your selected platform, click the Add button.

4. The Add Origin of Virtual Currency form will appear. Choose the origin of the virtual currency you want to add from the dropdown.

   

   note

   Choose Other if you want to add any In-App Purchases that are not listed in the table above.

Change order of payment rules

1. On the Admin Portal sidebar, go to Commerce > Wallets > Configurations. Open your selected platform from the tabs at the top of the page.

   

2. Click the Sort Order button, then click and drag each source to adjust its priority. Note that the higher the source, the higher its priority (e.g., Priority Order 1 is higher than Priority Order 2).

3. Click the Save Order button to save your changes.

Manage player wallets

You can view a player's transaction history, credit, and debit for each of their wallets in the Admin Portal.

View a player's wallet details

1. On the Admin Portal sidebar, go to Commerce > Wallets > User Wallets.

2. Select the appropriate search filter from the dropdown menu, depending on what player account information you have on hand. You can search by Email or User ID. Fill in this information into the search bar and click Enter to search. The search results will include a list of the wallets owned by the target player.

3. Select a wallet to view the list of the virtual currency origins available.

   

4. You can view the transaction history of the selected wallet. by clicking View in the History column on the right-hand side. The history is listed in descending order with the most recent transactions at the top.

   

Credit a player's wallet

1. Click the Credit button. The Credit Wallet form appears.

   

2. Fill in the required information on the form:

   • Select the wallet of the specific currency you want to credit from the Currency field.

   • Type in the amount you want to credit in the Credit field.

   • Select the source of the credit from the Source dropdown menu. This is a memo field to help you keep track of where credits originated. The options are as follows:

     • 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

   • Select the Origin of Virtual Currency from the dropdown.

   • Define the time when the credit will expire using the Expired At field. This field is optional. If left blank, the credit will be a Permanent Balance.

   • Fill in the reason for the credit in the Reason field.

3. Click the Credit button to grant the credit amount to the selected wallet.

Credit a player's sub-wallet

If a wallet contains a type of virtual currency called VC1, under this wallet, there can be various sources/origins of VC1. For example, if VC1 comes from PlayStation, PlayStation will be marked as the Origin of Virtual Currency, which we refer to as a sub-wallet. When you credit a sub-wallet with PlayStation as an origin, that means that PlayStation is the source of this virtual currency.

1. You can also credit a specific sub-wallet by clicking Credit on the selected sub-wallet under the Actions column on the Wallets page. The Credit Wallet form appears.

   

2. Fill in the required information on the form:

   • Type in the amount you want to credit to the Credit field. Select the source of the credit from the Source dropdown menu. The options are the same as the previous form.
   • Define the time when the credit will expire using the Expired At field. This field is optional. If left blank, the credit will be a Permanent Balance.
   • Fill in the the reason for the credit in the Reason field.

3. Click the Credit button to grant the credit amount to the selected sub-wallet.

Debit a player's sub-wallet

1. You can also debit a specific sub-wallet by clicking Debit on the selected sub-wallet under the Actions column on the Wallets page. The Debit Wallet form appears.

   

2. Fill in the required information on the form:

   • Type in the amount you want to debit from the player's wallet in the Amount field.
   • Fill in the reason for the debit in the Reason field.

3. Click the Debit button to subtract the amount from the selected sub-wallet.

Implement Wallets Using the SDKs

Get Wallet Data

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

We now support multi-platform wallets. You can call GetWalletInfoByCurrencyCodeV2 to retrieve a wallet's transaction data based on the currency it uses. The CurrencyCode parameter determines the currency that will be retrieved.

Unreal Engine

FString CurrencyCode = TEXT("SampleCurrencyCode");
FRegistry::Wallet.GetWalletInfoByCurrencyCodeV2(CurrencyCode,     
   THandler<FAccelByteModelsWalletInfoResponse>::CreateLambda(
   [=](const FAccelByteModelsWalletInfoResponse& Result)
{
  UE_LOG(LogTemp, Log, TEXT("Wallet Balance : %d"), Result.Balance); 
}), FErrorHandler::CreateLambda([](int32 Code, const FString& Message)
{
    UE_LOG(LogTemp, Error, TEXT("Code : %d, Message : %s"), Code, *Message);
});

Unity

var wallet = AccelByteSDK.GetClientRegistry().GetApi().GetWallet();

string currencyCode = "sampleCurrencyCode";
Result<WalletInfoResponse> getWalletInfoResult = null;

wallet.GetWalletInfoByCurrencyCodeV2(currencyCode, result => 
{    
    if (result.IsError)
    {
        // Handle API failure or error here
        Debug.Log($"Error: {result.Error.Message}");
        return;
    }

    // Handle API success here
    getWalletInfoResult = result; 
});

Go Extend SDK

walletService := &platform.WalletService{
    Client:          factory.NewPlatformClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
currencyCode := "sampleCurrencyCode"
namespace := "mygame"
input := &wallet.PublicGetMyWalletParams{
    CurrencyCode: currencyCode,
    Namespace:    namespace,
}
result, err := walletService.PublicGetMyWalletShort(input)

Python Extend SDK

import accelbyte_py_sdk.api.platform as platform_service

result, error = platform_service.public_get_wallet(
    currency_code="sampleCurrencyCode",
    user_id="********************************",
)
if error:
    exit(error)

Java Extend SDK

Wallet walletWrapper = new Wallet(sdk);

String currencyCode = "sampleCurrencyCode";
PlatformWallet response;
try {
    response = walletWrapper.publicGetMyWallet(PublicGetMyWallet.builder()
        .namespace("<namespace>")
        .currencyCode(currencyCode)
        .build());
} catch (Exception e) {
    // Do something when failed
    return;
}

if (response == null) {
    // Null response from server
} else {
    // Do something when successful
}

C# Extend SDK

string currencyCode = "sampleCurrencyCode";

var response = sdk.Platform.Wallet.PublicGetMyWalletOp
    .Execute(currencyCode, sdk.Namespace);
if (response != null)
{
    //do something if success
}

Troubleshooting

There is no need to create a wallet. Wallets are automatically created whenever virtual currencies are added. Even without adding virtual currencies to a wallet, a wallet with balance 0 is displayed on the front-end.