IAP.createOneTimePurchaseOrder

Feature description

We're moving to the single-item in-app purchase order page. The payment and product grant flow is options / onEvent / onError handled with event-style options.

• options.sku: This is the ID of the product to order. (productIdis deprecated)
• options.processProductGrant: Called when granting the product after the order is created. Returns whether the grant succeeded true/false(or a Promise).
• onEvent: When payment succeeds, type: 'success'is called with the result data.
• onError: Called if an error occurs during payment.

The returned cleanup function must be called when the in-app purchase feature is finished to release resources.

Toss app Android/iOS 5.219.0 It can be used on versions above. If called in an unsupported version, UNSUPPORTED_APP_VERSION an error occurs.

Type

IAP.createOneTimePurchaseOrder(params: IapCreateOneTimePurchaseOrderOptions): () => void;

Params

interface IapCreateOneTimePurchaseOrderOptions {
  options: {
    sku: string;
    /** @deprecated Use sku */
    productId?: string;
    processProductGrant: (params: {
      orderId: string;
    }) => boolean | Promise<boolean>;
  };
  onEvent: (event: {
    type: "success";
    data: IapCreateOneTimePurchaseOrderResult;
  }) => void | Promise<void>;
  onError: (error: unknown) => void | Promise<void>;
}

interface IapCreateOneTimePurchaseOrderResult {
  orderId: string;
  displayName: string;
  displayAmount: string;
  amount: number;
  currency: string;
  fraction: number;
  miniAppIconUrl: string | null;
}

Response

Returns a cleanup function to release resources when the payment flow ends (() => void).

Error

Error codes are onErrorcan be received as, or wrapped around the try/catcherrors caught in error.code value.

Code	Description
INVALID_PRODUCT_ID	This is when the product ID is invalid or the product does not exist.
PAYMENT_PENDING	This is when payment is still awaiting approval.
NETWORK_ERROR	This is when the request cannot be processed due to network/server issues.
INVALID_USER_ENVIRONMENT	This is when the product cannot be purchased on a specific device, account, or setting.
ITEM_ALREADY_OWNED	This is when you try to purchase a product you already bought.
APP_MARKET_VERIFICATION_FAILED	This is when payment succeeded but app store verification failed.
TOSS_SERVER_VERIFICATION_FAILED	This is when payment succeeded but sending to or saving on the server failed.
INTERNAL_ERROR	This is when the request cannot be processed due to an internal server issue.
KOREAN_ACCOUNT_ONLY	This is when the account is not a Korean account on iOS.
USER_CANCELED	This is when the user leaves the order page.
PRODUCT_NOT_GRANTED_BY_PARTNER	This is when the partner's product grant failed.
UNSUPPORTED_APP_VERSION	If the running version of the Toss app doesn't support this feature, it occurs immediately upon call. IAP.createOneTimePurchaseOrder.isSupported()Check in advance with error.messageand, if it occurs, show the user the (update guidance message).

Example code

import { IAP } from "@apps-in-toss/web-framework";

const button = document.querySelector("#buy-button");
let cleanup;

button.addEventListener("click", () => {
  try {
    cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku: "coin_100",
        processProductGrant: ({ orderId }) => {
          // Write the product grant logic
          console.log("Grant processed:", orderId);
          return true;
        },
      },
      onEvent: (event) => {
        console.log(event.type, event.data);
      },
      onError: (error) => {
        console.error(error);
      },
    });
  } catch (error) {
    console.error(error);
  }
});

// cleanup?.() when leaving the screen