@apps-in-toss/framework 0.0.13 → 0.0.15

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { ComponentType, PropsWithChildren } from 'react';
 import { InitialProps, BedrockProps } from 'react-native-bedrock';
 import { EmitterSubscription } from 'react-native';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { PartnerWebViewScreenProps, ExternalWebViewScreenProps } from '@toss-design-system/react-native';
 import { WebViewProps as WebViewProps$1 } from '@react-native-bedrock/native/react-native-webview';
 
 type AppsInTossProps = Pick<BedrockProps, 'context'>;
@@ -206,6 +207,395 @@ declare function startUpdateLocation(eventParams: {
     options: StartUpdateLocationOptions;
 }): () => void;
 
+/**
+ * @public
+ * @category 토스페이
+ * @name CheckoutPaymentOptions
+ * @description 토스페이 결제를 생성할 때 필요한 옵션 객체예요.
+ * @property {string} orderNo 가맹점의 상품 주문번호예요.
+ * @property {string} productDesc 상품 설명이에요.
+ * @property {number} amount 결제 금액이에요.
+ * @property {number} amountTaxFree 결제 금액 중 비과세 금액이에요.
+ * @property {number} [amountTaxable] 결제 금액 중 과세 금액이에요.
+ * @property {number} [amountVat] 결제 금액 중 부가세예요.
+ * @property {number} [amountServiceFee] 결제 금액 중 봉사료예요.
+ * @property {'TOSS_MONEY' | 'CARD' | null} [enablePayMethods] 결제수단 구분 변수예요. (TOSS_MONEY: 토스머니만, CARD: 카드만, null: 기본 결제수단)
+ * @property {boolean} [cashReceipt] 현금영수증 발급 가능 여부예요.
+ * @property {'CULTURE' | 'GENERAL' | 'PUBLIC_TP'} [cashReceiptTradeOption] 현금영수증 발급 타입이에요. (CULTURE: 문화비, GENERAL: 일반, PUBLIC_TP: 교통비)
+ * @property {'USE' | 'NO_USE'} [installment] 할부를 사용할 지 말 지 여부에요. (USE: 사용, NO_USE: 할부 미사용)
+ */
+interface CheckoutPaymentOptions {
+    /**
+     * 가맹점의 상품 주문번호에요.
+     */
+    orderNo: string;
+    /**
+     * 상품 설명이에요.
+     */
+    productDesc: string;
+    /**
+     * 결제 금액이예요.
+     */
+    amount: number;
+    /**
+     * 결제 금액 중 비과세 금액이에요.
+     */
+    amountTaxFree: number;
+    /**
+     * 결제 금액 중 과세 금액이에요.
+     */
+    amountTaxable?: number;
+    /**
+     * 결제 금액 중 부가세예요.
+     */
+    amountVat?: number;
+    /**
+     * 결제 금액 중 봉사료예요.
+     */
+    amountServiceFee?: number;
+    /**
+     * 결제수단 구분 변수예요.
+     *
+     * - 'TOSS_MONEY': 결제수단 중 토스머니만 노출
+     * - 'CARD': 결제수단 중 카드만 노출
+     * - null: 상점에 설정된 기본 결제 수단 노출
+     */
+    enablePayMethods?: 'TOSS_MONEY' | 'CARD' | null;
+    /**
+     * 현금영수증 발급 가능 여부예요.
+     */
+    cashReceipt?: boolean;
+    /**
+     * 현금영수증 발급 타입이에요.
+     *
+     * - 'CULTURE': 문화비
+     * - 'GENERAL': 일반(기본값)
+     * - 'PUBLIC_TP': 교통비
+     */
+    cashReceiptTradeOption?: 'CULTURE' | 'GENERAL' | 'PUBLIC_TP';
+    /**
+     * 할부를 사용할 지 말 지 여부에요.
+     *
+     * - 'USE': 사용(기본값)
+     * - 'NO_USE': 할부 미사용
+     */
+    installment?: 'USE' | 'NO_USE';
+}
+/**
+ * @public
+ * @category 토스페이
+ * @name checkoutPayment
+ * @description 토스페이 결제를 생성하는 함수예요.
+ *
+ * @param {CheckoutPaymentOptions} options 결제를 생성할 때 필요한 옵션 객체예요.
+ * @param {string} options.orderNo 가맹점의 상품 주문번호예요.
+ * @param {string} options.productDesc 상품 설명이에요.
+ * @param {number} options.amount 결제 금액이에요.
+ * @param {number} options.amountTaxFree 결제 금액 중 비과세 금액이에요.
+ * @param {number} [options.amountTaxable] 결제 금액 중 과세 금액이에요.
+ * @param {number} [options.amountVat] 결제 금액 중 부가세예요.
+ * @param {number} [options.amountServiceFee] 결제 금액 중 봉사료예요.
+ * @param {'TOSS_MONEY' | 'CARD' | null} [options.enablePayMethods] 결제수단 구분 변수예요. (TOSS_MONEY: 토스머니만, CARD: 카드만, null: 기본 결제수단)
+ * @param {boolean} [options.cashReceipt] 현금영수증 발급 가능 여부예요.
+ * @param {'CULTURE' | 'GENERAL' | 'PUBLIC_TP'} [options.cashReceiptTradeOption] 현금영수증 발급 타입이에요. (CULTURE: 문화비, GENERAL: 일반, PUBLIC_TP: 교통비)
+ * @param {'USE' | 'NO_USE'} [options.installment] 할부를 사용할 지 말 지 여부에요. (USE: 사용, NO_USE: 할부 미사용)
+ * @returns {Promise<{ payToken: string }>} 결제 인증 후 발급된 결제 토큰 값이 포함된 객체를 반환해요.
+ *
+ * @example
+ * ### 결제 생성하기
+ *
+ * ```tsx
+ * import { TossPay } from '@apps-in-toss/framework';
+ *
+ * async function handlePayment() {
+ *   try {
+ *     const result = await TossPay.checkoutPayment({
+ *       orderNo: 'ORDER_12345',
+ *       productDesc: '티셔츠',
+ *       amount: 15000,
+ *       amountTaxFree: 0,
+ *       amountTaxable: 13636,
+ *       amountVat: 1364,
+ *       enablePayMethods: 'CARD',
+ *       installment: 'USE'
+ *     });
+ *
+ *     console.log('결제 토큰:', result.payToken);
+ *   } catch (error) {
+ *     console.error('결제 생성에 실패했어요:', error);
+ *   }
+ * }
+ * ```
+ */
+declare function checkoutPayment(options: CheckoutPaymentOptions): Promise<{
+    payToken: string;
+}>;
+
+/**
+ * @public
+ * @category 토스페이
+ * @name ExecutePaymentOptions
+ * @description 생성한 토스페이 결제를 실행할 때 필요한 옵션이에요.
+ * @property {string} orderNo 결제를 생성할 때 사용한 주문번호예요.
+ * @property {string} payToken 결제 인증 과정에서 전달받은 결제 토큰이에요. 결제를 실행할 때 사용해요.
+ */
+interface ExecutePaymentOptions {
+    /**
+     * 결제를 생성할 때 사용한 주문번호예요.
+     */
+    orderNo: string;
+    /**
+     * 결제 인증 과정에서 전달받은 Pay 토큰이에요.
+     */
+    payToken: string;
+}
+/**
+ * @public
+ * @category 토스페이
+ * @name CardExecutePaymentResult
+ * @description 카드로 결제 요청을 실행한 뒤 돌아오는 결제 결과 객체예요. 결제 승인 여부, 결제된 금액, 주문 정보 등을 담고 있어요.
+ * @property {'CARD'} payMethod 결제 수단이에요.
+ * @property {number} code 결제 요청의 결과 코드예요.
+ * @property {'LIVE' | 'TEST'} mode 현재 결제 환경이에요.
+ * @property {string} orderNo 주문번호예요.
+ * @property {number} amount 총 결제 금액이에요.
+ * @property {string} approvalTime 결제가 승인된 시간이에요. (ISO 8601 형식)
+ * @property {string} stateMsg 결제 상태 메시지예요.
+ * @property {number} discountedAmount 적용된 할인 금액이에요.
+ * @property {number} paidAmount 실제 결제된 금액이에요.
+ * @property {string} payToken 결제 요청 시 사용한 Pay 토큰이에요.
+ * @property {string} transactionId 거래 ID예요.
+ * @property {number} cardCompanyCode 카드사 코드예요.
+ * @property {string} cardCompanyName 카드사 이름이에요.
+ * @property {string} cardAuthorizationNo 카드사 승인 번호예요. (라이브 결제 환경에서만 확인 가능해요)
+ * @property {number} spreadOut 할부 개월 수예요. (5만원 미만 금액 및 일시불 결제의 경우에는 `0`)
+ * @property {boolean} noInterest 무이자 할부 여부예요.
+ * @property {string} salesCheckLinkUrl 결제 내역을 확인할 수 있는 매출전표 URL이에요.
+ * @property {'CREDIT' | 'CHECK' | 'PREPAYMENT'} cardMethodType 카드 유형이에요.
+ * @property {string} cardNumber 마스킹된 카드 번호예요. (`****-****-****-1234` 형식)
+ * @property {string} cardNum4Print 카드 번호의 마지막 4자리예요.
+ * @property {string} cardBinNumber 카드 BIN 번호예요.
+ */
+interface CardExecutePaymentResult {
+    /**
+     * 결제 수단이에요.
+     */
+    payMethod: 'CARD';
+    /**
+     * 결제 요청의 결과 코드예요.
+     */
+    code: number;
+    /**
+     * 현재 결제 환경이에요.
+     *
+     * - `LIVE`: 실제 환경
+     * - `TEST`: 테스트 환경
+     */
+    mode: 'LIVE' | 'TEST';
+    /**
+     * 주문번호예요.
+     */
+    orderNo: string;
+    /**
+     * 총 결제 금액이에요.
+     */
+    amount: number;
+    /**
+     * 결제가 승인된 시간이에요. (ISO 8601 형식)
+     */
+    approvalTime: string;
+    /**
+     * 결제 상태 메시지예요.
+     */
+    stateMsg: string;
+    /**
+     * 적용된 할인 금액이에요.
+     */
+    discountedAmount: number;
+    /**
+     * 실제 결제된 금액이에요.
+     */
+    paidAmount: number;
+    /**
+     * 결제 요청 시 사용한 Pay 토큰이에요.
+     */
+    payToken: string;
+    /**
+     * 거래 ID예요.
+     */
+    transactionId: string;
+    /**
+     * 카드사 코드예요.
+     */
+    cardCompanyCode: number;
+    /**
+     * 카드사 이름이에요.
+     */
+    cardCompanyName: string;
+    /**
+     * 카드사 승인 번호예요. (라이브 결제 환경에서만 확인 가능해요)
+     */
+    cardAuthorizationNo: string;
+    /**
+     * 할부 개월 수예요. (5만원 미만 금액 및 일시불 결제의 경우에는 `0`)
+     */
+    spreadOut: number;
+    /**
+     * 무이자 할부 여부예요.
+     */
+    noInterest: boolean;
+    /**
+     * 결제 내역을 확인할 수 있는 매출전표 URL이에요.
+     */
+    salesCheckLinkUrl: string;
+    /**
+     * 카드 유형이에요.
+     *
+     * - 'CREDIT': 신용카드
+     * - 'CHECK': 체크카드
+     * - 'PREPAYMENT': 선불카드
+     */
+    cardMethodType: 'CREDIT' | 'CHECK' | 'PREPAYMENT';
+    /**
+     * 마스킹된 카드 번호예요. (`****-****-****-1234` 형식)
+     */
+    cardNumber: string;
+    /**
+     * 카드 사용자 구분을 나타내는 값이에요.
+     *
+     * - 'PERSONAL': 개인 카드
+     * - 'PERSONAL_FAMILY': 가족 카드
+     * - 'CORP_PERSONAL': 법인지정 결제계좌 (임직원)
+     * - 'CORP_PRIVATE': 법인 공용
+     * - 'CORP_COMPANY': 법인지정 결제계좌 회사 (하나카드 Only)
+     */
+    cardUserType: 'PERSONAL' | 'PERSONAL_FAMILY' | 'CORP_PERSONAL' | 'CORP_PRIVATE' | 'CORP_COMPANY';
+    /**
+     * 카드 번호의 마지막 4자리예요.
+     */
+    cardNum4Print: string;
+    /**
+     * 카드 BIN 번호예요.
+     */
+    cardBinNumber: string;
+}
+/**
+ * @public
+ * @category 토스페이
+ * @name TossMoneyExecutePaymentResult
+ * @description 토스머니로 결제 요청을 실행한 뒤 돌아오는 결제 결과 객체예요. 결제 승인 여부, 결제된 금액, 주문 정보 등을 담고 있어요.
+ * @property {'TOSS_MONEY'} payMethod 결제 수단이에요.
+ * @property {number} code 결제 요청의 결과 코드예요.
+ * @property {'LIVE' | 'TEST'} mode 현재 결제 환경이에요.
+ * @property {string} orderNo 주문번호예요.
+ * @property {number} amount 총 결제 금액이에요.
+ * @property {string} approvalTime 결제가 승인된 시간이에요. (ISO 8601 형식)
+ * @property {string} stateMsg 결제 상태 메시지예요.
+ * @property {number} discountedAmount 적용된 할인 금액이에요.
+ * @property {number} paidAmount 실제 결제된 금액이에요.
+ * @property {string} payToken 결제 요청 시 사용한 Pay 토큰이에요.
+ * @property {string} transactionId 거래 ID예요.
+ * @property {string} cashReceiptMgtKey 현금영수증 관리번호 식별값이에요.
+ * @property {string} accountBankName 결제된 은행의 코드예요.
+ * @property {string} accountNumber 결제된 계좌번호예요.
+ */
+interface TossMoneyExecutePaymentResult {
+    /**
+     * 결제에 사용된 결제 수단이에요.
+     */
+    payMethod: 'TOSS_MONEY';
+    /**
+     * 결제 요청의 결과 코드예요.
+     */
+    code: number;
+    /**
+     * 현재 결제 환경이에요.
+     *
+     * - `LIVE`: 실제 환경
+     * - `TEST`: 테스트 환경
+     */
+    mode: 'LIVE' | 'TEST';
+    /**
+     * 결제 승인된 상품의 주문번호예요.
+     */
+    orderNo: string;
+    /**
+     * 결제 승인된 상품의 총 결제 금액이에요.
+     */
+    amount: number;
+    /**
+     * 결제가 승인된 시간이에요. (ISO 8601 형식)
+     */
+    approvalTime: string;
+    /**
+     * 결제 상태 메시지예요.
+     */
+    stateMsg: string;
+    /**
+     * 적용된 할인 금액이에요.
+     */
+    discountedAmount: number;
+    /**
+     * 실제 결제 승인된 금액이에요.
+     */
+    paidAmount: number;
+    /**
+     * 결제 요청 시 사용한 Pay 토큰이에요.
+     */
+    payToken: string;
+    /**
+     * 거래 ID예요.
+     */
+    transactionId: string;
+    /**
+     * 현금영수증 관리번호 식별값이에요.
+     */
+    cashReceiptMgtKey: string;
+    /**
+     * 결제된 은행의 코드예요.
+     */
+    accountBankName: string;
+    /**
+     * 결제된 계좌번호예요.
+     */
+    accountNumber: string;
+}
+/**
+ * @public
+ * @category 토스페이
+ * @name executePayment
+ * @description 구매자가 결제를 시도하면, 먼저 결제 정보를 생성하고 인증을 받아요. 이때 결제 상태는 '대기' 중이에요. 이후 결제를 실제로 승인하려면 주어진 주문번호와 결제 토큰을 사용해서 이 함수로 생성된 결제를 승인해요. 결제 승인이 완료되면, 구매자의 결제 수단(예: 카드, 계좌)에서 실제로 금액이 출금돼요. 이 함수를 호출하지 않으면 결제가 자동으로 만료되고, 출금도 발생하지 않아요.
+ *
+ * @param {ExecutePaymentOptions} options 결제를 실행할 때 필요한 옵션이에요.
+ * @param {string} options.orderNo 결제를 생성할 때 사용한 주문번호예요.
+ * @param {string} options.payToken 결제 인증 과정에서 전달받은 결제 토큰이에요. 결제를 실행할 때 사용해요.
+ * @returns {Promise<CardExecutePaymentResult | TossMoneyExecutePaymentResult>} 결제 결과 객체를 반환해요. 자세한 내용은 [카드 결제 결과](reference/framework/토스페이/CardExecutePaymentResult.html) 또는 [토스머니 결제 결과](reference/framework/토스페이/TossMoneyExecutePaymentResult.html)를 참고하세요.
+ *
+ * @example
+ *
+ * ### 카드 결제 실행하기
+ *
+ * ```tsx
+ * import { TossPay } from '@apps-in-toss/framework';
+ *
+ * async function handlePayment() {
+ *   try {
+ *     const payToken = 'PAY_TOKEN_12345'; // 결제 인증 후 받은 토큰
+ *
+ *     const result = await TossPay.executePayment({
+ *       orderNo: 'ORDER_12345',
+ *       payToken,
+ *     });
+ *
+ *     console.log('결제가 완료되었어요:', result);
+ *   } catch (error) {
+ *     console.error('결제에 실패했어요:', error);
+ *   }
+ * }
+ * ```
+ */
+declare function executePayment(options: ExecutePaymentOptions): Promise<CardExecutePaymentResult | TossMoneyExecutePaymentResult>;
+
 /**
  * @public
  * @category 클립보드
@@ -637,13 +1027,40 @@ declare function appLogin(): Promise<{
  */
 declare function getOperationalEnvironment(): 'toss' | 'sandbox';
 
-interface WebViewProps extends Omit<WebViewProps$1, 'cacheEnabled' | 'source' | 'sharedCookiesEnabled' | 'thirdPartyCookiesEnabled' | 'injectedJavaScriptBeforeContentLoaded'> {
-    local: {
-        port: number;
-        host: number;
-    };
+/**
+ * @public
+ * @category 토스페이
+ * @name TossPay
+ * @description 토스페이 결제 관련 함수를 모아둔 객체예요.
+ * @property {typeof checkoutPayment} [checkoutPayment] 토스페이 결제를 생성하는 함수예요. 자세한 내용은 [checkoutPayment](reference/framework/토스페이/checkoutPayment)를 참고하세요.
+ * @property {typeof executePayment} [executePayment] 토스페이 결제를 실행하는 함수예요. 자세한 내용은 [executePayment](reference/framework/토스페이/executePayment)를 참고하세요.
+ */
+declare const TossPay: {
+    checkoutPayment: typeof checkoutPayment;
+    executePayment: typeof executePayment;
+};
+
+type GameWebViewProps$1 = WebViewProps$1;
+
+type WebViewProps = PartnerWebViewProps | ExternalWebViewProps | GameWebViewProps;
+interface PartnerWebViewProps extends Omit<PartnerWebViewScreenProps, InternalProps> {
+    type: 'partner';
+    local: LocalNetwork;
+}
+interface ExternalWebViewProps extends Omit<ExternalWebViewScreenProps, InternalProps> {
+    type: 'external';
+    local: LocalNetwork;
+}
+interface GameWebViewProps extends Omit<GameWebViewProps$1, InternalProps> {
+    type: 'game';
+    local: LocalNetwork;
+}
+interface LocalNetwork {
+    port: number;
+    host: string;
 }
-declare function WebView({ local, onMessage, ...props }: WebViewProps): react_jsx_runtime.JSX.Element;
+type InternalProps = 'source' | 'cacheEnabled' | 'sharedCookiesEnabled' | 'thirdPartyCookiesEnabled' | 'injectedJavaScriptBeforeContentLoaded';
+declare function WebView({ type, local, onMessage, ...props }: WebViewProps): react_jsx_runtime.JSX.Element;
 
 type UseGeolocationOptions = Omit<StartUpdateLocationOptions, 'callback'>;
 /**
@@ -695,4 +1112,4 @@ declare const env: {
     getDeploymentId: () => string | undefined;
 };
 
-export { Accuracy, AppsInToss, type ContactEntity, type FetchAlbumPhotosOptions, type GetCurrentLocationOptions, type ImageResponse, type Location, type LocationCoords, type OpenCameraOptions, type StartUpdateLocationOptions, type StartUpdateLocationSubscription, type UpdateLocationEventEmitter, type UseGeolocationOptions, WebView, type WebViewProps, appLogin, env, fetchAlbumPhotos, fetchContacts, getClipboardText, getCurrentLocation, getOperationalEnvironment, openCamera, setClipboardText, startUpdateLocation, useGeolocation };
+export { Accuracy, AppsInToss, type ContactEntity, type ExternalWebViewProps, type FetchAlbumPhotosOptions, type GameWebViewProps, type GetCurrentLocationOptions, type ImageResponse, type Location, type LocationCoords, type OpenCameraOptions, type PartnerWebViewProps, type StartUpdateLocationOptions, type StartUpdateLocationSubscription, TossPay, type UpdateLocationEventEmitter, type UseGeolocationOptions, WebView, type WebViewProps, appLogin, env, fetchAlbumPhotos, fetchContacts, getClipboardText, getCurrentLocation, getOperationalEnvironment, openCamera, setClipboardText, startUpdateLocation, useGeolocation };