In-App Purchases for Instant Games

Instant Games In-App Purchases (IAP) provide a way for developers to leverage micro-transactions in their Instant Games on Facebook.com. Developers will be able to immediately test IAP in their games. Once a game has passed through In App Purchase review, players will be able to make purchases on Android and Facebook.com.

In-App Purchases are supported on web, iOS and Android.

Getting Started

The first step of enabling In App Purchases is to configure the products that you would like to make available to players and configure payout information. This can be done on the In App Purchase tab under the Instant Games product.

Select or create a company that will the designated recipient of payouts from Instant Games in-app purchases. You can find more information here.

Integrating In-App Purchase

Best Practices

The following is the expected flow per game session:

• Check whether payments is available for the session; see section below for more details.
• As a best practice, to ensure proper handling of consumables in the event of a crash during the IAP flow, call getPurchasesAsync() to obtain a list of unconsumed purchases. Then call consumePurchase(<purchase_token>) on any consumables, awarding the user the corresponding in-game item or virtual currency.
• Call getCatalogAsync() to obtain the list of products to display to the user. Use this data to dynamically populate the store UI.
• If the user interacts with the UI to make a purchase, using the productID of the item from the catalog, call purchaseAsync(<purchase_config>).
• At this point, you can optionally send the signedRequest to your servers to fully verify the purchase.
• If the item is a consumable, consume the purchase via consumePurchase(<purchase_token>), passing in the purchaseToken, and award the user the corresponding in-game item or virtual currency.

Detecting whether payments is available

Payments in Instant Games are only supported on Facebook.com (not Messenger.com) and on Android once you have passed review. Your code should ensure that payments are available on the player's device before showing any payments functionality.

As with other Instant Games APIs, use getSupportedAPIs and look for payments.purchaseAsync.

If available, subscribe to payments.onReady with a callback as follows.

FBInstant.payments.onReady(function () {
  console.log('Payments Ready!');
});

If getSupportedAPIs does not contain payments.purchaseAsync, then payments is not supported on the device.

If the callback set in payments.onReady is never called, payments is also not supported for this session and no payment related functionality should be used.

Rendering the store

Use the getCatalogAsync method to get the list of available products. Make sure to use the proper local currency (priceCurrencyCode) and price (price) for each product when displaying your store.

FBInstant.payments.getCatalogAsync().then(function (catalog) {
  console.log(catalog); // [{productID: '12345', ...}, ...]
});

Handling a purchase

When a player shows intent to purchase an item, you can trigger the purchase confirmation dialog using purchaseAsync.

FBInstant.payments.purchaseAsync({
  productID: '12345',
  developerPayload: 'foobar',
}).then(function (purchase) {
  console.log(purchase);
  // {productID: '12345', purchaseToken: '54321', developerPayload: 'foobar', ...}
});

Verifying a Purchase

It is possible to verify that a payment has occurred on a backend system by parsing the signedRequest value that is returned with the payment object.

The signedRequest consists of two parts separated by the . character. The first part is a Base64 encoded SHA256 hash of the payment information, while the second part is the same payment information encoded directly in Base64.

You can validate that the payment information is authentic by using the following code samples:

Javascript sample:

import hmacSHA256 from "crypto-js/hmac-sha256";
import Base64 from "crypto-js/enc-base64";
import utf8 from "crypto-js/enc-utf8";
import JSONbig from "json-bigint";

const signedRequest = "<SIGNED_REQUEST>";
const firstPart = signedRequest.split(".")[0].replace(/-/g, "+").replace(/_/g, "/");
const secondPart = signedRequest.split(".")[1];

const signature = Base64.parse(firstPart).toString();
const dataHash = hmacSHA256(secondPart, "<APP_SECRET>").toString();

const isValid = signature === dataHash;
const json = Base64.parse(secondPart).toString(utf8);
/*
  NOTE: The purchase_token field will exceed the bounds of Number.MAX_SAFE_INTEGER, 
  so JSON.parse(...) is unsafe. This will be changed soon, but until then,
  please avoid using. Alternatively, pass the string directly from the 
  purchase API response instead.
*/
const data = JSONbig({ storeAsString: true }).parse(json);

console.log(isValid); // this will be true if the payment is verified as coming from the game
console.log(data); // a JSON object as follows:

/*
{
  algorithm: "HMAC-SHA256"
  app_id: 772899436149321
  is_consumed: false
  issued_at: 1628530124
  payment_action_type: "charge"
  payment_id: 2373285299469015
  product_id: "sample_product"
  purchase_price: Object // {"amount":"0.01", "currency":"USD"},
  purchase_time: 1628171348
  purchase_token: 10102867843382867
}
*/

/*
Starting 8/25/21:
{
  algorithm: "HMAC-SHA256"
  app_id: "772899436149321"
  is_consumed: false
  issued_at: 1628530124
  payment_action_type: "charge"
  payment_id: "2373285299469015"
  product_id: "sample_product"
  purchase_price: Object // {"amount":"0.01", "currency":"USD"},
  purchase_time: 1628171348
  purchase_token: "10102867843382867"
}
*/

Java sample:

import java.util.Base64;
import java.util.Arrays;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

...

String signedRequest = "<SIGNED_REQUEST>";

String[] parts = signedRequest.split("\\.",2);
String firstPart = parts[0].trim().replaceAll("-","+").replaceAll("_","/");
String secondPart = parts[1];

Base64.Decoder decoder = Base64.getDecoder();
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");

// Handle first part of signed request
byte[] signature = decoder.decode(firstPart);

// Handle second part of signed request
SecretKeySpec secret_key = new SecretKeySpec("<APP_SECRET>".getBytes(), "HmacSHA256");
sha256_HMAC.init(secret_key);
byte[] datahash = sha256_HMAC.doFinal(secondPart.getBytes());

// SignedRequest is valid if both matches
boolean isValid = Arrays.equals(signature, datahash);

Getting a player's purchased items

Use getPurchasesAsync to get the player's unconsumed purchases.

FBInstant.payments.getPurchasesAsync().then(function (purchases) {
  console.log(purchases); // [{productID: '12345', ...}, ...]
});

Consuming a purchased item

When a player decides to use a purchased item, call consumePurchaseAsync and award the effect of the item. Once called, the item will no longer be returned by getPurchasesAsync. Until this is done, the player will be unable to purchase the same item in the future.

If the item is a non-consumable product, don't call consumePurchaseAsync. This purchase will always be listed in getPurchasesAsync.

FBInstant.payments.consumePurchaseAsync('54321').then(function () {
  // Purchase successfully consumed!
  // Game should now provision the product to the player
}).catch(function(error) {
  // Handle error
});

Bulk Product Creation

To create multiple consumable products in a single operation, go to the In-App Purchase Products pane, select Add multiple products and then choose one of the following creation methods:

• Add Products Manually
• Upload a CSV File

Add Products Manually

To manually create multiple consumable products, select Add multiple products and then select Add manually. Each row in the Add products form represents a single consumable product.

For each consumable product, provide the following information (hover over the form header for additional guidance):

• Product image: Optional. 50×50 JPG, PNG, or GIF file.
• Product ID: Required. Unique identifier of the product. This ID can contain only lowercase letters, numbers, underscores, and periods.
• Title: Required. The title of the product.
• Description: Required. A short description of the product.
• Price: Required. Price of the product in U.S. dollars. This price will be automatically converted to the user's local currency during checkout.

Upload a CSV File

To create multiple consumable products from a CSV file, select Add multiple products and then select Upload file. This method supports the creation of 750 products per operation; to add a greater number of products, split the CSV file into multiple batches.

• If your app is also listed in the Google Play store, this CSV file is the catalog exported from your Google Play Console.
• If your app uses Price Templates, manually input the price of each item in U.S. dollars as a single float (without the currency symbol) in the empty Price column.
• Otherwise, manually create a CSV with the required information.

For each consumable product, provide the following information:

• Product ID: Unique identifier of the product. This ID can contain only lowercase letters, numbers, underscores, and periods.
• Locale: Must be "en_US".
• Title: The title of the product.
• Description: A short description of the product.
• Price: Price of the product in U.S. dollars. This price will be automatically converted to the user's local currency during checkout.

The following table provides an example of a CSV file for the creation of three consumable products.

When upload of the CSV file is complete you will see the Product preview form. Confirm that the imported information is correct; you can also edit fields and fix any errors in this form before completing the product creation.

Testing Transactions

Users added to the Testers section of the Set Up pane on the In App Purchase tab will not be charged for items in your game. This can be used to test purchase functionality without performing real transactions.

For Facebook Pay, please use one of the following test credit cards.

The FB Pay checkout dialog should look like the following:

Sending for Review

Before In App Purchases will work across all platforms, there are several checks that must be made.

The app must pass a functional In App Purchase review. Instant Games can be submitted for In App Purchases on the Review tab.

On the In App Purchase tab, statuses are shown to help you determine which of these activities need to be completed.

Analytics

In the In App Purchase tab, please follow the link to directly see the purchase metrics in FBS Insights.

Purchases will also be automatically logged in Events Manager.

Payout

Our primary goal is to build IAP in a way so that our developer partners can sustain and grow: for purchases made on web (Facebook.com), the revenue share model is 70% for developers - as it has been historically for games on the Facebook platform.

On mobile, Instant Games follow in-app billing terms from each platform. For purchases made in games on Google Play, developers will retain the full amount after the standard mobile platform revenue share. This means developers take home $0.70 of every dollar earned with $0.30 fee to Google.

Payout should be received in 30 day windows.

Update your Payout Information

If you have received a message from Meta asking you for additional information about your developer account, it’s because the info we have is out of date or inaccurate. Meta Payments is a regulated financial services company and, accordingly, must follow various state and federal financial services laws. These laws require us to make sure that all the info we have about any developer account with access to Meta's Developer tools is current and accurate. We’ll only use this info to verify your organization.

Failure to respond to an outstanding inquiry for greater than 60 days will result in your organization’s ability to monetize through in-app purchases on Meta’s Developer platform being suspended.

All messages related to this enforcement track can be viewed in the personal Facebook support inbox of any Financial Entity Admin.

The Financial Admin is the admin responsible for maintaining and monitoring the financial entity of their organization. This is usually the individual or individuals who initially configured the payout information associated with your application on the Meta for Developers platform.

If your organization’s monetization has been suspended due to a payout information inquiry and you believe this was done in error, or you wish to appeal, please contact us directly using the Payouts --> Getting Help section in our developers Help Center