In-App Purchase Integration

Overview

In-app purchase integration enables you to track player purchases and sync entitlements from third-party platforms such as PlayStation or Xbox. That way, any in-app items that are sold and granted to the player from a third-party platform will also be transferred to our platform, as long as our platform has the proper ID for the item from the platform you’re using. Items that can be sold include coins, bundles, loot boxes, and in-game items, both consumable and durable.

How It Works

Item Mapping and Setup

To ensure that your game can synchronize entitlements between PSN or Xbox and AccelByte services, you must first create your items in PSN or Xbox, and then create them in the AccelByte Admin Portal. To learn more about creating items in PSN and Xbox, check out the PSN and Xbox documentation (login required for both). You can also check out our Create an Item tutorial for instructions on creating an item in the Admin Portal.

When creating your item in the Admin Portal, you will need to input a specific ID from the 3rd party platform. This will ensure that the items in the 3rd party platform are mapped correctly to their counterparts in the AccelByte platform. The IDs used to map items from each platform are as follows:

  • PSN has an entitlement service that creates an Entitlement Label for each item in its catalog that is derived from the last characters of an item’s SKU. When you create an item in the Admin Portal, make sure you include this Entitlement Label to map your item to its counterpart in PSN.
  • Xbox items have multiple IDs. The ID used to map the item in our Admin Portal to Xbox is the StoreID. When you create an item in the Admin Portal, include the StoreID to map your item to its counterpart in Xbox.

Once you create an item in the Admin Portal that includes the correct mapping ID from your platform, your game will be able to sync the items from our platform and the 3rd party.

When a game syncs items from a 3rd party platform and AccelByte, it takes the use count of the item from our services and the quantity of the item from the 3rd party. For example, if you have a consumable weapon that can be used 10 times before it breaks, the use count should be input as 10 in the AccelByte Admin Portal and the quantity should be input as 1 in PSN or Xbox. Alternatively, if you want to sell a 10-pack of single use healing potions, the use count of a potion would be 1 and the quantity would be 10. If you input 10 in both our platform and the 3rd party platform, you’ll end up with 10 copies of an item that can each be used 10 times, i.e. your entitlement will have 100 uses total. To avoid this issue, always ensure that the use count and quantity values input in both platforms are accurate.

Please also be aware that although neither PSN nor Xbox currently have designations for durable items, you can sell durable items such as equipment or character skins using AccelByte services. Any item that you set as durable when you create it in our Admin Portal will be durable in your game, even if your 3rd party platform doesn’t have a configuration specifically for durable items.

Tutorials

PSN Configuration

Add a New PSN Configuration Through Admin Portal

Before starting the tutorial, make sure you have registered the PS4 Client to our IAM.

  1. In the Admin Portal, go to the E-Commerce section and click on the In-App Purchase menu.

    iap

  2. If you’re logged into the Publisher Namespace, you need to choose the Game Namespace where you want to configure In-App Purchases.

    iap

  • If you’re logged into a Game Namespace, you can configure In-App Purchases directly by clicking the Add Configuration button.

    iap

    Note that each namespace can only have one configuration.

  1. Fill in the required fields:

    iap

    • Input the PlayStation Client ID.

    • Input the PlayStation Secret.

    • Select the Environment, e.g. sp-int for Development, prod-qa for QA, or np for Live Environment.

    • Input the PlayStation Redirect URI. This field is optional, if you leave it empty the value will be orbis://.

      Make sure you have also created a service in PlayStation Store Delivered Content inside your AppServer.

  2. Once the configuration is complete, you will see the Configuration Details in the In-App Purchase Integration menu. If needed, you can edit or remove the configuration from here.

    iap

Manage Your PSN Configuration Using API

Retrieve Your PSN Configuration

If you need to retrieve your IAP Configuration, follow these steps to make the request:

  1. Use the Get PlayStation IAP Config: GET - /admin/namespaces/{namespace}/iap/config/playstation endpoint.
  2. Input the Namespace where the configuration belongs.

Upon successful request, you will be able to retrieve the configuration.

Update Your PSN Configuration

You can update your PSN configuration by following the steps below:

  1. Use the Update PlayStation IAP Config: PUT - /admin/namespaces/{namespace}/iap/config/playstation endpoint.

  2. Input the Namespace where the configuration belongs.

  3. Fill out the Request Body:

    These following fields are required.

    • Input the Client ID.

    • Input the Client Secret.

    • Input the Environment.

      The following field is optional.

    • Input the Redirect URI. You can leave it blank and the default redirect URI will be orbis://.

Upon successful request, you will be able to update the configuration.

Xbox Configuration

Add a New Xbox Configuration Through the Admin Portal

Before starting the tutorial, make sure you have registered the XBL Client to our IAM.

  1. Go to the In-App Purchase menu in the Admin Portal. If you’re logged into the Publisher Namespace, you need to choose the Game Namespace where you want to configure In-App Purchases.

    iap

  • If you’re logged into a Game Namespace, you can configure In-App Purchases directly by clicking the Add Configuration button.

    iap

    Note that each namespace can only have one configuration.

  1. Fill in the required fields:

    iap

    • Input the Relying Private Key in Base64 format.
    • Upload your Business Partner Certificate in .pkf format.
    • Input your Certificate Password. This field is optional, if your certificate requires a password, you need to input the certificate password.

    Click Create and your new configuration will be added to the list.

  2. Once the configuration is complete, you will see the Configuration Details in the In-App Purchase Integration menu. If needed, you can edit or remove the configuration from here.

    iap

Change Your Business Partner Certificate

  1. In the Admin Portal, go to the In-App Purchase menu and choose the namespace where the configuration belongs. In the configuration details, click the Change link in the Business Partner Certificate section.

    iap

  2. A pop up will appear. Fill in the required fields:

    iap

    • Upload your Business Partner Certificate in .pkf format.
    • Input your Certificate Password.

Manage Your XBL Configuration Using API

Retrieve Your XBL IAP Configuration

If you need to retrieve your IAP Configuration, follow these steps to make the request:

  1. Use the Get Xbox IAP Config: GET - /admin/namespaces/{namespace}/iap/config/xbl endpoint.
  2. Input the Namespace where the configuration belongs.

Upon successful request, you will be able to retrieve the configuration.

Update Your XBL IAP Configuration

If you need to update your IAP Configuration, follow these steps to make the request:

  1. Use the Update Xbl IAP Config: PUT - /admin/namespaces/{namespace}/iap/config/xbl endpoint.
  2. Input the Namespace where the configuration belongs.
  3. Fill out the Request Body:
    • Input the Relying Party Private Key.

Upon successful request, you will be able to update the configuration.

Update Your XBL Business Partner Certificate File

Follow the steps below to update your XBL business partner certificate.

  1. Use the Upload xbl business partner cert file: PUT - ​/admin​/namespaces​/{namespace}​/iap​/config​/xbl​/cert endpoint.
  2. Input the Namespace where the configuration belongs.
  3. Upload the Business Partner Certificate in .pkf format.
  4. Input your Certificate Password.

Upon successful request, the certificate will be updated.

Retrieve IAP Orders Using API

You can get a list of your IAP Orders by following the steps below:

  1. Use the Query IAP Orders: GET - /admin/namespaces/{namespace}/users/{userId}/iap endpoint.
  2. Input the Namespace where the configuration belongs.
  3. Input the User ID of the user whose orders you want to retrieve.
  4. Select the platform in the type field. For example, choose PLAYSTATION if you want to retrieve orders from PSN. You can also leave this blank to retrieve orders from all platforms.
  5. Input the Product ID to retrieve only orders for a particular product, or leave blank to retrieve orders for all products.
  6. Select the orders’ status. The available values are Verified, Fulfilled, and Failed. You can also leave this blank to retrieve all orders.
  7. Input the Start and End Time of the time period you want to retrieve orders from, using ISO 8601 format e.g. yyyy-MM-dd'T'HH:mm:ssZZ. To retrieve all orders, leave these fields blank
  8. Input the offset and limit if you want the returned data to be paginated. Otherwise, leave these blank.

Upon successful request, you will be able to retrieve the list of IAP Orders.

Entitlement Synchronization

Synchronize with Entitlement in PSN Store

You can synchronize your entitlement in the PSN Store by following these steps to make the request:

  1. Use the Synchronize with entitlements in PSN Store: PUT - /public/namespaces/{namespace}/users/{userId}/iap/psn/sync endpoint.
  2. Input the Namespace where the configuration belongs.
  3. Input the User ID where the entitlement belongs.
  4. Fill out the Request Body:
    • Input the Playstation Auth Code with the value you previously input as the PSN Redirect URI.

Upon successful request, you will be able to synchronize the entitlement.

Synchronize with Entitlement in Xbox Store

You can synchronize your entitlement in the Xbox Store by following these steps to make the request:

  1. Use the Sync Xbox Inventory: PUT - /public/namespaces/{namespace}/users/{userId}/iap/xbox/sync endpoint.
  2. Input the Namespace where the configuration belongs.
  3. Input the User ID where the entitlement belongs.
  4. Fill out the Request Body:
    • Input the Xsts Token.

Upon successful request, you will be able to synchronize the entitlement.

What’s Next?