@tosspayments/tosspayments-sdk 2.4.1 → 2.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tosspayments/tosspayments-sdk",
   "description": "TossPayments.js Tosspayments SDK.",
-  "version": "2.4.1",
+  "version": "2.6.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.4.2",
+    "@tosspayments/standard-public-interfaces": "2.6.0",
     "happy-dom": "^14.12.3",
     "prettier": "^2.0.2",
     "rollup": "^2.60.0",

package/types/index.d.ts

@@ -277,7 +277,7 @@ interface WidgetPaymentRequest {
          */
         products?: Array<{
             /**
-             * 상품명입니다.
+             * 상품명입니다. 최대 길이는 100자입니다.
              */
             name: string;
             /**
@@ -421,6 +421,28 @@ type WidgetPaymentResult = {
     amount: Amount;
 };
 
+interface WidgetPaymentRequestWindow extends WidgetPaymentRequest {
+    /**
+     * 결제 금액 정보입니다.
+     */
+    amount: Amount;
+}
+interface WidgetPaymentRequestWindowOptions {
+    /**
+     * 결제위젯 UI의 variantKey 정보입니다. [결제위젯 어드민](https://dashboard.tosspayments.com/payment-widget-service/)에서 확인할 수 있어요.
+     */
+    variantKey?: {
+        /**
+         * 결제수단 UI의 variantKey입니다.
+         */
+        paymentMethod?: string | null;
+        /**
+         * 약관 UI의 variantKey입니다.
+         */
+        agreement?: string | null;
+    } | null;
+}
+
 /**
  * 결제 UI 위젯을 렌더링합니다
  * @param {object} params 결제 UI 렌더링 정보입니다.
@@ -584,6 +606,95 @@ type RequestPaymentWithRedirection$1 = (paymentRequest: WithRedirection<WidgetPa
  */
 type SetAmount = (amount: Amount) => Promise<void>;
 
+/**
+ * 결제창을 통해 결제를 요청합니다
+ * @docsDefaultSignature RequestPaymentWindowWithRedirection
+ *
+ * @param {WidgetPaymentRequestWindow} paymentRequest - 결제 요청 정보입니다.
+ * @param {WidgetPaymentRequestWindowOptions} options - 위젯 결제창 옵션입니다.
+ *
+ * @returns 결제 결과
+ *
+ *
+ * @throws {@link PublicError.Widgets.UserCancelError} 사용자가 결제를 취소한 경우
+ * @throws {@link PublicError.Widgets.InvalidVariantKeyError} variantKey 가 유효하지 않은 경우
+ * @throws {@link PublicError.Widgets.ProviderStatusUnhealthyError} 결제 기관의 시스템에 문제가 있을 때
+ * @throws {@link PublicError.Widgets.UnsupportedTestPhasePaymentMethodError} 테스트 환경을 지원하지 않는 결제수단을 선택한 경우
+ * @throws {@link PublicError.Widgets.IncorrectSuccessUrlFormatError} successUrl이 유효하지 않은 경우
+ * @throws {@link PublicError.Widgets.IncorrectFailUrlFormatError} failUrl이 유효하지 않은 경우
+ * @throws {@link PublicError.Widgets.PaymentRequestFailError} 결제 요청에 실패한 경우
+ * @throws {@link PublicError.Widgets.NotSupportedPromiseError} promise 방식을 지원하지 않는 환경인 경우
+ * @throws {@link PublicError.Widgets.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
+ * @throws {@link PublicError.Widgets.InvalidMetadataError} metadata가 올바르지 않은 경우
+ * @throws {@link PublicError.Widgets.InvalidParametersError} 파라미터가 올바르지 않은 경우
+ * @throws {@link PublicError.Widgets.BelowZeroAmountError} 결제 금액이 0원 미만인 경우
+ * @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
+ */
+type RequestPaymentWindow = RequestPaymentWindowWithPromise & RequestPaymentWindowWithRedirection;
+/**
+ * @docsAlias Promise 방식
+ * @returns `WidgetPaymentResult` 객체가 응답됩니다. 객체 필드를 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해야 결제가 최종적으로 완료돼요.
+ * @param {WidgetPaymentRequestWindow} paymentRequest 결제 요청 정보입니다.
+ * @param {WidgetPaymentRequestWindowOptions} options 위젯 결제창 옵션입니다.
+ *
+ * @example
+ *  ```js
+ *  widgets.requestPaymentWindow(
+ *    {
+ *      orderId: generateRandomString(),
+ *      orderName: "토스 티셔츠 외 2건",
+ *      customerEmail: "customer123@gmail.com",
+ *      customerName: "김토스",
+ *    },
+ *    {
+ *      variantKey: {
+ *        paymentMethod: "CUSTOM-1",
+ *        agreement: "AGREEMENT",
+ *      },
+ *    }
+ *  );
+ * ```
+ *
+ */
+type RequestPaymentWindowWithPromise = (paymentRequest: WidgetPaymentRequestWindow, options?: WidgetPaymentRequestWindowOptions) => Promise<WidgetPaymentResult>;
+/**
+ * @docsAlias Redirect 방식
+ *
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 메서드 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * ```plain theme="grey" copyable="false"
+ * {successUrl}?paymentType={PAYMENT_TYPE}&amount={AMOUNT}&orderId={ORDER_ID}&paymentKey={PAYMENT_KEY}
+ * ```
+ * 결제 요청이 실패하면 파라미터로 설정한 `failUrl`로 이동해요. 쿼리 파라미터로 에러 코드와 메시지를 확인하세요.
+ * ```plain theme="grey" copyable="false"
+ * {failUrl}?code={ERROR_CODE}&message={ERROR_MESSAGE}&orderId={ORDER_ID}
+ * ```
+ * Redirect 방식에서는 URL이 이동하기 때문에 `void`가 응답됩니다.
+
+ * @param {WidgetPaymentRequestWindow} paymentRequest 결제 요청 정보입니다.
+ * @param {WidgetPaymentRequestWindowOptions} options 위젯 결제창 옵션입니다.
+ *
+ * @example
+ *  ```js
+ *  widgets.requestPaymentWindow(
+ *    {
+ *      orderId: generateRandomString(),
+ *      orderName: "토스 티셔츠 외 2건",
+ *      successUrl: window.location.origin + "/success.html",
+ *      failUrl: window.location.origin + "/fail.html",
+ *      customerEmail: "customer123@gmail.com",
+ *      customerName: "김토스",
+ *    },
+ *    {
+ *      variantKey: {
+ *        paymentMethod: "CUSTOM-1",
+ *        agreement: "AGREEMENT",
+ *      },
+ *    }
+ *  );
+ * ```
+ */
+type RequestPaymentWindowWithRedirection = (paymentRequest: WithRedirection<WidgetPaymentRequestWindow>, options?: WidgetPaymentRequestWindowOptions) => Promise<void>;
+
 interface TossPaymentsWidgets {
     /**
      * 주문의 결제 금액을 설정합니다. [자세히 >](#widgetssetamount)
@@ -597,6 +708,10 @@ interface TossPaymentsWidgets {
      * 결제를 요청합니다. 구매자가 결제 UI에서 선택한 결제수단의 결제창을 띄워요. [자세히 >](#widgetsrequestpayment)
      */
     requestPayment: RequestPayment$2;
+    /**
+     * 위젯 결제창으로 결제를 요청합니다. [자세히 >](#widgetsrequestpaymentwindow)
+     */
+    requestPaymentWindow: RequestPaymentWindow;
     /**
      * 약관 UI를 렌더링합니다. [자세히 >](#widgetsrenderagreement)
      */
@@ -1317,7 +1432,7 @@ interface ForeignEasyPayPaymentRequest extends PaymentRequest {
          */
         products?: Array<{
             /**
-             * 상품명입니다.
+             * 상품명입니다. 최대 길이는 100자입니다.
              */
             name: string;
             /**
@@ -1409,20 +1524,19 @@ interface RequestPaymentResult {
     amount: Amount;
 }
 
-interface BillingAuthRequest {
-    /**
-     * 자동결제(빌링)에 등록할 결제수단입니다. 토스페이먼츠 자동결제는 현재 신용·체크카드만 지원해요.
-     */
-    method: 'CARD' | 'TRANSFER';
+/**
+ * 자동결제(빌링) 등록 요청의 공통 필드입니다.
+ */
+interface BaseBillingAuthRequest {
     /**
-     * 카드 등록이 성공하면 리다이렉트되는 URL입니다. 리다이렉트되면 URL의 쿼리 파라미터로 `authKey`, `customerKey`가 추가돼요. 값을 검증하고 [빌링키 발급 API](/reference#authkey로-카드-빌링키-발급)를 호출하세요.
+     * 등록이 성공하면 리다이렉트되는 URL입니다. 리다이렉트되면 URL의 쿼리 파라미터로 `authKey`, `customerKey`가 추가돼요. 값을 검증하고 [빌링키 발급 API](/reference#authkey로-카드-빌링키-발급)를 호출하세요.
      * 반드시 오리진을 포함해야 합니다.
      *
      * @example https://www.example.com/success
      */
     successUrl: string;
     /**
-     * 카드 등록이 실패하면 리다이렉트되는 URL입니다. 리다이렉트되면 URL의 쿼리 파라미터로 에러 코드와 메시지를 확인할 수 있어요.
+     * 등록이 실패하면 리다이렉트되는 URL입니다. 리다이렉트되면 URL의 쿼리 파라미터로 에러 코드와 메시지를 확인할 수 있어요.
      * 반드시 오리진을 포함해야 합니다.
      */
     failUrl: string;
@@ -1444,11 +1558,49 @@ interface BillingAuthRequest {
      * @default 'iframe'
      */
     windowTarget?: 'iframe' | 'self' | null;
+}
+/**
+ * 카드 자동결제(빌링) 등록 요청 정보입니다.
+ */
+interface CardBillingAuthRequest extends BaseBillingAuthRequest {
+    /**
+     * 자동결제(빌링)에 등록할 결제수단입니다.
+     */
+    method: 'CARD';
     /**
      * 결제화면에 노출할 카드 타입입니다. `PERSONAL`(개인카드), `CORPORATE`(법인카드) 값을 배열 형태로 전달할 수 있습니다. 입력한 순서대로 화면에 노출되며, 첫 번째로 입력한 카드 타입이 기본 선택됩니다.
      */
     selectableCardTypes?: Array<'PERSONAL' | 'CORPORATE'> | null;
+    /**
+     * 결제창을 여는 방법입니다. `DEFAULT`는 기존 카드 빌링창을 열고, `DIRECT`는 easyPay로 전달된 간편결제의 자체창을 엽니다.
+     * 기본 값은 `DEFAULT`입니다.
+     */
+    flowMode?: 'DIRECT' | 'DEFAULT';
+    /**
+     * 간편결제사 코드입니다. 현재 빌링을 지원하는 간편결제사는 토스페이, 네이버페이가 있습니다.
+     * `flowMode: 'DIRECT'`일 때만 사용할 수 있습니다.
+     */
+    easyPay?: '토스페이' | 'TOSSPAY' | '네이버페이' | 'NAVERPAY';
+    /**
+     * 간편결제에서 특정 카드사만 노출할 수 있도록 파라미터를 제공합니다.
+     * `flowMode: 'DIRECT'`일 때만 사용할 수 있습니다.
+     */
+    cardCompany?: string;
 }
+/**
+ * 계좌이체 자동결제(빌링) 등록 요청 정보입니다.
+ */
+interface TransferBillingAuthRequest extends BaseBillingAuthRequest {
+    /**
+     * 자동결제(빌링)에 등록할 결제수단입니다.
+     */
+    method: 'TRANSFER';
+}
+/**
+ * 자동결제(빌링) 등록 요청 정보입니다. 토스페이먼츠 자동결제는 신용·체크카드, 계좌이체를 지원해요.
+ * `method` 필드에 따라 사용 가능한 필드가 달라집니다.
+ */
+type BillingAuthRequest = CardBillingAuthRequest | TransferBillingAuthRequest;
 
 /**
  *
@@ -1812,7 +1964,7 @@ type RequestForeignEasyPayPaymentWithRedirection = (paymentRequest: WithRedirect
 /**
  * 자동결제(빌링) 결제창을 열어 구매자의 카드 등록을 요청하는 메서드입니다.
  *
- * @param {BillingAuthRequest} billingAuthRequest 자동결제(빌링) 카드 등록에 필요한 정보입니다.
+ * @param {BillingAuthRequest} billingAuthRequest 자동결제(빌링) 등록에 필요한 정보입니다.
  * @returns URL이 이동하기 때문에 `void`가 응답됩니다. 파라미터로 설정한 `successUrl` 또는 `failUrl`에서 카드 등록 결과를 확인하고 [빌링키 발급 API](/reference#authkey로-카드-빌링키-발급)를 호출해야 자동결제를 할 수 있어요.
  *
  * @example