GS2-Money

A feature that handles in-game resources whose value is equivalent to cash. Be sure to use this feature when handling assets that fall under prepaid payment instruments (self-issued type) as defined by the Japanese Payment Services Act.

Balance

GS2-Money does not manage a player’s billing currency balance as a simple quantity; instead, it manages quantities per the value at the time of purchase.

For example, if 100 units of billing currency are purchased for 100 yen, the value of one unit is equivalent to 1 yen. Now suppose 1,200 units of billing currency can be purchased simultaneously for 1,000 yen. One option is to keep the unit price at 1 yen and treat the extra 200 units as a free bonus; another option is to treat the units purchased for 1,000 yen as having a different unit price of 0.8334 yen.

If the latter approach is adopted, GS2-Money has the ability to separately manage the “balance of billing currency with a unit price of 1 yen” and the “balance of billing currency with a unit price of 0.8334 yen”.

graph TD
  Wallet["Wallet<br/>(distinguished by slot number)"]
  Wallet --> Paid["Paid currency<br/>(paid)"]
  Wallet --> Free["Free currency<br/>(free)"]
  Paid --> Detail1["Balance with unit price 1 yen"]
  Paid --> Detail2["Balance with unit price 0.8334 yen"]
  Paid --> Detail3["...per purchase value"]

What is the benefit of choosing the latter?

Obviously, the latter makes accounting more complex and may seem to offer no benefit. From the service provider’s perspective, that is entirely true. However, let us switch sides and think from the game player’s perspective.

Some games have a billing currency with a cash value of 0 yen (commonly called “free currency”) that is distributed by the operator. To encourage players to purchase billing currency, suppose an attractive product is sold for 300 units that can only be purchased with billing currency obtained by paying real money (commonly called “paid currency”).

If a player purchases 1,200 units of billing currency for 1,000 yen and the system grants 1,000 paid-currency units and 200 free-currency units, the player can only purchase the 300-unit product three times. On the other hand, if you treat all 1,200 units as paid currency with a unit price of 0.8334 yen, the player can purchase it four times. This difference has at least some impact on player psychology.

Whether to prioritize accounting convenience or player benefit is a specification that should be considered carefully.

Slots

GS2-Money supports multiple wallets per player. The key used to distinguish these wallets is the slot.

This feature exists in order to comply with the guidelines of platform providers that prohibit bringing in billing currency purchased on other platforms.

However, since these guidelines only apply to paid currency, there is a feature that allows free currency to be shared across all slots. By setting the namespace’s shareFree to true, free currency is treated as a balance shared across all slots.

Consumption Priority

When a player consumes billing currency, you can choose whether to consume free currency first or paid currency first. Generally, the specification of consuming free currency first is adopted, but for accounting reasons paid currency can be prioritized. When consuming paid currency, the currency with the higher unit price is consumed first.

Specify one of the following for the namespace’s priority.

We understand that there are needs to consume currencies in the order they were obtained, regardless of whether they are free or paid, or among paid currencies. However, this feature is not currently implemented. If your project requires this, please contact the development team.

Receipt Validation

GS2-Money has a feature to validate receipts obtained when purchasing additional content from game distribution platforms. The receipt is validated to confirm that it was correctly issued by the platform provider and that it has not been used in the game before.

By using this feature, you can prevent attacks that attempt to obtain billing currency using fraudulent receipts.

To enable receipt validation, register the following authentication information on the namespace.

• appleKey: The bundle ID of Apple App Store
• googleKey: The public key of Google Play
• enableFakeReceipt: Whether to allow dummy receipts during development

Transaction Log

Not only the receipt validation history but also all addition and subtraction of billing currency is recorded. Furthermore, several times a day, the system aggregates how much unused billing currency is currently pooled in the game in cash-equivalent terms. The aggregated result is reflected in the balance field of the namespace.

Depending on the situation, you may be required to deposit a portion of the unused balance with a third-party institution; this calculated result can be used in such cases.

Legal Procedures

GS2-Money collects the data required for various legal procedures and makes it accessible through the API, but the legal procedures themselves must be performed by you or your organization as the user of GS2.

GS2 cannot take responsibility for what procedures are required, and therefore cannot give advice on it. Please consult your legal counsel.

Script Triggers

By registering various script settings on the namespace, you can execute custom scripts at the timing of deposit/withdrawal processing or wallet creation.

The main event triggers and the script setting names that can be configured are as follows.

• createWalletScript: When a wallet is created
• depositScript: When a deposit is processed
• withdrawScript: When a withdrawal is processed

Transaction Actions

GS2-Money provides the following transaction actions.

• Consume action: Consume balance, Record receipt
• Acquire action: Add to balance, Delete receipt record

By using “Add to balance” as an acquire action, you can safely run processes within a transaction that directly grant billing currency (paid or free) upon clearing a specific event or as a gacha “bonus”. This enables flexible measures combining purchases with in-game rewards.

Implementation Examples

Retrieving the Balance

Specifying the wallet slot, retrieve the current paid currency balance (paid), free currency balance (free), and the breakdown by purchase unit price (detail).

    var item = await gs2.Money.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Wallet(
        slot: 0
    ).ModelAsync();

    const auto Domain = Gs2->Money->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Wallet(
        0 // slot
    );
    const auto Item = Domain->Model();

Adding to the Balance

Adding to the balance cannot be performed with game engine SDKs.

Implement it by, for example, adding to the balance as a GS2-Showcase purchase reward, or by calling the GS2-Money receipt validation API via server-to-server communication.

Consuming the Balance

We do not recommend directly consuming the balance via this API. By consuming billing currency through services such as GS2-Showcase, you can safely handle granting items in exchange for consumption as a single transaction.

By specifying paidOnly as true, only paid currency will be consumed. Use this when you need to comply with platform provider guidelines.

    var result = await gs2.Money.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Wallet(
        slot: 0
    ).WithdrawAsync(
        count: 50,
        paidOnly: false
    );
    var item = await result.ModelAsync();
    var price = result.Price;

    const auto Future = Gs2->Money->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Wallet(
        0 // slot
    )->Withdraw(
        50,
        nullptr // paidOnly
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError()) return false;

Detailed Reference