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.
Throws:
CLIENT_UNSUPPORTED_OPERATIONPAYMENTS_NOT_INITIALIZEDNETWORK_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:
| Parameter | Type | Description |
|---|---|---|
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_OPERATIONPAYMENTS_NOT_INITIALIZEDINVALID_PARAMNETWORK_FAILUREINVALID_OPERATIONUSER_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.
Throws:
CLIENT_UNSUPPORTED_OPERATIONPAYMENTS_NOT_INITIALIZEDNETWORK_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:
| Parameter | Type | Description |
|---|---|---|
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_OPERATIONPAYMENTS_NOT_INITIALIZEDINVALID_PARAMNETWORK_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:
| Parameter | Type | Description |
|---|---|---|
callback | Function | The callback function to be executed when Payments are available. |
Returns:
voidExample:
FBInstant.payments.onReady(function () { console.log('Payments Ready!') });
Types
Product
Represents a game’s product information.
Properties:
| Property | Type | Description |
|---|---|---|
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:
| Property | Type | Description |
|---|---|---|
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:
- Split the signature into two parts delimited by the ‘.’ character.
- Decode the first part (the encoded signature) with base64url encoding.
- 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
- Hash the whole response payload string using HMAC SHA-256 and your app secret and confirm that it is equal to the encoded signature.
- 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:
| Property | Type | Description |
|---|---|---|
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. |