Last Updated: 9/6/2021, 8:19:04 AM

# 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.

# 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 In-App Purchase Integration in the Admin Portal. For a full list of permissions that impact in-app purchase management, see the Platform/Commerce tab of the permissions reference (opens new window).

Usage Permission Tag Action
Retrieve Your PSN Configuration ADMIN:NAMESPACE:{namespace}:IAP:CONFIG READ
Update Your PSN Configuration ADMIN:NAMESPACE:{namespace}:IAP:CONFIG UPDATE
Retrieve Your XBL IAP Configuration ADMIN:NAMESPACE:{namespace}:IAP:CONFIG READ
Update Your XBL IAP Configuration ADMIN:NAMESPACE:{namespace}:IAP:CONFIG UPDATE
Update Your XBL Business Partner Certificate File ADMIN:NAMESPACE:{namespace}:IAP:CONFIG UPDATE
Retrieve Your Steam Configuration ADMIN:NAMESPACE:{namespace}:IAP:CONFIG READ
Update Your Steam Configuration ADMIN:NAMESPACE:{namespace}:IAP:CONFIG UPDATE
Retrieve Your Steam Configuration ADMIN:NAMESPACE:{namespace}:IAP:CONFIG READ
Update Your Stadia Configuration File ADMIN:NAMESPACE:{namespace}:IAP:CONFIG UPDATE
Retrieve IAP Orders Using API ADMIN:NAMESPACE:{namespace}:IAP:CONFIG READ
Synchronize with Entitlement in PSN Store ADMIN:NAMESPACE:{namespace}:IAP:CONFIG UPDATE
Synchronize with Entitlement in Xbox Store ADMIN:NAMESPACE:{namespace}:IAP:CONFIG UPDATE
Synchronize with Entitlement in Steam ADMIN:NAMESPACE:{namespace}:IAP:CONFIG UPDATE
Synchronize with Entitlement in Stadia ADMIN:NAMESPACE:{namespace}:IAP:CONFIG UPDATE

Permissions work slightly differently depending on whether they are assigned to IAM Clients or Roles assigned to users. For more information, read the Authentication and Authorization documentation.

# Managing In-App Purchase Integration in the Admin Portal

# PSN

# Add a New PSN Configuration

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.

  3. 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.

  4. 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

# Xbox

# Add a New Xbox Configuration

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.

  2. 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.

  3. 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.

# Steam

# Add a New Steam Configuration

Before you create a new Steam configuration, make sure you have registered the Steam 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 switch to 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 for each platform.

  2. The Add Configuration form appears. Here, input the Steam Web API Key.

    iap

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

  3. 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

# Stadia

# Add a New Stadia Configuration

Before creating a new Stadia configuration, make sure you have registered the Stadia 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 switch to 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 for each platform.

  2. The Add Configuration form appears. Here, upload the Stadia Configuration File.

    iap

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

  3. 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

# Managing In-App Purchase Integration using API

# PSN

# 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. Here is an example of a response to a successful request:

# 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. Here is an example of a response to a successful request:

# Xbox

# 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. Here is an example of a response to a successful request:

# 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. Here is an example of a response to a successful request:

# 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. Here is an example of a response to a successful request:

# Steam

# Retrieve Your Steam Configuration

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

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

Upon successful request, you will be able to retrieve the configuration. Here is an example of a response to a successful request:

# Update Your Steam Configuration

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

  1. Use the Update Steam IAP Config: PUT - /admin/namespaces/{namespace}/iap/config/steam endpoint.
  2. Input the Namespace where the configuration belongs.
  3. Fill out the Request Body:
    • Input the publisherAuthenticationKey.

Upon successful request, you will be able to update the configuration. Here is an example of a response to a successful request:

# Stadia

# Retrieve Your Stadia Configuration

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

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

Upon successful request, you will be able to retrieve the configuration. Here is an example of a response to a successful request:

# Update Your Stadia Configuration File

Follow the steps below to update your Stadia configuration file.

  1. Use the Upload Stadia JSON Config: PUT - /admin/namespaces/{namespace}/iap/config/stadia/cert endpoint.
  2. Input the Namespace where the configuration belongs.
  3. Upload the Stadia Configuration File in JSON format.

Upon successful request, you will be able to update the configuration file. Here is an example of a response to a successful request:

# Retrieve IAP Orders

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. Here is an example of a response to a successful request:

# 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. Here is an example of a response to a successful request:

# 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. Here is an example of a response to a successful request:

# Synchronize with Entitlement in Steam

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

  1. Use the Sync Steam Inventory: PUT - /public/namespaces/{namespace}/users/{userId}/iap/steam/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 Steam ID.
    • Input the App ID.
    • Input the Region.
    • Input the Language.

Upon successful request, you will be able to synchronize the entitlement. A successful request returns Code 204 No Content which indicates that the request was successful.

# Synchronize with Entitlement in Stadia

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

  1. Use the Sync Stadia Inventory: PUT - /public/namespaces/{namespace}/users/{userId}/iap/stadia/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 Stadia Player ID.
    • Input the App ID.
    • Input the Region.
    • Input the Language.

Upon successful request, you will be able to synchronize the entitlement. A successful request returns Code 204 No Content which indicates that the request was successful.