> For the complete documentation index, see [llms.txt](https://onestore-dev.gitbook.io/dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk/iap.md).

# 05. In App Purchase (IAP)

### **Prerequisites**

#### Register In-App Products

You must register **managed products** under the "App Monetization > In-App Products" menu in ONEconsole. Only managed products are supported for Web products; subscription products are not supported. See [02. Pre-Preparations](https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk/pre.md) for details.

#### Check Feature Availability: isSupported

Request purchases and product details through the `iap` module of the SDK object obtained from `createSDK()`. Feature availability can be checked with `sdk.iap.isSupported(feature)`. **Check it before showing the purchase UI or shop prices.**

<table><thead><tr><th width="320">Call</th><th width="100">Returns</th><th>Meaning</th></tr></thead><tbody><tr><td><code>sdk.iap.isSupported()</code></td><td>boolean</td><td>Whether payment is supported (same as <code>"purchase"</code>)</td></tr><tr><td><code>sdk.iap.isSupported("purchase")</code></td><td>boolean</td><td>Whether payment is supported</td></tr><tr><td><code>sdk.iap.isSupported("getProductDetails")</code></td><td>boolean</td><td>Whether product details lookup is supported (see 'Product Details' below)</td></tr></tbody></table>

```javascript
// Check after initializeAsync(), and show the purchase UI only if supported
if (sdk.iap.isSupported("purchase")) {
  showPurchaseButton();
}
```

* The result is determined from the initialization response, so call it **after** `initializeAsync()`. Before that, it may optimistically return true.
* Payment and product details lookup may be supported **independently** depending on the app version. `isSupported()` without an argument refers to payment only, so always check with `isSupported("getProductDetails")` before looking up product details.

### **Requesting a Purchase: purchase**

A purchase is requested with a single call to `purchase()`. On success, a result object is returned. **User cancellation, payment failure, and request rejection are all delivered as errors** (see the purchase and product details errors in [06. Error Reasons (reason)](https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk/errors.md)). The response may be delayed until the payment is finished.

#### Purchase Example

```javascript
var sdk = createSDK();
// ... omitted ...

var param = {
  productId: "gem10000+10",
  productName: "1000 Gems + 10 Bonus",
  developerPayload: "{{Optional: information to use when granting the item}}"
};

sdk.iap.purchase(param).then(
  function (result) {
    console.info("Purchase succeeded");
    console.info("Order ID (receipt): ", result.orderId);
    console.info("Purchase time (epoch millis): ", result.purchaseTimeMillis);
    console.info("Purchase ID: ", result.purchaseId);
    console.info("Purchase token: ", result.purchaseToken);
    console.info("Requested in-app product ID: ", result.productId);
    console.info("developerPayload: ", result.developerPayload);

    // TODO: verify and grant the item
  },
  function (error) {
    console.error("Purchase error >", error.reason);
  }
);
```

#### Purchase Request Parameters

The `param` of `sdk.iap.purchase(param)` is a JSON object.

<table><thead><tr><th width="170">Parameter</th><th width="90">Type</th><th width="100">Required</th><th>Description</th></tr></thead><tbody><tr><td>productId</td><td>String</td><td>Required</td><td>ID of the in-app product to purchase (the custom PID registered by the developer in the Developer Center)</td></tr><tr><td>productName</td><td>String</td><td>Optional</td><td>Name of the in-app product to purchase (if omitted, the product name registered in the Developer Center is shown)</td></tr><tr><td>developerPayload</td><td>String</td><td>Optional</td><td>Developer-defined string used to identify the purchase when the result is received by the game or notified via <a href="https://onestore-dev.gitbook.io/dev/eng/tools/billing/v21/pns">PNS</a> (up to 200 bytes)</td></tr></tbody></table>

#### Purchase Response

<table><thead><tr><th width="190">Key</th><th width="90">Type</th><th>Description</th></tr></thead><tbody><tr><td>orderId</td><td>String</td><td>Order ID (receipt information)</td></tr><tr><td>purchaseTimeMillis</td><td>Number</td><td>Purchase time (epoch millis)</td></tr><tr><td>purchaseId</td><td>String</td><td>Purchase ID</td></tr><tr><td>purchaseToken</td><td>String</td><td>Purchase token</td></tr><tr><td>productId</td><td>String</td><td>ID of the in-app product that was requested</td></tr><tr><td>developerPayload</td><td>String</td><td>Identifier managed by the developer to identify the purchase (the developerPayload passed in the request)</td></tr></tbody></table>

{% hint style="danger" %}
**Grant Confirmation Principles**

* The success response of `purchase()` is **only a payment-completed signal, not grounds for granting the item.** Confirm the grant after the game server verifies the payment with `purchaseToken`.
* Payment completion is notified to the game server via [PNS](https://onestore-dev.gitbook.io/dev/eng/tools/billing/v21/pns). PNS is delivered even when the game client did not receive the response (network loss, forced app termination, etc.), so build the granting process around the server to avoid losses.
* Consumption (consume) is also the game server's responsibility. The app does not consume automatically after payment, so **purchasing an unconsumed product again fails with `already_owned`.** See the [ONE store IAP Server API](https://onestore-dev.gitbook.io/dev/eng/tools/billing/v21/serverapi) for the related APIs.
* `developerPayload` is the identifier that links an order to a user. To match the purchase when the PNS is received, pass it in the request and map it on your server.
  {% endhint %}

### **Product Details: getProductDetailsAsync**

Use this to display prices in the in-game shop. Pass a list of in-app product IDs registered in the Developer Center, and the product names and prices are returned. It does not open a payment screen, so it can be called even while an ad or payment is being displayed.

Before calling, check availability with `sdk.iap.isSupported("getProductDetails")`. It returns `false` in a browser environment or on an older app version. In that case, do not call the API and handle it in the game instead, for example by continuing without price display.

#### Product Details Example

```javascript
if (sdk.iap.isSupported("getProductDetails")) {
  sdk.iap.getProductDetailsAsync(["ruby_100", "ruby_500"])
    .then(function (products) {
      // products: [{ productId, type, title, price, priceAmountMicros, priceCurrencyCode }, ...]
      products.forEach(function (p) {
        showPrice(p.productId, p.price, p.priceCurrencyCode);
      });
    })
    .catch(function (e) {
      console.warn("Product details lookup failed", e.reason, e.message);   // see Error Reasons
    });
}
```

#### Request Parameters

<table><thead><tr><th width="130">Parameter</th><th width="90">Type</th><th width="90">Required</th><th>Description</th></tr></thead><tbody><tr><td>productIds</td><td>string[]</td><td>Required</td><td>List of in-app product IDs to look up. Same value as <code>productId</code> in <code>purchase()</code>. <strong>Up to 20 per call.</strong> Exceeding the limit, an empty array, an array containing an empty string, or a non-array value fails with <code>invalid_request</code> without calling the app. For 21 or more, split into calls of 20</td></tr></tbody></table>

#### Response: Array of Product Objects

One product = one object. Only products on sale are included; if there are none, an empty array is returned.

<table><thead><tr><th width="190">Field</th><th width="90">Type</th><th>Description</th></tr></thead><tbody><tr><td>productId</td><td>string</td><td>In-app product ID. The value sent in the request</td></tr><tr><td>type</td><td>string</td><td>Product type. Always <code>"inapp"</code></td></tr><tr><td>title</td><td>string</td><td>Product name (as registered in the Developer Center)</td></tr><tr><td>price</td><td>string</td><td>Price string (e.g. <code>"1000"</code>). It may not include a currency symbol or digit grouping, so display it together with <code>priceCurrencyCode</code></td></tr><tr><td>priceAmountMicros</td><td>number</td><td>Price × 1,000,000. Use for amount calculation, comparison, and sorting</td></tr><tr><td>priceCurrencyCode</td><td>string</td><td>Currency code (e.g. <code>"KRW"</code>)</td></tr></tbody></table>

{% hint style="warning" %}
**Result Handling Principles**

* **An empty array is not an error.** Even if none of the requested products are found, a normal response (an empty array) is returned. Do not handle an empty array and an error in the same branch.
* **Only some products may be returned.** Products that are discontinued or unregistered are omitted from the result, and this is not an error. **The result order may not match the request order.** Match by `productId`.
* Use `price` for display and **`priceAmountMicros` for amount calculation and sorting**. `price` is a string and must not be used in arithmetic.
* Failures are delivered as Promise rejects (see [06. Error Reasons (reason)](https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk/errors.md)). If there is no response within 10 seconds, `reason` is `"timeout"`.
  {% endhint %}
