Commerce (IAP)

There are two types of items that you can offer in your game, consumable and durable.

• Durable - Durable items are single-use items that persist with the user. Meaning, once the item has been purchased, it cannot be purchased again. For example, you may offer the initial game download for free with only a demo level, then offer additional levels as in-app purchases.
• Consumable - Consumable items can be purchased multiple times. For example, consumable IAP may by 'character lives' or 'coins' that are used during the course of gameplay. Consumable purchases must be ingested by your app before they can be made available for purchased again.

Defining Items for Purchase

Before you begin integrating the IAP methods in your experience, you’ll need to define the items that you will be offering for purchase. The in-app purchase list can be updated or modified at any time.

At the moment there is no support for selling a single item with multiple currencies. A separate SKU will need to be created for each item and currency combination.

To define your IAP list open your preferred spreadsheet or text editor and create a tab-separated (.tsv) file in the following format.

The values for the items in the table above are:

• SKU - The unique string that you use to reference the IAP item in your app.
• Name - The short descriptive name that the user will see.
• Description - The full description of the item the user will see. Be as descriptive as necessary to avoid any confusion.
• Currency - Currency is the unit of currency that the item will be charged in. Supported currencies are: USD, 123, 345, 567, 34465, 546347, 53245.
• Amount - The decimal amount to charge for the IAP item.
• Item Type - The type of item for sale. Available options are 'consumable' and 'durable'. Please see the description above for the difference between the two.

An IAP item template is available for download from the IAP section of the Developer Center.

Once you’ve created your file, you can upload your IAP items to your selected experience in the IAP section of the Developer Center and selecting ‘Upload TSV’ and following the on-screen prompts.

Integrating IAP

Once you’ve finished defining the items that you would like to offer as purchases, you can start building them as purchasable items into your app.

The following SDK methods can be called from your client app.

• Retrieve the user's purchased items:

  Native - ovr_IAP_GetViewerPurchases()

  Unity - Platform.IAP.GetViewerPurchases()

  Review the ovr_IAP_GetViewerPurchases page for information about the parameters and return data structure.

• Retrieve a list of available items and prices by SKU:

  Native - ovr_IAP_GetProductsBySKU()

  Unity - Platform.IAP.GetProductsBySKU()

  Review the ovr_IAP_GetProductsBySKU page for information about the parameters and return data structure.

• Launch the checkout flow for a SKU (Purchase an item):

  Native - ovr_IAP_LaunchCheckoutFlow()

  Unity - Platform.IAP.LaunchCheckoutFlow()

  Review the ovr_IAP_LaunchCheckoutFlow page for information about the parameters and return data structure.

• Consume a purchased item:

  Native - ovr_IAP_ConsumePurchase()

  Unity - Platform.IAP.ConsumePurchase()

  Review the ovr_IAP_ConsumePurchase page for information about the parameters and return data structure.

Example Implementation

The following Unity example demonstrates the end-to-end flow of retrieving information for an IAP item, displaying that information to the user, consuming any outstanding purchases, and initiating the checkout flow when a user indicates that they would like to make a purchase. The following example is taken from the VRBoardGame sample app. Please see the Sample Apps page for more information about the apps that are available.

using UnityEngine;
using Oculus.Platform;
using Oculus.Platform.Models;
using UnityEngine.UI;


// This class coordinates In-App-Purchases (IAP) for the application.  Follow the
// instructions in the Readme for setting up IAP on the Oculus Dashboard.  Only
// one consumable IAP item is used is the demo: the Power-Ball!
public class IAPManager : MonoBehaviour
{
    // the game controller to notify when the user purchase more powerballs
    [SerializeField] private GameController m_gameController;

    // where to record to display the current price for the IAP item
    [SerializeField] private Text m_priceText;

    // purchasable IAP products we've configured on the Oculus Dashboard
    private const string CONSUMABLE_1 = "PowerballPack1";

    void Start()
    {
        FetchProductPrices();
        FetchPurchasedProducts();
    }

    // get the current price for the configured IAP item
    public void FetchProductPrices()
    {
        string[] skus = { CONSUMABLE_1 };
        IAP.GetProductsBySKU(skus).OnComplete(GetProductsBySKUCallback);
    }

    void GetProductsBySKUCallback(Message<ProductList> msg)
    {
        if (msg.IsError)
        {
            PlatformManager.TerminateWithError(msg);
            return;
        }

        foreach (Product p in msg.GetProductList())
        {
            Debug.LogFormat("Product: sku:{0} name:{1} price:{2}", p.Sku, p.Name, p.FormattedPrice);
            if (p.Sku == CONSUMABLE_1)
            {
                m_priceText.text = p.FormattedPrice;
            }
        }
    }

    // fetches the Durable purchased IAP items.  should return none unless you are expanding the
    // to sample to include them.
    public void FetchPurchasedProducts()
    {
        IAP.GetViewerPurchases().OnComplete(GetViewerPurchasesCallback);
    }

    void GetViewerPurchasesCallback(Message<PurchaseList> msg)
    {
        if (msg.IsError)
        {
            PlatformManager.TerminateWithError(msg);
            return;
        }

        foreach (Purchase p in msg.GetPurchaseList())
        {
            Debug.LogFormat("Purchased: sku:{0} granttime:{1} id:{2}", p.Sku, p.GrantTime, p.ID);
        }
    }

    public void BuyPowerBallsPressed()
    {
#if UNITY_EDITOR
        m_gameController.AddPowerballs(1);
#else
        IAP.LaunchCheckoutFlow(CONSUMABLE_1).OnComplete(LaunchCheckoutFlowCallback);
#endif
    }

    private void LaunchCheckoutFlowCallback(Message<Purchase> msg)
    {
        if (msg.IsError)
        {
            PlatformManager.TerminateWithError(msg);
            return;
        }

        Purchase p = msg.GetPurchase();
        Debug.Log("purchased " + p.Sku);
        m_gameController.AddPowerballs(3);
    }
} 

S2S REST Requests

Certain actions require to you to interact directly with our server. See the Server-to-Server API Basics page for information about interacting with our APIs.

Verify Item Ownership

Verify that a user owns an item.

Example Request

$ curl -d "access_token=$USER_ACCESSTOKEN" -d "user_id=$USERID"
        https://graph.oculus.com/$APPID/verify_entitlement

Example Response

{"success":true}

Consume an IAP Item

Consume an IAP item that a user has purchased.

Example Request

$ curl -d "access_token=$USER_ACCESSTOKEN" -d "sku=$SKU"
        https://graph.oculus.com/$APPID/consume_entitlement

Example Response

{"success":true}

Retrieve Items Owned

Retrieve a list of items that the user owns.

Example Request

$ curl -G -d "access_token=$USER_ACCESSTOKEN" -d "sku=$SKU" -d 'fields'='item{skus},id'
        https://graph.oculus.com/$APPID/viewer_purchases

Example Response

{
  "data": [
    {
      "id": "963119010431337",
      "item": {
        "sku": "EXAMPLE1"
      }
    }
  ]
}

Test IAP

You can test your IAP integration by creating test users for your organization. These test users have permission to purchase IAP items in your app, including the Alpha, Beta, and Release Candidate apps, without using actual money. These users will work with all applications in your organization and can be deleted at any time.

Create a test user by navigating to your Org's publishing page on the Developer Center and selecting the 'Test Users' tab. On this page select ‘+ Add Test User’ and enter a password and pin on the modal that opens. Click ‘Submit’ to create the user. This user will be assigned the name of the person who’s account created the test user, a random Oculus Id, and an email address based on the account creators email address. This user inherits permissions to all apps and channels for the Org that you created the user in.

Once the test user has been created, log in to that account and add a payment method for the user. Since this user will be testing the IAP checkout flow, add the following credit card numbers to test different IAP flows.

• Always succeeds - 4111 1177 1155 2927
• Fails at authorization - 4111 1180 9636 6644
• Fails at sale - 4111 1193 1540 5122

These cards only work with test users and can only be used within your organization. When using these cards, you can enter any valid address and expiration date.