Instant Games

Instant Games SDK v8.0: FBInstant.payments

Updated: May 5, 2026
Copy for LLM
For more information about In-App Purchases, please see the In-App Purchase documentation
See Instant Games SDK v8.0 for the SDK overview, changelog, and root FBInstant reference.

FBInstant.payments

getCatalogAsync()

Fetches the game’s product catalog.
Returns:Promise<Array<Product>> — The set of products that are registered to the game.
Throws:
  • CLIENT_UNSUPPORTED_OPERATION
  • PAYMENTS_NOT_INITIALIZED
  • NETWORK_FAILURE
Example:
FBInstant.payments.getCatalogAsync().then(function (catalog) {
  console.log(catalog); // [{productID: '12345', ...}, ...]
});

purchaseAsync()

Begins the purchase flow for a specific product. Will immediately reject if called before FBInstant.startGameAsync() has resolved.
Parameters:
ParameterTypeDescription
purchaseConfig
The purchase’s configuration details.
Returns:Promise<Purchase> — A Promise that resolves when the product is successfully purchased by the player. Otherwise, it rejects.
Throws:
  • CLIENT_UNSUPPORTED_OPERATION
  • PAYMENTS_NOT_INITIALIZED
  • INVALID_PARAM
  • NETWORK_FAILURE
  • INVALID_OPERATION
  • USER_INPUT
Example:
FBInstant.payments.purchaseAsync({
  productID: '12345',
  developerPayload: 'foobar',
}).then(function (purchase) {
  console.log(purchase);
  // {productID: '12345', purchaseToken: '54321', developerPayload: 'foobar', ...}
});

getPurchasesAsync()

Fetches all of the player’s unconsumed purchases. The game must fetch the current player’s purchases as soon as the client indicates that it is ready to perform payments-related operations, i.e. at game start. The game can then process and consume any purchases that are waiting to be consumed.
Returns:Promise<Array<Purchase>> — The set of purchases that the player has made for the game.
Throws:
  • CLIENT_UNSUPPORTED_OPERATION
  • PAYMENTS_NOT_INITIALIZED
  • NETWORK_FAILURE
Example:
FBInstant.payments.getPurchasesAsync().then(function (purchases) {
  console.log(purchase);
  // [{productID: '12345', ...}, ...]
});

consumePurchaseAsync()

Consumes a specific purchase belonging to the current player. Before provisioning a product’s effects to the player, the game should request the consumption of the purchased product.
Once the purchase is successfully consumed, the game should immediately provide the player with the effects of their purchase.
Note: For consumable products, you must call consumePurchaseAsync after verifying and delivering the product:
Parameters:
ParameterTypeDescription
purchaseToken
string
The purchase token of the purchase that should be consumed.
Returns:Promise<void> — A Promise that resolves when the purchase has been consumed successfully.
Throws:
  • CLIENT_UNSUPPORTED_OPERATION
  • PAYMENTS_NOT_INITIALIZED
  • INVALID_PARAM
  • NETWORK_FAILURE
Example:
FBInstant.payments.consumePurchaseAsync(purchaseToken).then(function () {
  console.log('Purchase consumed. Player can now buy this product again.');
}).catch(function (error) {
  console.error('Failed to consume purchase:', error);
});

onReady()

Sets a callback to be triggered when Payments operations are available.
Parameters:
ParameterTypeDescription
callback
Function
The callback function to be executed when Payments are available.
Returns:void
Example:
FBInstant.payments.onReady(function () {
  console.log('Payments Ready!')
});

Types

Product

Represents a game’s product information.
Properties:
PropertyTypeDescription
title
string
The title of the product
productID
string
The product’s game-specified identifier
description
string(optional)
The product description
imageURI
string(optional)
A link to the product’s associated image
price
string
The price of the product
priceCurrencyCode
string
The currency code for the product
priceAmount
number
The numeric price of a product

Purchase

Represents an individual purchase of a game product.
Properties:
PropertyTypeDescription
developerPayload
string(optional)
A developer-specified string, provided during the purchase of the product
isConsumed
boolean
Whether or not the purchase has been consumed
paymentActionType
string
The current status of the purchase, such as ‘charge’ or ‘refund’
paymentID
string
The identifier for the purchase transaction
productID
string
The product’s game-specified identifier
purchasePlatform
PurchasePlatform
The platform associated with the purchase, such as “FB” for Facebook and “GOOGLE” for Google.
purchasePrice
Object
Contains the local amount and currency associated with the purchased item
purchaseTime
string
Unix timestamp of when the purchase occurred
purchaseToken
string
A token representing the purchase that may be used to consume the purchase
signedRequest
SignedPurchaseRequest
Server-signed encoding of the purchase request

SignedPurchaseRequest

A signature to verify this object indeed comes from Facebook. The string is base64url encoded and signed with an HMAC version of your App Secret, based on the OAuth 2.0 spec.
You can validate it with the following 5 steps:
  1. Split the signature into two parts delimited by the ‘.’ character.
  2. Decode the first part (the encoded signature) with base64url encoding.
  3. Decode the second part (the response payload) with base64url encoding, which should be a string representation of a JSON object that has the following fields: algorithm - always equals to HMAC-SHA256 issued_at - a unix timestamp of when this response was issued app_id - The game’s application ID is_consumed - Whether the purchase has been consumed by the player. payment_action_type - The current status of the purchase payment_id - The identifier for the purchase transaction product_id - The product’s game-specified identifier purchase_price - Contains the local amount and currency associated with the purchased item purchase_token - A token representing the purchase that may be used to consume the purchase purchase_time - Unix timestamp of when the purchase occurred developer_payload - A developer-specified string, provided during the purchase of the product
  4. Hash the whole response payload string using HMAC SHA-256 and your app secret and confirm that it is equal to the encoded signature.
  5. You may also wish to validate the issued_at timestamp in the response payload to ensure the request was made recently.
Signature validation should only happen on your server. Never do it on the client side as it will compromise your app secret key.

PurchaseConfig

The configuration of a purchase request for a product registered to the game.
Properties:
PropertyTypeDescription
productID
string
The identifier of the product to purchase
developerPayload
string(optional)
An optional developer-specified payload, to be included in the returned purchase’s signed request.