@tosspayments/tosspayments-sdk 2.6.0 → 2.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tosspayments/tosspayments-sdk",
   "description": "TossPayments.js Tosspayments SDK.",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
   "types": "types/index.d.ts",
@@ -26,7 +26,7 @@
     "@rollup/plugin-commonjs": "^21.0.1",
     "@rollup/plugin-typescript": "^8.3.0",
     "@tosspayments/sdk-loader": "workspace:packages/sdk-loader",
-    "@tosspayments/standard-public-interfaces": "2.6.0",
+    "@tosspayments/standard-public-interfaces": "2.9.0",
     "happy-dom": "^14.12.3",
     "prettier": "^2.0.2",
     "rollup": "^2.60.0",

package/types/index.d.ts

@@ -443,6 +443,40 @@ interface WidgetPaymentRequestWindowOptions {
     } | null;
 }
 
+interface WidgetPaymentWindow {
+    /**
+     * 결제창의 이벤트를 구독합니다.
+     *
+     * @param {'paymentRequest'} eventName 구독할 이벤트입니다. `paymentRequest` 이벤트로 구매자의 결제 요청을 수신하세요.
+     * @param {function} callback 이벤트가 일어나면 호출되는 콜백 함수입니다.
+     *
+     * @example
+     *  ```javascript
+     *  paymentWindow.on('paymentRequest', ({ paymentMethod }) => {
+     *    // 결제 요청 처리
+     *  });
+     * ```
+     *
+     * @throws {@link PublicError.Widgets.InvalidEventParameterError} eventName이 유효하지 않은 경우
+     * @throws {@link PublicError.Widgets.InvalidCallbackParameterError} callback이 유효하지 않은 경우
+     * @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
+     */
+    on: (eventName: 'paymentRequest', callback: (params: {
+        paymentMethod: WidgetSelectedPaymentMethod;
+    }) => Promise<void>) => void;
+    /**
+     * 결제창을 제거합니다.
+     *
+     * @example
+     *  ```javascript
+     *  await paymentWindow.destroy();
+     * ```
+     *
+     * @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
+     */
+    destroy: () => Promise<void>;
+}
+
 /**
  * 결제 UI 위젯을 렌더링합니다
  * @param {object} params 결제 UI 렌더링 정보입니다.
@@ -695,6 +729,46 @@ type RequestPaymentWindowWithPromise = (paymentRequest: WidgetPaymentRequestWind
  */
 type RequestPaymentWindowWithRedirection = (paymentRequest: WithRedirection<WidgetPaymentRequestWindow>, options?: WidgetPaymentRequestWindowOptions) => Promise<void>;
 
+/**
+ * 결제창을 렌더링합니다
+ * @param {object} params 결제창 렌더링 정보입니다.
+ *
+ * @returns 반환되는 결제창 객체로 아래 메서드를 호출할 수 있어요.
+ *
+ * @example
+ *  ```javascript
+ *  const paymentWindow = await widgets.renderPaymentWindow({
+ *    variantKey: {
+ *      paymentMethod: "CUSTOM-1",
+ *      agreement: "AGREEMENT",
+ *    },
+ *  });
+ * ```
+ *
+ * @throws {@link PublicError.Widgets.PaymentWindowAlreadyRenderedError} 이미 결제창이 렌더링 된 경우
+ * @throws {@link PublicError.Widgets.UserCancelError} 사용자가 결제창 렌더링을 취소한 경우
+ * @throws {@link PublicError.Widgets.NotSetupAmountError} 결제금액이 설정되지 않은 경우
+ * @throws {@link PublicError.Widgets.InvalidVariantKeyError} variantKey가 유효하지 않은 경우
+ * @throws {@link PublicError.Widgets.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
+ * @throws {@link PublicError.Widgets.InvalidParametersError} 파라미터가 올바르지 않은 경우
+ * @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
+ */
+type RenderPaymentWindow = (params?: {
+    /**
+     * 결제위젯 UI의 variantKey 정보입니다. [결제위젯 어드민](https://dashboard.tosspayments.com/payment-widget-service/)에서 확인할 수 있어요.
+     */
+    variantKey?: {
+        /**
+         * 결제수단 UI의 variantKey입니다.
+         */
+        paymentMethod?: string;
+        /**
+         * 약관 UI의 variantKey입니다.
+         */
+        agreement?: string;
+    };
+}) => Promise<WidgetPaymentWindow>;
+
 interface TossPaymentsWidgets {
     /**
      * 주문의 결제 금액을 설정합니다. [자세히 >](#widgetssetamount)
@@ -709,13 +783,20 @@ interface TossPaymentsWidgets {
      */
     requestPayment: RequestPayment$2;
     /**
+     *
      * 위젯 결제창으로 결제를 요청합니다. [자세히 >](#widgetsrequestpaymentwindow)
+     * @deprecated renderPaymentWindow API로 대체됩니다.
+     * @ignore
      */
     requestPaymentWindow: RequestPaymentWindow;
     /**
      * 약관 UI를 렌더링합니다. [자세히 >](#widgetsrenderagreement)
      */
     renderAgreement: RenderAgreement;
+    /**
+     * 결제창을 렌더링합니다. [자세히 >](#widgetsrenderpaymentwindow)
+     */
+    renderPaymentWindow: RenderPaymentWindow;
 }
 
 interface BrandpayAmount extends Amount {
@@ -1391,6 +1472,10 @@ interface TransferPaymentRequest extends PaymentRequest {
          * 문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다.
          */
         isCulturalExpenses?: boolean | null;
+        /**
+         * @ignore
+         */
+        encryptedCustomerCi?: string | null;
     } | null;
 }
 
@@ -1418,9 +1503,9 @@ interface ForeignEasyPayPaymentRequest extends PaymentRequest {
      */
     foreignEasyPay: {
         /**
-         * 해외간편결제 코드입니다. 현재는 `PAYPAL`만 지원하고 있어요.
+         * 해외간편결제 코드입니다. 현재는 `PAYPAL`, `PAYPAY`만 지원하고 있어요.
          */
-        provider: 'PAYPAL' | 'GCASH' | 'TOUCHNGO' | 'BOOST' | 'BPI' | 'BILLEASE' | 'DANA' | 'ALIPAYHK' | 'TRUEMONEY' | 'RABBIT_LINE_PAY' | 'ALIPAY';
+        provider: 'PAYPAL' | 'GCASH' | 'TOUCHNGO' | 'BOOST' | 'BPI' | 'BILLEASE' | 'DANA' | 'ALIPAYHK' | 'TRUEMONEY' | 'RABBIT_LINE_PAY' | 'ALIPAY' | 'PAYPAY';
         /**
          * 구매자가 위치한 국가입니다. ISO-3166의 두 자리 국가 코드를 입력하세요.
          */
@@ -1595,6 +1680,15 @@ interface TransferBillingAuthRequest extends BaseBillingAuthRequest {
      * 자동결제(빌링)에 등록할 결제수단입니다.
      */
     method: 'TRANSFER';
+    /**
+     * @ignore
+     */
+    transfer?: {
+        /**
+         * @ignore
+         */
+        encryptedCustomerCi?: string | null;
+    } | null;
 }
 /**
  * 자동결제(빌링) 등록 요청 정보입니다. 토스페이먼츠 자동결제는 신용·체크카드, 계좌이체를 지원해요.