[Early Access] Getting Started with In-App Purchases

Instant Games In-App Purchases (IAP) provides a way for developers to to leverage micro-transactions in their Instant Games on Facebook.com and Messenger for Android. While currently in closed beta, you can start integrating IAP into your games today.

Getting Started

In order to enable your Instant Game for IAP, you must initially test on web (Android support is coming soon, but uses the same APIs).

The first step of enabling In App Purchases is to add the Web Payments product to your game and configure the products that you would like to make available to players.

Add the “Web Payments” 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.

You should also toggle the Payments Lite setting to 'yes'.

Although Instant Games uses Facebook Web Payments to configure products, the following Facebook Web Payments features are not yet supported:

Test Transactions: currently all payments for Facebook Instant Games must be made with real money, which is subject to the Facebook revenue share for web payments. We plan to roll out test payments in coming weeks.

Game Cards: game cards cannot be used with Instant Games.

Pricing Callback URLs and server side payments: Instant Games payment products must be declared in the payments interface and do not support server side features such as dynamic pricing.

Webhooks: Instant Games payments do not support webhooks. Currently no server-side validation mechanism for payments is available.

Graph API: Graph API access to products is not support for Instant Games. All interactions with Instant Games products should be handled through the Instant Games SDK.

Analytics: Instant Games does not support out of the box analytics for payments. If you would like to track transactions, you should log events in Facebook Analytics manually us FBInstant.logEvent. Note that that as these calls are client side they may not provide accurate information on expected payout.

Configuring Products

Configure your products using the product configuration interface, as follows:

On the product tab, you will see a list of all the products associated with your game, along with the option to create a new product.
Specify the data associated with this product, such as the name and price.

Integrating on Web

Detecting whether payments is available

Payments in Instant Games are only supported on Facebook.com (not Messenger.com) and on Android for whitelisted developers. 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 product information.

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({</p>
  productID: '12345',</p>
  developerPayload: 'foobar',</p>
}).then(function (purchase) {</p>
  console.log(purchase);</p>
  // {productID: '12345', purchaseToken: '54321', developerPayload: 'foobar', ...}
});

Getting a player's purchased items

Use getPurchasesAsync to get the player's unconsumed purchases.

FBInstant.payments.getPurchasesAsync().then(function (purchases) {
  console.log(purchase); // [{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.

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

Integrating on Android

In App Purchases for Instant Games on Android is in closed beta. Stay up to date on the Instant Game Developer Community. If you have completed and tested your integration on web, the same implementation will work on Android once available.