IAP.createOneTimePurchaseOrder

기능 설명

단건 인앱결제 주문서 페이지로 이동해요. 결제·상품 지급 흐름은 options / onEvent / onError 이벤트 스타일 옵션으로 처리해요.

• options.sku: 주문할 상품 ID예요. (productId는 deprecated)
• options.processProductGrant: 주문이 만들어진 뒤 상품을 지급할 때 호출해요. 지급 성공 여부를 true/false(또는 Promise)로 반환해요.
• onEvent: 결제 성공 시 type: 'success'와 결과 데이터로 호출돼요.
• onError: 결제 과정에서 에러가 나면 호출돼요.

반환값인 cleanup 함수는 인앱결제 기능이 끝나면 반드시 호출해 리소스를 해제해요.

토스앱 Android/iOS 5.219.0 이상에서 사용할 수 있어요. 미지원 버전에서 호출하면 UNSUPPORTED_APP_VERSION 에러가 발생해요.

타입

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

Params

interface IapCreateOneTimePurchaseOrderOptions {
  options: {
    sku: string;
    /** @deprecated 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

결제 흐름이 끝나면 호출해 리소스를 해제하는 cleanup 함수(() => void)를 반환해요.

에러

에러 코드는 onError로 받거나 호출을 감싼 try/catch에서 잡은 에러의 error.code 값이에요.

코드	설명
INVALID_PRODUCT_ID	유효하지 않은 상품 ID이거나 상품이 없는 경우예요.
PAYMENT_PENDING	결제가 아직 승인을 기다리고 있는 경우예요.
NETWORK_ERROR	네트워크/서버 문제로 요청을 처리할 수 없는 경우예요.
INVALID_USER_ENVIRONMENT	특정 기기·계정·설정에서 구매할 수 없는 상품인 경우예요.
ITEM_ALREADY_OWNED	이미 구매한 상품을 다시 구매하려 하는 경우예요.
APP_MARKET_VERIFICATION_FAILED	결제는 됐지만 앱스토어 검증에 실패한 경우예요.
TOSS_SERVER_VERIFICATION_FAILED	결제는 됐지만 서버 전송/저장에 실패한 경우예요.
INTERNAL_ERROR	서버 내부 문제로 요청을 처리할 수 없는 경우예요.
KOREAN_ACCOUNT_ONLY	iOS에서 한국 계정이 아닌 경우예요.
USER_CANCELED	사용자가 주문서에서 이탈한 경우예요.
PRODUCT_NOT_GRANTED_BY_PARTNER	파트너사 상품 지급이 실패한 경우예요.
UNSUPPORTED_APP_VERSION	실행 중인 토스앱 버전이 이 기능을 지원하지 않으면 호출 즉시 발생해요. IAP.createOneTimePurchaseOrder.isSupported()로 사전 확인하고, 발생 시 error.message(업데이트 안내 문구)를 사용자에게 보여주세요.

예시 코드

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 }) => {
          // 상품 지급 로직 작성
          console.log("지급 처리:", orderId);
          return true;
        },
      },
      onEvent: (event) => {
        console.log(event.type, event.data);
      },
      onError: (error) => {
        console.error(error);
      },
    });
  } catch (error) {
    console.error(error);
  }
});

// 화면을 떠날 때 cleanup?.()