@tosspayments/tosspayments-sdk 2.2.0 → 2.2.1

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.2.1](https://github.com/tosspayments/browser-sdk/compare/@tosspayments/tosspayments-sdk@2.2.0...@tosspayments/tosspayments-sdk@2.2.1) (2024-07-08)
+
+
+### Bug Fixes
+
+* **tosspayments-sdk:** 위젯 연동시 필요한 type export ([#116](https://github.com/tosspayments/browser-sdk/issues/116)) ([724501c](https://github.com/tosspayments/browser-sdk/commit/724501c8ad79e395d29b0b11191d6e296d0f8134))
+
+
+
+
+
 # [2.2.0](https://github.com/tosspayments/browser-sdk/compare/@tosspayments/tosspayments-sdk@2.1.0...@tosspayments/tosspayments-sdk@2.2.0) (2024-07-03)
 
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tosspayments/tosspayments-sdk",
   "description": "TossPayments.js Tosspayments SDK.",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
   "types": "types/index.d.ts",
@@ -21,7 +21,7 @@
     "@rollup/plugin-commonjs": "^21.0.1",
     "@rollup/plugin-typescript": "^8.3.0",
     "@tosspayments/sdk-loader": "2.0.1",
-    "@tosspayments/standard-public-interfaces": "^2.0.0",
+    "@tosspayments/standard-public-interfaces": "2.0.2",
     "happy-dom": "^14.12.3",
     "prettier": "^2.0.2",
     "rollup": "^2.60.0",
@@ -38,5 +38,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "a07117f1b6f50632b6c7ce46931becddb1cbe69e"
+  "gitHead": "32f15f03267096258d766409ce4c69f572cd5828"
 }

package/types/index.d.ts

@@ -14,18 +14,18 @@ interface WidgetPaymentMethodWidget {
      *
      * @example
      *  ```javascript
-     *  widgets.on('paymentMethodSelect', selectedPaymentMethod => {
-          if (paymentMethodSelected.code === '문화바우처') {
-            // 문화바우처 안내사항 노출
-          }
-          
-          if (paymentMethodSelected.code === '카드') {
+     *  paymentMethodWidget.on('paymentMethodSelect', selectedPaymentMethod => {
+          if (selectedPaymentMethod.code === '카드') {
             // 카드 안내사항 노출
           }
+          if (selectedPaymentMethod.code === '문화바우처') {
+            // 커스텀 결제수단 (결제위젯 Pro 플랜 기능)
+            // 문화바우처 안내사항 노출
+          }
         });
      * ```
      *
-     * @param {'paymentMethodSelect'} eventName 구독할 이벤트입니다. `paymentMethodSelect` 이벤트로 구매자가 선택한 결제수단 정보를 확인하세요.
+     * @param {'paymentMethodSelect'} eventName 구독할 이벤트입니다. `paymentMethodSelect` 이벤트로 구매자가 선택한 결제수단 코드를 확인하세요. 일반결제는 [결제수단 ENUM 코드](/codes/enum-codes#결제수단-타입)가 응답돼요. 결제위젯 Pro 플랜으로 [커스텀 결제수단](/guides/v2/payment-widget/pro/integration-custom)을 연동했다면 결제위젯 어드민에서 설정한 `key` 값이 응답돼요.
      * @param {function} callback 이벤트가 일어나면 호출되는 콜백 함수입니다.
      *
      * @throws {@link PublicError.Widgets.InvalidEventParameterError} eventName이 유효하지 않은 경우
@@ -216,6 +216,9 @@ interface WidgetPaymentRequest {
      * 구매자가 해외간편결제를 선택하면 결제에 적용되는 옵션입니다.
      */
     foreignEasyPay?: {
+        /**
+         * 구매자가 위치한 국가입니다. ISO-3166의 두 자리 국가 코드를 입력하세요.
+         */
         country: string;
         /**
          * 구매 상품 정보입니다. 여러 가지의 상품을 결제했다면 각 상품의 정보를 입력하세요. 예를 들어, 구매자가 세 가지 종류의 상품을 구매했다면 배열의 길이는 3이어야 합니다.
@@ -307,7 +310,7 @@ interface Amount {
      */
     value: number;
     /**
-     * 결제 통화입니다.
+     * 결제 통화입니다. 일반결제는 `KRW`만 지원합니다. 해외 간편결제(PayPal)는 `USD`만 지원합니다.
      */
     currency: string;
 }
@@ -458,9 +461,9 @@ type RequestPaymentWithPromise$1 = (paymentRequest: WidgetPaymentRequest) => Pro
 /**
  * @docsAlias Redirect 방식
  *
- * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 메서드 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
  * ```plain theme="grey" copyable="false"
- * {successUrl}?amount={AMOUNT}&orderId={ORDER_ID}&paymentKey={PAYMENT_KEY}
+ * {successUrl}?paymentType={PAYMENT_TYPE}&amount={AMOUNT}&orderId={ORDER_ID}&paymentKey={PAYMENT_KEY}
  * ```
  * 결제 요청이 실패하면 파라미터로 설정한 `failUrl`로 이동해요. 쿼리 파라미터로 에러 코드와 메시지를 확인하세요.
  * ```plain theme="grey" copyable="false"
@@ -526,6 +529,9 @@ interface TossPaymentsWidgets {
 }
 
 interface BrandpayAmount extends Amount {
+    /**
+     * 결제 통화입니다. 브랜드페이는 `KRW` 결제만 지원합니다.
+     */
     currency: 'KRW';
 }
 
@@ -565,6 +571,9 @@ interface BrandpayRequestPaymentResult {
      * 주문번호입니다. 결제를 요청할 때 호출한 `requestPayment()` 메서드로 넘긴 `orderId` 값과 같은지 확인하세요.
      */
     orderId: string;
+    /**
+     * 결제 금액 정보입니다. `requestPayment()` 메서드로 넘긴 `amount` 값과 같은지 확인하세요.
+     */
     amount: BrandpayAmount;
 }
 
@@ -588,7 +597,7 @@ interface BrandpayRequestPaymentResult {
 type RequestPayment$1 = RequestPaymentWithRedirection & RequestPaymentWithPromise;
 /**
  * @docsAlias Redirect 방식
- * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [브랜드페이 결제 승인 API](/reference/brandpay#결제-승인)를 호출해서 결제를 완료하세요.
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 메서드 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [브랜드페이 결제 승인 API](/reference/brandpay#결제-승인)를 호출해서 결제를 완료하세요.
  * ```plain theme="grey" copyable="false"
  * {successUrl}?amount={AMOUNT}&orderId={ORDER_ID}&paymentKey={PAYMENT_KEY}
  * ```
@@ -799,7 +808,8 @@ interface PaymentRequest {
     taxFreeAmount?: number;
     /**
      * 결제창이 열리는 프레임입니다.
-     * `iframe` 또는 현재 브라우저 화면(`self`)에서 등록창을 열 수 있어요. 기본 값은 `iframe`입니다.
+     * `iframe` 또는 현재 브라우저 화면(`self`)에서 결제창을 열 수 있어요. 기본 값은 `iframe`입니다.
+     * 모바일 웹에서는 `windowTarget` 값이 작동하지 않고 화면이 이동합니다.
      */
     windowTarget?: 'iframe' | 'self';
 }
@@ -1065,7 +1075,7 @@ interface ForeignEasyPayPaymentRequest extends PaymentRequest {
          */
         provider: string;
         /**
-         * 구매자가 결제한 국가입니다. ISO-3166의 두 자리 국가 코드를 입력하세요.
+         * 구매자가 위치한 국가입니다. ISO-3166의 두 자리 국가 코드를 입력하세요.
          */
         country: string;
         /**
@@ -1194,8 +1204,9 @@ interface BillingAuthRequest {
      */
     customerEmail?: string;
     /**
-     * 카드 등록창이 열리는 프레임입니다. iframe 또는 현재 브라우저 화면(self)에서 등록창을 열 수 있습니다. 기본 값은 `iframe`입니다.
-     * 모바일 웹에서는 windowTarget 값과 상관없이 항상 새로운 결제창으로 이동합니다.
+     * 결제창이 열리는 프레임입니다.
+     * `iframe` 또는 현재 브라우저 화면(`self`)에서 등록창을 열 수 있어요. 기본 값은 `iframe`입니다.
+     * 모바일 웹에서는 `windowTarget` 값이 작동하지 않고 화면이 이동합니다.
      *
      * @default 'iframe'
      */
@@ -1249,7 +1260,7 @@ type RequestPayment = RequestCardPaymentWithRedirection & RequestCardPaymentWith
 type RequestCardPaymentWithPromise = (paymentRequest: CardPaymentRequest) => Promise<RequestPaymentResult>;
 /**
  * @docsAlias 카드(Redirect 방식)
- * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 메서드 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
  * ```plain theme="grey" copyable="false"
  * {successUrl}?amount={AMOUNT}&orderId={ORDER_ID}&paymentKey={PAYMENT_KEY}
  * ```
@@ -1318,7 +1329,7 @@ type RequestCardPaymentWithRedirection = (paymentRequest: WithRedirection<CardPa
 type RequestVirtualAccountPaymentWithPromise = (paymentRequest: VirtualAccountPaymentRequest) => Promise<RequestPaymentResult>;
 /**
  * @docsAlias 가상계좌(Redirect 방식)
- * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 메서드 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
  * ```plain theme="grey" copyable="false"
  * {successUrl}?amount={AMOUNT}&orderId={ORDER_ID}&paymentKey={PAYMENT_KEY}
  * ```
@@ -1386,7 +1397,7 @@ type RequestVirtualAccountPaymentWithRedirection = (paymentRequest: WithRedirect
 type RequestTransferPaymentWithPromise = (paymentRequest: TransferPaymentRequest) => Promise<RequestPaymentResult>;
 /**
  * @docsAlias 계좌이체(Redirect 방식)
- * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 메서드 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
  * ```plain theme="grey" copyable="false"
  * {successUrl}?amount={AMOUNT}&orderId={ORDER_ID}&paymentKey={PAYMENT_KEY}
  * ```
@@ -1447,7 +1458,7 @@ type RequestTransferPaymentWithRedirection = (paymentRequest: WithRedirection<Tr
 type RequestMobilePhonePaymentWithPromise = (paymentRequest: MobilePhonePaymentRequest) => Promise<RequestPaymentResult>;
 /**
  * @docsAlias 휴대폰 결제(Redirect 방식)
- * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 메서드 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
  * ```plain theme="grey" copyable="false"
  * {successUrl}?amount={AMOUNT}&orderId={ORDER_ID}&paymentKey={PAYMENT_KEY}
  * ```
@@ -1502,7 +1513,7 @@ type RequestMobilePhonePaymentWithRedirection = (paymentRequest: WithRedirection
 type RequestGiftCertificatePaymentWithPromise = (paymentRequest: GiftCertificatePaymentRequest) => Promise<RequestPaymentResult>;
 /**
  * @docsAlias 상품권(Redirect 방식)
- * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 메서드 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
  * ```plain theme="grey" copyable="false"
  * {successUrl}?amount={AMOUNT}&orderId={ORDER_ID}&paymentKey={PAYMENT_KEY}
  * ```
@@ -1561,7 +1572,7 @@ type RequestGiftCertificatePaymentWithRedirection = (paymentRequest: WithRedirec
 type RequestForeignEasyPayPaymentWithPromise = (paymentRequest: ForeignEasyPayPaymentRequest) => Promise<RequestPaymentResult>;
 /**
  * @docsAlias 해외 간편결제(Redirect 방식)
- * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 메서드 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
  * ```plain theme="grey" copyable="false"
  * {successUrl}?amount={AMOUNT}&orderId={ORDER_ID}&paymentKey={PAYMENT_KEY}
  * ```
@@ -1652,8 +1663,13 @@ interface TossPaymentsInstance {
      * ```javascript
      * // 회원 결제
      * const widgets = tossPayments.widgets({ customerKey });
+     *
      * // 비회원 결제
-     * // const payment = tossPayments.widgets({ customerKey: TossPayments.ANONYMOUS });
+     * // 스크립트 태그 연동방식
+     * const widgets = tossPayments.widgets({ customerKey: TossPayments.ANONYMOUS });
+     * // 모듈 임포트 연동방식
+     * import { ANONYMOUS } from "@tosspayments/tosspayments-sdk";
+     * const widgets = tossPayments.widgets({ customerKey: ANONYMOUS });
      * ```
      * @param {WidgetSDKInitParams} params 결제위젯 초기화 정보입니다.
      *
@@ -1687,14 +1703,10 @@ interface TossPaymentsInstance {
      * @throw {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
      * @example
      * ```javascript
-     * // 회원 결제
      * const payment = tossPayments.payment({ customerKey });
-     *
-     * //비회원 결제
-     * // const payment = tossPayments.payment({ customerKey: TossPayments.ANONYMOUS });
      * ```
+     * @param {PaymentGatewaySDKInitParams} params 결제창 초기화 정보입니다.
      * @returns 아래 메서드를 호출할 수 있는 결제창 객체를 반환합니다.
-     * @param {PaymentGatewaySDKInitParams} 결제창 초기화 정보입니다.
      *
      */
     payment: (params: PaymentGatewaySDKInitParams) => TossPaymentsPaymentGateway;
@@ -1702,8 +1714,14 @@ interface TossPaymentsInstance {
 /**
  * @example
  * ```javascript
+ * // 스크립트 태그 연동방식
  * const tossPayments = TossPayments("<WidgetClientKey />");
+ *
+ * // 모듈 임포트 연동방식
+ * import { loadTossPayments } from "@tosspayments/tosspayments-sdk"
+ * const tossPayments = await loadTossPayments("<WidgetClientKey />");
  * ```
+ *
  * @param {string} clientKey 토스페이먼츠 발급하는 클라이언트 키입니다. 개발자센터의 [API 키 메뉴](https://developers.tosspayments.com/my/api-keys)에서 확인할 수 있어요.
  *
  * 결제위젯을 연동한다면 [결제위젯 연동 키](/reference/using-api/api-keys#결제위젯-연동-키)를 사용하세요. 결제창, 자동결제(빌링)을 연동한다면 [API 개별 연동 키](/reference/using-api/api-keys#api-개별-연동-키)를 사용하세요.
@@ -1722,7 +1740,7 @@ interface BrandpaySDKInitParams {
     /**
      * 브랜드페이 결제 과정에서 [Access Token 발급](/guides/v2/brandpay/auth)을 위해 필요한 URL입니다. Access Token은 브랜드페이 고객을 식별하고 고객의 결제 권한을 증명합니다. 값을 넣지 않으면 개발자센터의 브랜드페이 메뉴에 최초로 등록한 리다이렉트 URL이 기본값으로 들어갑니다.
      *
-     * \* 브랜드페이 메뉴에 두 개 이상의 리다이렉트 URL을 등록한 상점은 각 도메인에 맞는 redirectUrl 값을 필수로 추가하세요.
+     * \* 브랜드페이 메뉴에 두 개 이상의 리다이렉트 URL을 등록한 상점은 각 도메인에 맞는 `redirectUrl` 값을 필수로 추가하세요.
      */
     redirectUrl?: string;
 }
@@ -1743,7 +1761,7 @@ interface WidgetSDKInitParams {
         /**
          * 브랜드페이 결제 과정에서 [Access Token 발급](/guides/v2/brandpay/auth)을 위해 필요한 URL입니다. Access Token은 브랜드페이 고객을 식별하고 고객의 결제 권한을 증명합니다. 값을 넣지 않으면 개발자센터의 브랜드페이 메뉴에 최초로 등록한 리다이렉트 URL이 기본값으로 들어갑니다.
          *
-         * \* 브랜드페이 메뉴에 두 개 이상의 리다이렉트 URL을 등록한 상점은 각 도메인에 맞는 redirectUrl 값을 필수로 추가하세요.
+         * \* 브랜드페이 메뉴에 두 개 이상의 리다이렉트 URL을 등록한 상점은 각 도메인에 맞는 `redirectUrl` 값을 필수로 추가하세요.
          */
         redirectUrl?: string;
     };
@@ -1764,4 +1782,4 @@ declare function loadTossPayments(clientKey: TosspaymentsParams[0], loadOptions?
 
 declare const ANONYMOUS = "@@ANONYMOUS";
 
-export { ANONYMOUS, clearTossPayments, loadTossPayments };
+export { ANONYMOUS, type WidgetAgreementStatus, type WidgetAgreementWidget, type WidgetPaymentMethodWidget, type WidgetSelectedPaymentMethod, clearTossPayments, loadTossPayments };