# "Instant Games SDK v8.0: FBInstant.payments"


See [Instant Games SDK v8.0](https://developers.facebook.com/documentation/games/sdk-reference/v8.0) for the SDK overview, changelog, and root `FBInstant` reference.

## FBInstant.payments



### getCatalogAsync()

Fetches the game's product catalog.

**Returns:** `Promise<Array<`[`Product`](#product)`>>` — The set of products that are registered to the game.

**Throws:**

- `CLIENT_UNSUPPORTED_OPERATION`
- `PAYMENTS_NOT_INITIALIZED`
- `NETWORK_FAILURE`

**Example:**

```javascript
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` | [`PurchaseConfig`](#purchaseconfig) | The purchase's configuration details. |

**Returns:** `Promise<`[`Purchase`](#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:**

```javascript
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`](#purchase)`>>` — The set of purchases that the player has made for the game.

**Throws:**

- `CLIENT_UNSUPPORTED_OPERATION`
- `PAYMENTS_NOT_INITIALIZED`
- `NETWORK_FAILURE`

**Example:**

```javascript
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.

**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_OPERATION`
- `PAYMENTS_NOT_INITIALIZED`
- `INVALID_PARAM`
- `NETWORK_FAILURE`

**Example:**

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

---

### 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:** `void`

**Example:**

```javascript
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:

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:**

| 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. |

---