In-App Purchases

In this article, you'll learn how to implement payments using PaymentsKit. In no time players in your game will easily be able to make purchases of items, cosmetics, currencies, or anything else you want to offer them.

1) Create a product in the Trail Game Manager (manage.trail.gg/).
2) Display the product in your game by fetching the price & currency.
3) Trigger the payment.
4) Consume entitlements

📘

This guide assumes that you are familiar with the Game Manager and will not discuss its different components. If you'd like to learn more about its different features we suggest you check out the Game To Web sections first.

Creating a product

First, let's navigate to the Game Manager. Select your project (game) and then click on In-game purchases:

1) Click on the Create product button.

2) Add your IAP information: Name, Icon, and Price Tier (Price Tiers?).

📘

Price Tiers

As mentioned in 💰 Monetization article, Trail uses tiers for pricing. This removes the burden of caring about currencies, taxes, and localization; your IAP price will always look good for the user in any currency without any work from you.

❗️

Upsell Window

The Upsell Window is a feature that we currently recommend you keep disabled.

🚧

Be descriptive

It is important to be accurate and descriptive when naming your product. The name you enter will be shown to the player when buying and will appear on the receipt they receive by email.

100 Gold Coins is a good name because it tells the player what kind of item they are buying (Gold Coins) and how many of them (100). Be both descriptive and specific!

Finally, it is a good idea to use the same image as used in-game.

📘

Editing a product

You can edit a product after creating it by simply clicking on the created product's name. You can modify the icon and name. However, you can not modify the price tier. If you want to modify a price tier, simply make a new product. If you must change a tier, reach out to us on Discord

Once a product is created, it is marked as consumable and its unique product ID is generated. The product ID is vital as you'll be using it to reference your product in code when calling for either pricing information or initializing a purchase.

Displaying a product in-game

📘

API References

You can find the methods for PaymentsKit in the references for the Unity SDK and for the C SDK.

Now that we've set up a product, the next step is to show the product to the user so they can buy it. This can be done in a myriad of ways and depends highly on your game. We won't get into details of how you can design or show the information to the player. Instead, we'll look at how you can obtain the information from Trail so you can use it in your design.

The main piece of information you'd need from Trail is the price, so let's request a product price:

// Remember to initialize the SDK first.
// using Trail;

private void RequestProductPriceFromTrail()
{
    // We tell Trail to send us the product ID
  Trail.PaymentsKit.GetProductPrice("ff148434-9d1c-11eb-b2d9-c7e44343d0cd", PriceRequestCallback);
}

// Callback that fires when the request is done
private void PriceRequestCallback(Result result, Price price)
{
    if(result.IsOk()) {
    // We then pass the price and the information to the game so it displays it for the player
    DisplayItem(itemName, itemDescription, price.ToString());
  }
  else {
    Debug.Log("Error occured when fetching price information: " + result);
  }
}

Here is a coding recipe that walks you through the process of implementing price fetching using Trail!

📘

What is price.ToString()

price.ToString() combines the price and currency into one string. So in our example, it would say "3.99 Currency" where "Currency" in this case is replaced with your regional currency (USD, Euro, etc...).

If you want to get the price amount and the currency separately, you can then use price.Amount for the amount itself and price.CurrencyISO4217 for the currency itself.

Next, the player will probably want to buy the item so we need to request a payment.

Requesting a payment

Let's return to Unity and request payment when your players click the purchase button.

// Remember to initialize the SDK first.
// using Trail;

// Calling the method below will show the payment dialog to the user.
Trail.PaymentsKit.RequestPayment("ff148434-9d1c-11eb-b2d9-c7e44343d0cd",PaymentRequestCallback);
  
  
void PaymentRequestCallback (Result result, string orderId, string entitlementId)
  {
    // First, check that there was not unexpected error.
    if (result.IsOk()) {
    // The function below is just a placeholder.
    // You will have to replace it with whatever method you use
    // to send entitlements to your backend.
      MyGameBackend.ConsumeEntitlement(orderID, entitlementID);
    } 
    else 
    {
      Debug.LogError("Payment Error: " + result);
    }
}

Let's go over the code; first, we send a RequestPayment using the payment ID and wait for the request to finish. Once it is done, the callback RequestPaymentCallback will run. We check if the result is good to go. If so, we report it to our back end to start the next step (note that you receive both the orderID and entitlementID in the callback. If not, we print the error out so we can debug it.

Consuming the Entitlement

As discussed in the 💰 Monetization article; a consumable product produces an entitlement (a receipt stating the player's ownership of the items bought) so you can consume it in your backend when the item is granted to the player.

Consuming a product is done through an HTTP cURL post:

POST v2/payments-kit/consume-entitlement
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_API_TOKEN>' \
--data-raw '{
    "entitlement_id": "00000000-0000-0000-0000-000000000000"
}'

Resolving unconsumed entitlements

Sometimes, an entitlement doesn't get consumed (e.g., Internet connectivity issues, a crash, or the user quits early), which is why it is important that your game always checks if there are any unconsumed entitlements on startup, and if there any proceeds to consume them using the same process as if they had just been purchased.

To check for unconsumed entitlements use the following SDK method.

// Call the following method as soon as the game has booted
// and the SDK initialized.
// using Trail;

Trail.PaymentsKit.GetEntitlements(
  (Result result, PaymentsKit.Entitlement[] entitlements) => 
    {
    // First, check that there was not unexpected error.
    if (result.IsOk()) {
      // The function below is just a placeholder.
      // You will have to replace it with whatever method you use
      // to send entitlements to your backend.
      MyGameBackend.ConsumeEntitlements(entitlements);
    }
    else
    {
      Debug.LogError("Something went wrong. " + result);
    }
  }
);