IAP.createSubscriptionPurchaseOrder

구독 상품의 인앱결제 주문서 페이지로 이동합니다. 사용자가 구독 상품 구매 버튼을 누르는 상황에서 호출합니다. createOneTimePurchaseOrder와 흐름이 동일하며, 구독 ID(subscriptionId)가 추가로 제공됩니다.

시그니처

createSubscriptionPurchaseOrder는 IAP 네임스페이스 객체의 멤버로 노출됩니다.

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

declare const IAP: {
  createSubscriptionPurchaseOrder(params: {
    options: {
      sku: string;
      offerId?: string | null;
      processProductGrant: (params: {
        orderId: string;
        subscriptionId?: string;
      }) => boolean | Promise<boolean>;
    };
    onEvent: (event: { type: 'success'; data: IapCreateSubscriptionPurchaseOrderResult }) => void | Promise<void>;
    onError: (error: unknown) => void | Promise<void>;
  }): () => void;
  // ...overview 참고
};

파라미터

이름	타입	필수	설명
params.options.sku	string	✓	주문할 구독 상품의 고유 ID.
params.options.offerId	string | null		적용할 offer ID. 없으면 기본 가격이 적용됩니다.
params.options.processProductGrant	(params: { orderId: string; subscriptionId?: string }) => boolean | Promise<boolean>	✓	주문 생성 후 서버에서 구독을 지급할 때 호출되는 콜백. 지급 성공 시 true, 실패 시 false를 반환합니다.
params.onEvent	(event: SubscriptionSuccessEvent) => void | Promise<void>	✓	결제 성공 시 호출되는 이벤트 핸들러.
params.onError	(error: unknown) => void | Promise<void>	✓	결제 중 에러 발생 시 호출되는 핸들러.

반환값

• () => void — 앱브릿지 cleanup 함수. 결제 흐름이 끝나면 반드시 호출해 리소스를 해제해야 합니다.

권한

권한이 필요하지 않습니다 — IAP 네임스페이스는 별도의 PermissionName에 바인딩되지 않습니다.

예제

최소 예제

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

const cleanup = IAP.createSubscriptionPurchaseOrder({
  options: {
    sku: 'sub_monthly',
    processProductGrant: async ({ orderId, subscriptionId }) => {
      // 서버에서 구독 지급 후 true 반환
      return true;
    },
  },
  onEvent: (event) => {
    console.log('구독 완료', event.data);
    cleanup();
  },
  onError: (error) => {
    console.error('구독 오류', error);
    cleanup();
  },
});

실전 예제 — offer ID 적용

import { IAP } from '@apps-in-toss/web-framework';
import { useCallback, useRef } from 'react';

interface Props {
  sku: string;
  offerId?: string;
}

function SubscriptionButton({ sku, offerId }: Props) {
  const cleanupRef = useRef<(() => void) | null>(null);

  const handleClick = useCallback(() => {
    cleanupRef.current = IAP.createSubscriptionPurchaseOrder({
      options: {
        sku,
        offerId: offerId ?? null,
        processProductGrant: async ({ orderId, subscriptionId }) => {
          try {
            await fetch('/api/subscribe', {
              method: 'POST',
              body: JSON.stringify({ orderId, subscriptionId }),
              headers: { 'Content-Type': 'application/json' },
            });
            return true;
          } catch {
            return false;
          }
        },
      },
      onEvent: (event) => {
        console.log('구독 활성화', event.data);
        cleanupRef.current?.();
      },
      onError: (error) => {
        console.error(error);
        cleanupRef.current?.();
      },
    });
  }, [sku, offerId]);

  return (
    <button type="button" onClick={handleClick}>
      구독하기
    </button>
  );
}

직접 실행해 보기

sdk-example의 IAP 페이지에서 구독 구매 흐름을 실행해 볼 수 있습니다.

→sdk-example에서 실행해 보기

관련 API

• IAP.createOneTimePurchaseOrder — 단건 구매 주문서로 이동합니다.
• IAP.getProductItemList — 구매 전 상품 목록을 조회합니다.
• IAP.getSubscriptionInfo — 구독 상태를 조회합니다.
• IAP.completeProductGrant — 서버 지급 완료 신호를 전송합니다.

관련 가이드

• Guides — IAP 결제 흐름 — processProductGrant/completeProductGrant 시퀀스·서버 fulfillment·복구 패턴을 한 곳에 정리한 가이드.

외부 참조

• @apps-in-toss/web-framework — 상위 SDK 패키지. 실제 export는 내부적으로 @apps-in-toss/web-bridge에서 가져옵니다.