@apps-in-toss/native-modules 1.1.2 → 1.2.0

package/dist/index.d.cts

@@ -231,24 +231,12 @@ interface ContactsViralParams {
  */
 declare function contactsViral(params: ContactsViralParams): () => void;
 
-declare class BackButtonClickHandleEvent extends GraniteEventDefinition<undefined, undefined> {
-    name: "backButtonClickEvent";
-    remove(): void;
-    listener(_: undefined): void;
-}
-
 declare class EntryMessageExitedEvent extends GraniteEventDefinition<undefined, undefined> {
     name: "entryMessageExited";
     remove(): void;
     listener(_: undefined): void;
 }
 
-declare class HomeIconButtonClickHandleEvent extends GraniteEventDefinition<undefined, undefined> {
-    name: "homeIconButtonClickEvent";
-    remove(): void;
-    listener(_: undefined): void;
-}
-
 interface StartUpdateLocationOptions {
     /**
      * 위치 정확도를 설정해요.
@@ -298,7 +286,7 @@ declare class VisibilityChangedByTransparentServiceWebEvent extends GraniteEvent
     private isVisibilityChangedByTransparentServiceWebResult;
 }
 
-declare const appsInTossEvent: GraniteEvent<BackButtonClickHandleEvent | EntryMessageExitedEvent | HomeIconButtonClickHandleEvent | UpdateLocationEvent | AppBridgeCallbackEvent | VisibilityChangedByTransparentServiceWebEvent>;
+declare const appsInTossEvent: GraniteEvent<EntryMessageExitedEvent | UpdateLocationEvent | AppBridgeCallbackEvent | VisibilityChangedByTransparentServiceWebEvent>;
 
 declare function onVisibilityChangedByTransparentServiceWeb(eventParams: {
     options: {
@@ -1423,16 +1411,16 @@ type GameCenterGameProfileResponse = {
  */
 declare function getGameCenterGameProfile(): Promise<GameCenterGameProfileResponse | undefined>;
 
-/**
- * @public
- * @category 인앱결제
- * @name IapCreateOneTimePurchaseOrderOptions
- * @description 인앱결제 1건을 요청할 때 필요한 정보예요.
- * @property {string} productId - 주문할 상품의 ID예요.
- */
-interface IapCreateOneTimePurchaseOrderOptions {
+type Sku = {
+    /**
+     * @deprecated `productId`는 더 이상 사용하지 않아요. 대신 `sku`를 사용해요.
+     */
     productId: string;
-}
+    sku?: string;
+} | {
+    productId?: never;
+    sku: string;
+};
 /**
  * @public
  * @category 인앱결제
@@ -1455,15 +1443,54 @@ interface IapCreateOneTimePurchaseOrderResult {
     fraction: number;
     miniAppIconUrl: string | null;
 }
+interface SuccessEvent {
+    type: 'success';
+    data: IapCreateOneTimePurchaseOrderResult;
+}
+interface PurchasedEvent {
+    type: 'purchased';
+    data: {
+        orderId: string;
+    };
+}
 /**
  * @public
  * @category 인앱결제
- * @name iapCreateOneTimePurchaseOrder
+ * @name IapCreateOneTimePurchaseOrderOptions
+ * @property {Sku} options - 결제할 상품의 정보예요.
+ * @property {string} options.sku - 주문할 상품의 고유 ID예요.
+ * @property {(params: { orderId: string }) => boolean | Promise<boolean>} processProductGrant - 주문이 만들어진 뒤 실제로 상품을 지급할 때 호출해요. `orderId`를 받아서 지급 성공 여부를 `true` 또는 `Promise<true>`로 반환해요. 지급에 실패하면 `false`를 반환해요.
+ * @property {(event: SuccessEvent) => void | Promise<void>} onEvent - 결제가 성공했을 때 호출해요. `event.type`이 `'success'`이고, `event.data`에 `IapCreateOneTimePurchaseOrderResult`가 들어 있어요.
+ * @property {(error: unknown) => void | Promise<void>} onError - 결제 과정에서 에러가 발생했을 때 호출해요. 에러 객체를 받아서 로깅하거나 복구 절차를 실행할 수 있어요.
+ */
+interface IapCreateOneTimePurchaseOrderOptions {
+    options: Sku & {
+        processProductGrant: (params: {
+            orderId: string;
+        }) => boolean | Promise<boolean>;
+    };
+    onEvent: (event: SuccessEvent) => void | Promise<void>;
+    onError: (error: unknown) => void | Promise<void>;
+}
+interface IapRequestOneTimePurchaseOptions {
+    options: Sku;
+    onEvent: (event: PurchasedEvent | SuccessEvent) => void | Promise<void>;
+    onError: (error: unknown) => void | Promise<void>;
+}
+declare function iapCreateOneTimePurchaseOrder(params: Sku): Promise<IapCreateOneTimePurchaseOrderResult>;
+declare function processProductGrant(params: {
+    orderId: string;
+    isProductGranted: boolean;
+}): Promise<void>;
+declare function requestOneTimePurchase(params: IapRequestOneTimePurchaseOptions): () => void;
+/**
+ * @public
+ * @category 인앱결제
+ * @name createOneTimePurchaseOrder
  * @description
  * 특정 인앱결제 주문서 페이지로 이동해요. 사용자가 상품 구매 버튼을 누르는 상황 등에 사용할 수 있어요. 사용자의 결제는 이동한 페이지에서 진행돼요. 만약 결제 중에 에러가 발생하면 에러 유형에 따라 에러 페이지로 이동해요.
  * @param {IapCreateOneTimePurchaseOrderOptions} params - 인앱결제를 생성할 때 필요한 정보예요.
- * @param {string} params.productId - 주문할 상품의 ID예요.
- * @returns {Promise<IapCreateOneTimePurchaseOrderResult | undefined>} 결제에 성공하면 결제 결과 객체를 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.219.0, iOS 5.219.0)보다 낮으면 인앱결제를 실행할 수 없어서 `undefined`를 반환해요.
+ * @returns {() => void} 앱브릿지 cleanup 함수를 반환해요. 인앱결제 기능이 끝나면 반드시 이 함수를 호출해서 리소스를 해제해야 해요.
  *
  * @throw {code: "INVALID_PRODUCT_ID"} - 유효하지 않은 상품 ID이거나, 해당 상품이 존재하지 않을 때 발생해요.
  * @throw {code: "PAYMENT_PENDING"} - 사용자가 요청한 결제가 아직 승인을 기다리고 있을 때 발생해요.
@@ -1475,41 +1502,53 @@ interface IapCreateOneTimePurchaseOrderResult {
  * @throw {code: "INTERNAL_ERROR"} - 서버 내부 문제로 요청을 처리할 수 없을 때 발생해요.
  * @throw {code: "KOREAN_ACCOUNT_ONLY"} - iOS 환경에서 사용자의 계정이 한국 계정이 아닐 때 발생해요.
  * @throw {code: "USER_CANCELED"} - 사용자가 결제를 완료하지 않고 주문서 페이지를 이탈했을 때 발생해요.
+ * @throw {code: "PRODUCT_NOT_GRANTED_BY_PARTNER"} - 파트너사의 상품 지급이 실패했을 때 발생해요.
  *
  * @example
  * ### 특정 인앱결제 주문서 페이지로 이동하기
  *
  * ```tsx
  * import { IAP } from "@apps-in-toss/web-framework";
- * import { Button } from "@toss-design-system/react-native";
+ * import { Button } from "@toss/tds-react-native";
+ * import { useCallback } from "react";
  *
  * interface Props {
- *   productId: string;
+ *   sku: string;
  * }
  *
- * function IapCreateOneTimePurchaseOrderButton({ productId }: Props) {
- *   async function handleClick() {
- *     try {
- *       await IAP.createOneTimePurchaseOrder({
- *         productId,
- *       });
- *       console.error("인앱결제에 성공했어요");
- *     } catch (error) {
- *       console.error('인앱결제에 실패했어요:', error);
- *     }
- *   }
+ * function IapCreateOneTimePurchaseOrderButton({ sku }: Props) {
+ *   const handleClick = useCallback(async () => {
+ *
+ *     const cleanup = await IAP.createOneTimePurchaseOrder({
+ *       options: {
+ *        sku,
+ *        processProductGrant: ({ orderId }) => {
+ *         // 상품 지급 로직 작성
+ *          return true; // 상품 지급 여부
+ *        }
+ *        },
+ *       onEvent: (event) => {
+ *         console.log(event);
+ *       },
+ *       onError: (error) => {
+ *         console.error(error);
+ *       },
+ *     });
+ *
+ *     return cleanup;
+ *   }, []);
  *
  *   return <Button onClick={handleClick}>구매하기</Button>;
  * }
  * ```
  */
-declare function createOneTimePurchaseOrder(params: IapCreateOneTimePurchaseOrderOptions): Promise<IapCreateOneTimePurchaseOrderResult | undefined>;
+declare function createOneTimePurchaseOrder(params: IapCreateOneTimePurchaseOrderOptions): () => void;
 /**
  * @public
  * @category 인앱결제
  * @name IapProductListItem
  * @description 인앱결제로 구매할 수 있는 상품 하나의 정보를 담은 객체예요. 상품 목록을 화면에 표시할 때 사용해요.
- * @property {string} sku - 상품의 고유 ID예요. [IAP.createOneTimePurchaseOrder](https://developers-apps-in-toss.toss.im/bedrock/reference/native-modules/%EC%9D%B8%EC%95%B1%20%EA%B2%B0%EC%A0%9C/createOneTimePurchaseOrder.html)를 호출할때 사용하는 `productId`와 동일한 값이에요.
+ * @property {string} sku - 상품의 고유 ID예요.
  * @property {string} displayName - 화면에 표시할 상품 이름이에요. 상품 이름은 앱인토스 콘솔에서 설정한 값이에요.
  * @property {string} displayAmount - 통화 단위가 포함된 가격 정보예요. 예를 들어 `1,000원`으로 가격과 통화가 함께 표시돼요.
  * @property {string} iconUrl - 상품 아이콘 이미지의 URL이에요. 아이콘은 앱인토스 콘솔에서 설정한 이미지예요.
@@ -1525,7 +1564,7 @@ interface IapProductListItem {
 /**
  * @public
  * @category 인앱결제
- * @name iapGetProductItemList
+ * @name getProductItemList
  * @description 인앱결제로 구매할 수 있는 상품 목록을 가져와요. 상품 목록 화면에 진입할 때 호출해요.
  * @returns {Promise<{ products: IapProductListItem[] } | undefined>} 상품 목록을 포함한 객체를 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.219.0, iOS 5.219.0)보다 낮으면 `undefined`를 반환해요.
  *
@@ -1534,7 +1573,7 @@ interface IapProductListItem {
  *
  * ```tsx
  * import { IAP, IapProductListItem } from "@apps-in-toss/framework";
- * import { Button, List, ListRow } from "@toss-design-system/react-native";
+ * import { Button, List, ListRow } from "@toss/tds-react-native";
  * import { useEffect, useState } from "react";
  *
  * function IapProductList() {
@@ -1596,6 +1635,78 @@ interface IapProductListItem {
 declare function getProductItemList(): Promise<{
     products: IapProductListItem[];
 } | undefined>;
+/**
+ * @public
+ * @category 인앱결제
+ * @name getPendingOrders
+ * @description 대기 중인 주문 목록을 가져와요. 이 함수를 사용하면 결제가 아직 완료되지 않은 주문 정보를 확인할 수 있어요.
+ * @returns {Promise<{orderIds: string[]}}>} 대기 중인 주문ID 배열을 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.231.0, iOS 5.231.0)보다 낮으면 `undefined`를 반환해요.
+ *
+ * @example
+ * ### 대기 중인 주문 목록 가져오기
+ * ```typescript
+ * import { IAP } from '@apps-in-toss/framework';
+ *
+ * async function fetchOrders() {
+ *   try {
+ *     const pendingOrders = await IAP.getPendingOrders();
+ *     return pendingOrders;
+ *   } catch (error) {
+ *     console.error(error);
+ *   }
+ * }
+ * ```
+ */
+declare function getPendingOrders(): Promise<{
+    orderIds: string[];
+} | undefined>;
+/**
+ * @public
+ * @category 인앱결제
+ * @name CompletedOrRefundedOrdersResult
+ * @description 인앱결제로 구매하거나 환불한 주문 목록을 나타내는 객체예요. 페이지네이션 정보를 포함해요.
+ * @property {boolean} hasNext 다음 페이지가 있는지 여부예요. `true`면 더 많은 주문이 남아 있어요.
+ * @property {string | null} [nextKey] 다음 주문 목록을 조회할 때 사용할 키예요. 마지막 페이지라면 `null`이거나 생략될 수 있어요.
+ * @property {Array} orders 주문 정보를 담은 배열이에요. 각 요소는 하나의 주문을 나타내요.
+ * @property {string} orders[].orderId 주문의 고유 ID예요.
+ * @property {string} orders[].sku 주문 상품의 고유 ID예요.
+ * @property {'COMPLETED' | 'REFUNDED'} orders[].status 주문의 상태예요. 'COMPLETED'는 주문이 완료된 상태, 'REFUNDED'는 환불된 상태를 의미해요.
+ * @property {string} orders[].date 주문의 날짜 정보예요. ISO 8601 형식(YYYY-MM-DDTHH:mm:ss)을 사용해요. 예를 들어 "2025-09-22T00:00:00" 형식으로 제공돼요. 주문 상태가 `COMPLETED`라면 주문한 날짜를, `REFUNDED`라면 환불한 날짜를 나타내요.
+ */
+interface CompletedOrRefundedOrdersResult {
+    hasNext: boolean;
+    nextKey?: string | null;
+    orders: {
+        orderId: string;
+        sku: string;
+        status: 'COMPLETED' | 'REFUNDED';
+        date: string;
+    }[];
+}
+/**
+ * @public
+ * @category 인앱결제
+ * @name getCompletedOrRefundedOrders
+ * @description 인앱결제로 구매하거나 환불한 주문 목록을 가져와요.
+ * @returns {Promise<CompletedOrRefundedOrdersResult>} 페이지네이션을 포함한 주문 목록 객체를 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.231.0, iOS 5.231.0)보다 낮으면 `undefined`를 반환해요.
+ *
+ * @example
+ * ```typescript
+ * import { IAP } from "@apps-in-toss/framework";
+ *
+ * async function fetchOrders() {
+ *   try {
+ *     const response =  await IAP.getCompletedOrRefundedOrders();
+ *     return response;
+ *   } catch (error) {
+ *     console.error(error);
+ *   }
+ * }
+ * ```
+ */
+declare function getCompletedOrRefundedOrders(params?: {
+    key?: string | null;
+}): Promise<CompletedOrRefundedOrdersResult | undefined>;
 /**
  * @public
  * @category 인앱결제
@@ -1607,6 +1718,8 @@ declare function getProductItemList(): Promise<{
 declare const IAP: {
     createOneTimePurchaseOrder: typeof createOneTimePurchaseOrder;
     getProductItemList: typeof getProductItemList;
+    getPendingOrders: typeof getPendingOrders;
+    getCompletedOrRefundedOrders: typeof getCompletedOrRefundedOrders;
 };
 
 interface SaveBase64DataParams {
@@ -1773,10 +1886,30 @@ interface Spec extends TurboModule {
     }) => Promise<void>;
     saveBase64Data: (params: SaveBase64DataParams) => Promise<void>;
     /** IAP */
-    iapCreateOneTimePurchaseOrder: (params: IapCreateOneTimePurchaseOrderOptions) => Promise<IapCreateOneTimePurchaseOrderResult>;
     iapGetProductItemList: (arg: CompatiblePlaceholderArgument) => Promise<{
         products: IapProductListItem[];
     }>;
+    /** @deprecated `requestOneTimePurchase`를 사용해주세요. */
+    iapCreateOneTimePurchaseOrder: (params: {
+        productId: string;
+    }) => Promise<IapCreateOneTimePurchaseOrderResult>;
+    requestOneTimePurchase: (params: {
+        sku: string;
+    }, fallbacks: {
+        onPurchased: (params: {
+            orderId: string;
+        }) => void;
+    }) => () => void;
+    processProductGrant: (params: {
+        orderId: string;
+        isProductGranted: boolean;
+    }) => Promise<void>;
+    getPendingOrders: (params: CompatiblePlaceholderArgument) => Promise<{
+        orderIds: string[];
+    }>;
+    getCompletedOrRefundedOrders: (params: {
+        key?: string | null;
+    }) => Promise<CompletedOrRefundedOrdersResult>;
     getGameCenterGameProfile: (params: CompatiblePlaceholderArgument) => Promise<GameCenterGameProfileResponse>;
     submitGameCenterLeaderBoardScore: (params: {
         score: string;
@@ -3195,4 +3328,4 @@ declare const INTERNAL__module: {
     tossCoreEventLog: typeof tossCoreEventLog;
 };
 
-export { AppsInTossModule, BedrockCoreModule, BedrockModule, type CheckoutPaymentOptions, type CheckoutPaymentResult, type ContactsViralParams, type EventLogParams, type GameCenterGameProfileResponse, GoogleAdMob, type HapticFeedbackType, IAP, AppsInTossModuleInstance as INTERNAL__AppsInTossModule, INTERNAL__appBridgeHandler, INTERNAL__module, type IapCreateOneTimePurchaseOrderOptions, type IapCreateOneTimePurchaseOrderResult, type IapProductListItem, type LoadAdMobEvent, type LoadAdMobInterstitialAdEvent, type LoadAdMobInterstitialAdOptions, type LoadAdMobOptions, type LoadAdMobParams, type LoadAdMobRewardedAdEvent, type LoadAdMobRewardedAdOptions, type NetworkStatus, type Primitive, type SaveBase64DataParams, type ShowAdMobEvent, type ShowAdMobInterstitialAdEvent, type ShowAdMobInterstitialAdOptions, type ShowAdMobOptions, type ShowAdMobParams, type ShowAdMobRewardedAdEvent, type ShowAdMobRewardedAdOptions, Storage, type SubmitGameCenterLeaderBoardScoreResponse, TossPay, type UpdateLocationEventEmitter, appLogin, appsInTossEvent, closeView, contactsViral, eventLog, fetchAlbumPhotos, fetchContacts, generateHapticFeedback, getClipboardText, getCurrentLocation, getDeviceId, getGameCenterGameProfile, getLocale, getNetworkStatus, getOperationalEnvironment, getPlatformOS, getSchemeUri, getTossAppVersion, getTossShareLink, isMinVersionSupported, onVisibilityChangedByTransparentServiceWeb, openCamera, openGameCenterLeaderboard, openURL, saveBase64Data, setClipboardText, setDeviceOrientation, setIosSwipeGestureEnabled, setScreenAwakeMode, setSecureScreen, share, startUpdateLocation, submitGameCenterLeaderBoardScore };
+export { AppsInTossModule, BedrockCoreModule, BedrockModule, type CheckoutPaymentOptions, type CheckoutPaymentResult, type CompletedOrRefundedOrdersResult, type ContactsViralParams, type EventLogParams, type GameCenterGameProfileResponse, GoogleAdMob, type HapticFeedbackType, IAP, AppsInTossModuleInstance as INTERNAL__AppsInTossModule, INTERNAL__appBridgeHandler, INTERNAL__module, type IapCreateOneTimePurchaseOrderOptions, type IapCreateOneTimePurchaseOrderResult, type IapProductListItem, type LoadAdMobEvent, type LoadAdMobInterstitialAdEvent, type LoadAdMobInterstitialAdOptions, type LoadAdMobOptions, type LoadAdMobParams, type LoadAdMobRewardedAdEvent, type LoadAdMobRewardedAdOptions, type NetworkStatus, type Primitive, type SaveBase64DataParams, type ShowAdMobEvent, type ShowAdMobInterstitialAdEvent, type ShowAdMobInterstitialAdOptions, type ShowAdMobOptions, type ShowAdMobParams, type ShowAdMobRewardedAdEvent, type ShowAdMobRewardedAdOptions, Storage, type SubmitGameCenterLeaderBoardScoreResponse, TossPay, type UpdateLocationEventEmitter, appLogin, appsInTossEvent, closeView, contactsViral, eventLog, fetchAlbumPhotos, fetchContacts, generateHapticFeedback, getClipboardText, getCurrentLocation, getDeviceId, getGameCenterGameProfile, getLocale, getNetworkStatus, getOperationalEnvironment, getPlatformOS, getSchemeUri, getTossAppVersion, getTossShareLink, iapCreateOneTimePurchaseOrder, isMinVersionSupported, onVisibilityChangedByTransparentServiceWeb, openCamera, openGameCenterLeaderboard, openURL, processProductGrant, requestOneTimePurchase, saveBase64Data, setClipboardText, setDeviceOrientation, setIosSwipeGestureEnabled, setScreenAwakeMode, setSecureScreen, share, startUpdateLocation, submitGameCenterLeaderBoardScore };

package/dist/index.d.ts

@@ -231,24 +231,12 @@ interface ContactsViralParams {
  */
 declare function contactsViral(params: ContactsViralParams): () => void;
 
-declare class BackButtonClickHandleEvent extends GraniteEventDefinition<undefined, undefined> {
-    name: "backButtonClickEvent";
-    remove(): void;
-    listener(_: undefined): void;
-}
-
 declare class EntryMessageExitedEvent extends GraniteEventDefinition<undefined, undefined> {
     name: "entryMessageExited";
     remove(): void;
     listener(_: undefined): void;
 }
 
-declare class HomeIconButtonClickHandleEvent extends GraniteEventDefinition<undefined, undefined> {
-    name: "homeIconButtonClickEvent";
-    remove(): void;
-    listener(_: undefined): void;
-}
-
 interface StartUpdateLocationOptions {
     /**
      * 위치 정확도를 설정해요.
@@ -298,7 +286,7 @@ declare class VisibilityChangedByTransparentServiceWebEvent extends GraniteEvent
     private isVisibilityChangedByTransparentServiceWebResult;
 }
 
-declare const appsInTossEvent: GraniteEvent<BackButtonClickHandleEvent | EntryMessageExitedEvent | HomeIconButtonClickHandleEvent | UpdateLocationEvent | AppBridgeCallbackEvent | VisibilityChangedByTransparentServiceWebEvent>;
+declare const appsInTossEvent: GraniteEvent<EntryMessageExitedEvent | UpdateLocationEvent | AppBridgeCallbackEvent | VisibilityChangedByTransparentServiceWebEvent>;
 
 declare function onVisibilityChangedByTransparentServiceWeb(eventParams: {
     options: {
@@ -1423,16 +1411,16 @@ type GameCenterGameProfileResponse = {
  */
 declare function getGameCenterGameProfile(): Promise<GameCenterGameProfileResponse | undefined>;
 
-/**
- * @public
- * @category 인앱결제
- * @name IapCreateOneTimePurchaseOrderOptions
- * @description 인앱결제 1건을 요청할 때 필요한 정보예요.
- * @property {string} productId - 주문할 상품의 ID예요.
- */
-interface IapCreateOneTimePurchaseOrderOptions {
+type Sku = {
+    /**
+     * @deprecated `productId`는 더 이상 사용하지 않아요. 대신 `sku`를 사용해요.
+     */
     productId: string;
-}
+    sku?: string;
+} | {
+    productId?: never;
+    sku: string;
+};
 /**
  * @public
  * @category 인앱결제
@@ -1455,15 +1443,54 @@ interface IapCreateOneTimePurchaseOrderResult {
     fraction: number;
     miniAppIconUrl: string | null;
 }
+interface SuccessEvent {
+    type: 'success';
+    data: IapCreateOneTimePurchaseOrderResult;
+}
+interface PurchasedEvent {
+    type: 'purchased';
+    data: {
+        orderId: string;
+    };
+}
 /**
  * @public
  * @category 인앱결제
- * @name iapCreateOneTimePurchaseOrder
+ * @name IapCreateOneTimePurchaseOrderOptions
+ * @property {Sku} options - 결제할 상품의 정보예요.
+ * @property {string} options.sku - 주문할 상품의 고유 ID예요.
+ * @property {(params: { orderId: string }) => boolean | Promise<boolean>} processProductGrant - 주문이 만들어진 뒤 실제로 상품을 지급할 때 호출해요. `orderId`를 받아서 지급 성공 여부를 `true` 또는 `Promise<true>`로 반환해요. 지급에 실패하면 `false`를 반환해요.
+ * @property {(event: SuccessEvent) => void | Promise<void>} onEvent - 결제가 성공했을 때 호출해요. `event.type`이 `'success'`이고, `event.data`에 `IapCreateOneTimePurchaseOrderResult`가 들어 있어요.
+ * @property {(error: unknown) => void | Promise<void>} onError - 결제 과정에서 에러가 발생했을 때 호출해요. 에러 객체를 받아서 로깅하거나 복구 절차를 실행할 수 있어요.
+ */
+interface IapCreateOneTimePurchaseOrderOptions {
+    options: Sku & {
+        processProductGrant: (params: {
+            orderId: string;
+        }) => boolean | Promise<boolean>;
+    };
+    onEvent: (event: SuccessEvent) => void | Promise<void>;
+    onError: (error: unknown) => void | Promise<void>;
+}
+interface IapRequestOneTimePurchaseOptions {
+    options: Sku;
+    onEvent: (event: PurchasedEvent | SuccessEvent) => void | Promise<void>;
+    onError: (error: unknown) => void | Promise<void>;
+}
+declare function iapCreateOneTimePurchaseOrder(params: Sku): Promise<IapCreateOneTimePurchaseOrderResult>;
+declare function processProductGrant(params: {
+    orderId: string;
+    isProductGranted: boolean;
+}): Promise<void>;
+declare function requestOneTimePurchase(params: IapRequestOneTimePurchaseOptions): () => void;
+/**
+ * @public
+ * @category 인앱결제
+ * @name createOneTimePurchaseOrder
  * @description
  * 특정 인앱결제 주문서 페이지로 이동해요. 사용자가 상품 구매 버튼을 누르는 상황 등에 사용할 수 있어요. 사용자의 결제는 이동한 페이지에서 진행돼요. 만약 결제 중에 에러가 발생하면 에러 유형에 따라 에러 페이지로 이동해요.
  * @param {IapCreateOneTimePurchaseOrderOptions} params - 인앱결제를 생성할 때 필요한 정보예요.
- * @param {string} params.productId - 주문할 상품의 ID예요.
- * @returns {Promise<IapCreateOneTimePurchaseOrderResult | undefined>} 결제에 성공하면 결제 결과 객체를 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.219.0, iOS 5.219.0)보다 낮으면 인앱결제를 실행할 수 없어서 `undefined`를 반환해요.
+ * @returns {() => void} 앱브릿지 cleanup 함수를 반환해요. 인앱결제 기능이 끝나면 반드시 이 함수를 호출해서 리소스를 해제해야 해요.
  *
  * @throw {code: "INVALID_PRODUCT_ID"} - 유효하지 않은 상품 ID이거나, 해당 상품이 존재하지 않을 때 발생해요.
  * @throw {code: "PAYMENT_PENDING"} - 사용자가 요청한 결제가 아직 승인을 기다리고 있을 때 발생해요.
@@ -1475,41 +1502,53 @@ interface IapCreateOneTimePurchaseOrderResult {
  * @throw {code: "INTERNAL_ERROR"} - 서버 내부 문제로 요청을 처리할 수 없을 때 발생해요.
  * @throw {code: "KOREAN_ACCOUNT_ONLY"} - iOS 환경에서 사용자의 계정이 한국 계정이 아닐 때 발생해요.
  * @throw {code: "USER_CANCELED"} - 사용자가 결제를 완료하지 않고 주문서 페이지를 이탈했을 때 발생해요.
+ * @throw {code: "PRODUCT_NOT_GRANTED_BY_PARTNER"} - 파트너사의 상품 지급이 실패했을 때 발생해요.
  *
  * @example
  * ### 특정 인앱결제 주문서 페이지로 이동하기
  *
  * ```tsx
  * import { IAP } from "@apps-in-toss/web-framework";
- * import { Button } from "@toss-design-system/react-native";
+ * import { Button } from "@toss/tds-react-native";
+ * import { useCallback } from "react";
  *
  * interface Props {
- *   productId: string;
+ *   sku: string;
  * }
  *
- * function IapCreateOneTimePurchaseOrderButton({ productId }: Props) {
- *   async function handleClick() {
- *     try {
- *       await IAP.createOneTimePurchaseOrder({
- *         productId,
- *       });
- *       console.error("인앱결제에 성공했어요");
- *     } catch (error) {
- *       console.error('인앱결제에 실패했어요:', error);
- *     }
- *   }
+ * function IapCreateOneTimePurchaseOrderButton({ sku }: Props) {
+ *   const handleClick = useCallback(async () => {
+ *
+ *     const cleanup = await IAP.createOneTimePurchaseOrder({
+ *       options: {
+ *        sku,
+ *        processProductGrant: ({ orderId }) => {
+ *         // 상품 지급 로직 작성
+ *          return true; // 상품 지급 여부
+ *        }
+ *        },
+ *       onEvent: (event) => {
+ *         console.log(event);
+ *       },
+ *       onError: (error) => {
+ *         console.error(error);
+ *       },
+ *     });
+ *
+ *     return cleanup;
+ *   }, []);
  *
  *   return <Button onClick={handleClick}>구매하기</Button>;
  * }
  * ```
  */
-declare function createOneTimePurchaseOrder(params: IapCreateOneTimePurchaseOrderOptions): Promise<IapCreateOneTimePurchaseOrderResult | undefined>;
+declare function createOneTimePurchaseOrder(params: IapCreateOneTimePurchaseOrderOptions): () => void;
 /**
  * @public
  * @category 인앱결제
  * @name IapProductListItem
  * @description 인앱결제로 구매할 수 있는 상품 하나의 정보를 담은 객체예요. 상품 목록을 화면에 표시할 때 사용해요.
- * @property {string} sku - 상품의 고유 ID예요. [IAP.createOneTimePurchaseOrder](https://developers-apps-in-toss.toss.im/bedrock/reference/native-modules/%EC%9D%B8%EC%95%B1%20%EA%B2%B0%EC%A0%9C/createOneTimePurchaseOrder.html)를 호출할때 사용하는 `productId`와 동일한 값이에요.
+ * @property {string} sku - 상품의 고유 ID예요.
  * @property {string} displayName - 화면에 표시할 상품 이름이에요. 상품 이름은 앱인토스 콘솔에서 설정한 값이에요.
  * @property {string} displayAmount - 통화 단위가 포함된 가격 정보예요. 예를 들어 `1,000원`으로 가격과 통화가 함께 표시돼요.
  * @property {string} iconUrl - 상품 아이콘 이미지의 URL이에요. 아이콘은 앱인토스 콘솔에서 설정한 이미지예요.
@@ -1525,7 +1564,7 @@ interface IapProductListItem {
 /**
  * @public
  * @category 인앱결제
- * @name iapGetProductItemList
+ * @name getProductItemList
  * @description 인앱결제로 구매할 수 있는 상품 목록을 가져와요. 상품 목록 화면에 진입할 때 호출해요.
  * @returns {Promise<{ products: IapProductListItem[] } | undefined>} 상품 목록을 포함한 객체를 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.219.0, iOS 5.219.0)보다 낮으면 `undefined`를 반환해요.
  *
@@ -1534,7 +1573,7 @@ interface IapProductListItem {
  *
  * ```tsx
  * import { IAP, IapProductListItem } from "@apps-in-toss/framework";
- * import { Button, List, ListRow } from "@toss-design-system/react-native";
+ * import { Button, List, ListRow } from "@toss/tds-react-native";
  * import { useEffect, useState } from "react";
  *
  * function IapProductList() {
@@ -1596,6 +1635,78 @@ interface IapProductListItem {
 declare function getProductItemList(): Promise<{
     products: IapProductListItem[];
 } | undefined>;
+/**
+ * @public
+ * @category 인앱결제
+ * @name getPendingOrders
+ * @description 대기 중인 주문 목록을 가져와요. 이 함수를 사용하면 결제가 아직 완료되지 않은 주문 정보를 확인할 수 있어요.
+ * @returns {Promise<{orderIds: string[]}}>} 대기 중인 주문ID 배열을 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.231.0, iOS 5.231.0)보다 낮으면 `undefined`를 반환해요.
+ *
+ * @example
+ * ### 대기 중인 주문 목록 가져오기
+ * ```typescript
+ * import { IAP } from '@apps-in-toss/framework';
+ *
+ * async function fetchOrders() {
+ *   try {
+ *     const pendingOrders = await IAP.getPendingOrders();
+ *     return pendingOrders;
+ *   } catch (error) {
+ *     console.error(error);
+ *   }
+ * }
+ * ```
+ */
+declare function getPendingOrders(): Promise<{
+    orderIds: string[];
+} | undefined>;
+/**
+ * @public
+ * @category 인앱결제
+ * @name CompletedOrRefundedOrdersResult
+ * @description 인앱결제로 구매하거나 환불한 주문 목록을 나타내는 객체예요. 페이지네이션 정보를 포함해요.
+ * @property {boolean} hasNext 다음 페이지가 있는지 여부예요. `true`면 더 많은 주문이 남아 있어요.
+ * @property {string | null} [nextKey] 다음 주문 목록을 조회할 때 사용할 키예요. 마지막 페이지라면 `null`이거나 생략될 수 있어요.
+ * @property {Array} orders 주문 정보를 담은 배열이에요. 각 요소는 하나의 주문을 나타내요.
+ * @property {string} orders[].orderId 주문의 고유 ID예요.
+ * @property {string} orders[].sku 주문 상품의 고유 ID예요.
+ * @property {'COMPLETED' | 'REFUNDED'} orders[].status 주문의 상태예요. 'COMPLETED'는 주문이 완료된 상태, 'REFUNDED'는 환불된 상태를 의미해요.
+ * @property {string} orders[].date 주문의 날짜 정보예요. ISO 8601 형식(YYYY-MM-DDTHH:mm:ss)을 사용해요. 예를 들어 "2025-09-22T00:00:00" 형식으로 제공돼요. 주문 상태가 `COMPLETED`라면 주문한 날짜를, `REFUNDED`라면 환불한 날짜를 나타내요.
+ */
+interface CompletedOrRefundedOrdersResult {
+    hasNext: boolean;
+    nextKey?: string | null;
+    orders: {
+        orderId: string;
+        sku: string;
+        status: 'COMPLETED' | 'REFUNDED';
+        date: string;
+    }[];
+}
+/**
+ * @public
+ * @category 인앱결제
+ * @name getCompletedOrRefundedOrders
+ * @description 인앱결제로 구매하거나 환불한 주문 목록을 가져와요.
+ * @returns {Promise<CompletedOrRefundedOrdersResult>} 페이지네이션을 포함한 주문 목록 객체를 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.231.0, iOS 5.231.0)보다 낮으면 `undefined`를 반환해요.
+ *
+ * @example
+ * ```typescript
+ * import { IAP } from "@apps-in-toss/framework";
+ *
+ * async function fetchOrders() {
+ *   try {
+ *     const response =  await IAP.getCompletedOrRefundedOrders();
+ *     return response;
+ *   } catch (error) {
+ *     console.error(error);
+ *   }
+ * }
+ * ```
+ */
+declare function getCompletedOrRefundedOrders(params?: {
+    key?: string | null;
+}): Promise<CompletedOrRefundedOrdersResult | undefined>;
 /**
  * @public
  * @category 인앱결제
@@ -1607,6 +1718,8 @@ declare function getProductItemList(): Promise<{
 declare const IAP: {
     createOneTimePurchaseOrder: typeof createOneTimePurchaseOrder;
     getProductItemList: typeof getProductItemList;
+    getPendingOrders: typeof getPendingOrders;
+    getCompletedOrRefundedOrders: typeof getCompletedOrRefundedOrders;
 };
 
 interface SaveBase64DataParams {
@@ -1773,10 +1886,30 @@ interface Spec extends TurboModule {
     }) => Promise<void>;
     saveBase64Data: (params: SaveBase64DataParams) => Promise<void>;
     /** IAP */
-    iapCreateOneTimePurchaseOrder: (params: IapCreateOneTimePurchaseOrderOptions) => Promise<IapCreateOneTimePurchaseOrderResult>;
     iapGetProductItemList: (arg: CompatiblePlaceholderArgument) => Promise<{
         products: IapProductListItem[];
     }>;
+    /** @deprecated `requestOneTimePurchase`를 사용해주세요. */
+    iapCreateOneTimePurchaseOrder: (params: {
+        productId: string;
+    }) => Promise<IapCreateOneTimePurchaseOrderResult>;
+    requestOneTimePurchase: (params: {
+        sku: string;
+    }, fallbacks: {
+        onPurchased: (params: {
+            orderId: string;
+        }) => void;
+    }) => () => void;
+    processProductGrant: (params: {
+        orderId: string;
+        isProductGranted: boolean;
+    }) => Promise<void>;
+    getPendingOrders: (params: CompatiblePlaceholderArgument) => Promise<{
+        orderIds: string[];
+    }>;
+    getCompletedOrRefundedOrders: (params: {
+        key?: string | null;
+    }) => Promise<CompletedOrRefundedOrdersResult>;
     getGameCenterGameProfile: (params: CompatiblePlaceholderArgument) => Promise<GameCenterGameProfileResponse>;
     submitGameCenterLeaderBoardScore: (params: {
         score: string;
@@ -3195,4 +3328,4 @@ declare const INTERNAL__module: {
     tossCoreEventLog: typeof tossCoreEventLog;
 };
 
-export { AppsInTossModule, BedrockCoreModule, BedrockModule, type CheckoutPaymentOptions, type CheckoutPaymentResult, type ContactsViralParams, type EventLogParams, type GameCenterGameProfileResponse, GoogleAdMob, type HapticFeedbackType, IAP, AppsInTossModuleInstance as INTERNAL__AppsInTossModule, INTERNAL__appBridgeHandler, INTERNAL__module, type IapCreateOneTimePurchaseOrderOptions, type IapCreateOneTimePurchaseOrderResult, type IapProductListItem, type LoadAdMobEvent, type LoadAdMobInterstitialAdEvent, type LoadAdMobInterstitialAdOptions, type LoadAdMobOptions, type LoadAdMobParams, type LoadAdMobRewardedAdEvent, type LoadAdMobRewardedAdOptions, type NetworkStatus, type Primitive, type SaveBase64DataParams, type ShowAdMobEvent, type ShowAdMobInterstitialAdEvent, type ShowAdMobInterstitialAdOptions, type ShowAdMobOptions, type ShowAdMobParams, type ShowAdMobRewardedAdEvent, type ShowAdMobRewardedAdOptions, Storage, type SubmitGameCenterLeaderBoardScoreResponse, TossPay, type UpdateLocationEventEmitter, appLogin, appsInTossEvent, closeView, contactsViral, eventLog, fetchAlbumPhotos, fetchContacts, generateHapticFeedback, getClipboardText, getCurrentLocation, getDeviceId, getGameCenterGameProfile, getLocale, getNetworkStatus, getOperationalEnvironment, getPlatformOS, getSchemeUri, getTossAppVersion, getTossShareLink, isMinVersionSupported, onVisibilityChangedByTransparentServiceWeb, openCamera, openGameCenterLeaderboard, openURL, saveBase64Data, setClipboardText, setDeviceOrientation, setIosSwipeGestureEnabled, setScreenAwakeMode, setSecureScreen, share, startUpdateLocation, submitGameCenterLeaderBoardScore };
+export { AppsInTossModule, BedrockCoreModule, BedrockModule, type CheckoutPaymentOptions, type CheckoutPaymentResult, type CompletedOrRefundedOrdersResult, type ContactsViralParams, type EventLogParams, type GameCenterGameProfileResponse, GoogleAdMob, type HapticFeedbackType, IAP, AppsInTossModuleInstance as INTERNAL__AppsInTossModule, INTERNAL__appBridgeHandler, INTERNAL__module, type IapCreateOneTimePurchaseOrderOptions, type IapCreateOneTimePurchaseOrderResult, type IapProductListItem, type LoadAdMobEvent, type LoadAdMobInterstitialAdEvent, type LoadAdMobInterstitialAdOptions, type LoadAdMobOptions, type LoadAdMobParams, type LoadAdMobRewardedAdEvent, type LoadAdMobRewardedAdOptions, type NetworkStatus, type Primitive, type SaveBase64DataParams, type ShowAdMobEvent, type ShowAdMobInterstitialAdEvent, type ShowAdMobInterstitialAdOptions, type ShowAdMobOptions, type ShowAdMobParams, type ShowAdMobRewardedAdEvent, type ShowAdMobRewardedAdOptions, Storage, type SubmitGameCenterLeaderBoardScoreResponse, TossPay, type UpdateLocationEventEmitter, appLogin, appsInTossEvent, closeView, contactsViral, eventLog, fetchAlbumPhotos, fetchContacts, generateHapticFeedback, getClipboardText, getCurrentLocation, getDeviceId, getGameCenterGameProfile, getLocale, getNetworkStatus, getOperationalEnvironment, getPlatformOS, getSchemeUri, getTossAppVersion, getTossShareLink, iapCreateOneTimePurchaseOrder, isMinVersionSupported, onVisibilityChangedByTransparentServiceWeb, openCamera, openGameCenterLeaderboard, openURL, processProductGrant, requestOneTimePurchase, saveBase64Data, setClipboardText, setDeviceOrientation, setIosSwipeGestureEnabled, setScreenAwakeMode, setSecureScreen, share, startUpdateLocation, submitGameCenterLeaderBoardScore };