@tosspayments/tosspayments-sdk 2.0.0 → 2.2.0

package/types/index.d.ts

@@ -1,2 +1,1767 @@
-export { clearTossPayments } from './clearTossPayments';
-export { loadTossPayments } from './loadTossPayments';
+declare function clearTossPayments(): void;
+
+interface WidgetSelectedPaymentMethod<CustomPaymentMethodCode = WidgetsPaymentMethodCode> {
+    /**
+     * 구매자가 결제 UI에서 선택한 결제수단입니다. 예를 들어, 신용・체크카드를 선택하면 `CARD` 코드가 응답됩니다. [ENUM 코드](/codes/enum-codes) 및 [기관 코드](/codes/org-codes)를 참고하세요.
+     */
+    code: WidgetsPaymentMethodCode | CustomPaymentMethodCode;
+}
+type WidgetsPaymentMethodCode = 'CARD' | 'VIRTUAL_ACCOUNT' | 'MOBILE_PHONE' | 'TRANSFER' | 'CULTURE_GIFT_CERTIFICATE' | 'GAME_GIFT_CERTIFICATE' | 'BOOK_GIFT_CERTIFICATE' | 'TOSSPAY' | 'NAVERPAY' | 'SAMSUNGPAY' | 'LPAY' | 'KAKAOPAY' | 'PAYCO' | 'SSG' | 'APPLEPAY' | 'PINPAY' | 'KBPAY' | 'PAYPAL' | 'GCASH' | 'TOUCHNGO' | 'BOOST' | 'BPI' | 'BILLEASE' | 'DANA' | 'ALIPAYHK' | 'TRUEMONEY' | 'RABBIT_LINE_PAY' | 'ALIPAY' | 'SHINHAN' | 'HYUNDAI' | 'SAMSUNG' | 'WOORI' | 'KOOKMIN' | 'LOTTE' | 'NONGHYEOP' | 'HANA' | 'BC' | 'KDBBANK' | 'TOSSBANK' | 'KAKAOBANK' | 'SUHYEOP' | 'JEONBUKBANK' | 'KBANK' | 'POST' | 'SAEMAUL' | 'CITI' | 'SAVINGBANK' | 'JEJUBANK' | 'GWANGJUBANK' | 'SHINHYEOP' | 'JCB' | 'UNIONPAY' | 'MASTER' | 'VISA' | 'DINERS' | 'DISCOVER' | 'IBK_BC' | 'AMEX' | 'TOSS_PAYMENTS' | 'BANKPAY' | 'BRANDPAY' | 'KEYIN';
+
+interface WidgetPaymentMethodWidget {
+    /**
+     * 결제 UI의 이벤트를 구독합니다. [자세히 >](#paymentmethodwidgeton)
+     *
+     * @example
+     *  ```javascript
+     *  widgets.on('paymentMethodSelect', selectedPaymentMethod => {
+          if (paymentMethodSelected.code === '문화바우처') {
+            // 문화바우처 안내사항 노출
+          }
+          
+          if (paymentMethodSelected.code === '카드') {
+            // 카드 안내사항 노출
+          }
+        });
+     * ```
+     *
+     * @param {'paymentMethodSelect'} eventName 구독할 이벤트입니다. `paymentMethodSelect` 이벤트로 구매자가 선택한 결제수단 정보를 확인하세요.
+     * @param {function} callback 이벤트가 일어나면 호출되는 콜백 함수입니다.
+     *
+     * @throws {@link PublicError.Widgets.InvalidEventParameterError} eventName이 유효하지 않은 경우
+     * @throws {@link PublicError.Widgets.InvalidCallbackParameterError} callback이 유효하지 않은 경우
+     * @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
+     */
+    on: {
+        (eventName: 'paymentMethodSelect', callback: <CustomPaymentMethodCode>(paymentMethod: WidgetSelectedPaymentMethod<CustomPaymentMethodCode>) => void): void;
+    };
+    /**
+     * 구매자가 선택한 결제수단을 불러옵니다. [자세히 >](#paymentmethodwidgetgetselectedpaymentmethod)
+     *
+     * @example
+     *  ```javascript
+     *  const paymentMethod = await paymentMethodWidget.getSelectedPaymentMethod();
+     * ```
+     *
+     * @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
+     */
+    getSelectedPaymentMethod: <CustomPaymentMethodCode>() => Promise<WidgetSelectedPaymentMethod<CustomPaymentMethodCode>>;
+    /**
+     * 결제 UI 객체를 제거합니다. [자세히 >](#paymentmethodwidgetdestroy)
+     *
+     * @example
+     *  ```javascript
+     *  await paymentMethodWidget.destroy();
+     * ```
+     *
+     * @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
+     */
+    destroy: () => Promise<void>;
+}
+
+interface WidgetAgreementStatus {
+    agreedRequiredTerms: boolean;
+    agreements: Array<{
+        term: {
+            id: string;
+            required: boolean;
+        };
+        agreed: boolean;
+    }>;
+}
+
+interface WidgetAgreementWidget {
+    /**
+     * 약관 UI의 이벤트를 구독합니다. [자세히](#widgetagreementwidgeton)
+     *
+     * @param {'agreementStatusChange'} eventName 구독할 이벤트입니다. `agreementStatusChange` 이벤트로 구매자가 약관에 동의했는지 확인하세요.
+     * @param {function} callback 이벤트가 일어나면 호출되는 콜백 함수입니다.
+     *
+     * @example
+     *  ```javascript
+     *  agreementWidget.on('agreementStatusChange', agreementStatus => {
+          if (agreementStatus.agreedRequiredTerms) {
+            // 결제 버튼 활성화
+          } else {
+            // 결제 버튼 비활성화
+          }
+        });
+     * ```
+     *
+     * @throws {@link PublicError.Widgets.InvalidEventParameterError} eventName이 유효하지 않은 경우
+     * @throws {@link PublicError.Widgets.InvalidCallbackParameterError} callback이 유효하지 않은 경우
+     * @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
+     */
+    on: (eventName: 'agreementStatusChange', callback: (agreementStatus: WidgetAgreementStatus) => void) => void;
+    /**
+     * 약관 UI 객체를 제거합니다. [자세히 >](#agreementwidgetdestroy)
+     *
+     * @example
+     *  ```javascript
+     *  await agreementWidget.destroy();
+     * ```
+     *
+     * @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
+     */
+    destroy: () => Promise<void>;
+}
+
+interface WidgetPaymentRequest {
+    /**
+     * 주문번호입니다. 각 주문을 구분하는 무작위한 고유값을 생성하세요. 영문 대소문자, 숫자, 특수문자 `-`, `_`, `=`로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
+     */
+    orderId: string;
+    /**
+     * 구매상품입니다. 예를 들면 `생수 외 1건` 같은 형식입니다. 최대 길이는 100자입니다.
+     */
+    orderName: string;
+    /**
+     * 구매자 이메일입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다.
+     */
+    customerEmail?: string;
+    /**
+     * 구매자명입니다. 최대 길이는 100자입니다.
+     */
+    customerName?: string;
+    /**
+     * 구매자의 휴대폰 번호입니다. 가상계좌 안내, 퀵계좌이체 휴대폰 번호 자동 완성에 사용되고 있어요.
+     */
+    customerMobilePhone?: string;
+    /**
+     * 결제 금액 중 면세 금액입니다. 면세 상점 혹은 복합 과세 상점으로 계약된 상점만 사용하세요. 자세한 내용은 세금 처리 가이드에서 확인하세요.
+     */
+    taxFreeAmount?: number;
+    /**
+     * 구매자가 카드를 선택하면 결제에 적용되는 옵션입니다.
+     */
+    card?: {
+        /**
+         * 과세를 제외한 결제 금액(컵 보증금 등)입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.
+         * 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다.
+         */
+        taxExemptionAmount?: number;
+    };
+    /**
+     * 구매자가 계좌이체를 선택하면 결제에 적용되는 옵션입니다.
+     */
+    transfer?: {
+        /**
+         * 에스크로 적용 여부입니다. `true`로 설정하면 구매자가 반드시 에스크로 적용에 동의해야 결제가 완료돼요.
+         * `false`로 설정하거나 파라미터를 설정하지 않으면 에스크로 적용을 구매자 선택에 맡겨요.
+         */
+        useEscrow?: boolean;
+        /**
+         * 각 상품의 상세 정보 객체를 담는 배열입니다. 에스크로를 사용하는 상점이라면 필수 파라미터입니다.
+         * 예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다.
+         */
+        escrowProducts?: Array<{
+            /**
+             * 각 상품의 고유 ID입니다.
+             */
+            id?: string;
+            /**
+             * 상품명입니다.
+             */
+            name?: string;
+            /**
+             * 내 상점에서 사용하는 상품 관리 코드입니다.
+             */
+            code?: string;
+            /**
+             * 상품의 1개의 개별 가격입니다.
+             */
+            unitPrice?: number;
+            /**
+             * 상품 구매 수량입니다.
+             */
+            quantity?: number;
+        }>;
+    };
+    /**
+     * 구매자가 가상계좌를 선택하면 결제에 적용되는 옵션입니다.
+     */
+    virtualAccount?: {
+        /**
+         * 에스크로 사용 여부입니다. 값을 주지 않으면 결제창에서 고객이 직접 에스크로 결제 여부를 선택합니다.
+         */
+        useEscrow?: boolean;
+        /**
+         * 각 상품의 상세 정보 객체를 담는 배열입니다. 에스크로를 사용하는 상점이라면 필수 파라미터입니다.
+         * 예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다.
+         */
+        escrowProducts?: Array<{
+            /**
+             * 각 상품의 고유 ID입니다.
+             */
+            id?: string;
+            /**
+             * 상품명입니다.
+             */
+            name?: string;
+            /**
+             * 내 상점에서 사용하는 상품 관리 코드입니다.
+             */
+            code?: string;
+            /**
+             * 상품의 1개의 개별 가격입니다.
+             */
+            unitPrice?: number;
+            /**
+             * 상품 구매 수량입니다.
+             */
+            quantity?: number;
+        }>;
+    };
+    /**
+     * 구매자가 해외간편결제를 선택하면 결제에 적용되는 옵션입니다.
+     */
+    foreignEasyPay?: {
+        country: string;
+        /**
+         * 구매 상품 정보입니다. 여러 가지의 상품을 결제했다면 각 상품의 정보를 입력하세요. 예를 들어, 구매자가 세 가지 종류의 상품을 구매했다면 배열의 길이는 3이어야 합니다.
+         *
+         * PayPal에서 제공하는 판매자 보호를 받고 싶다면 반드시 해당 파라미터를 사용하세요. 판매자 보호 및 위험거래 관리를 위해 PayPal에 제공돼요.
+         */
+        products?: Array<{
+            /**
+             * 상품명입니다.
+             */
+            name: string;
+            /**
+             * 상품의 구매 수량입니다.
+             */
+            quantity: number;
+            /**
+             * 상품의 1개의 개별 가격입니다.
+             */
+            unitAmount: number;
+            /**
+             * 결제 통화입니다.
+             */
+            currency: string;
+            /**
+             * 상품 설명입니다.
+             */
+            description: string;
+        }>;
+        /**
+         * 배송 정보입니다.
+         */
+        shipping?: {
+            /**
+             * 수령인입니다.
+             */
+            fullName?: string;
+            /**
+             * 배송 주소입니다.
+             */
+            address?: {
+                /**
+                 * 국가입니다.
+                 */
+                country: string;
+                /**
+                 * 주소입니다. 도로명 및 건물(Street, Apt), 번지 정보입니다.
+                 */
+                line1?: string;
+                /**
+                 * 상세 주소입니다. 번지 및 동 호수 정보를 입력하세요.
+                 */
+                line2?: string;
+                /**
+                 * 주(State, Province, Region) 정보입니다. 국가의 도시 체계에 따라 없는 경우가 있습니다.
+                 */
+                area1?: string;
+                /**
+                 * 도시입니다.
+                 */
+                area2: string;
+                /**
+                 * 배송지 우편번호입니다. 중국, 일본, 프랑스, 독일 등 [일부 국가](https://developer.paypal.com/api/rest/reference/orders/v2/country-address-requirements/#link-countryandregionaddressrequirements)에서는 필수 파라미터입니다
+                 */
+                postalCode?: string;
+            };
+        };
+        /**
+         * 특정 해외간편결제 수단에만 필요한 정보입니다.
+         */
+        paymentMethodOptions?: {
+            /**
+             * PayPal 결제에 추가로 필요한 정보입니다.
+             */
+            paypal?: {
+                /**
+                 * PayPal에서 추가로 요청하는 STC(Set Transaction Context) 정보입니다. 이 정보는 토스페이먼츠에서 관리하지 않으며, PayPal에서 부정거래, 결제 취소, 환불 등 리스크 관리에 활용합니다.
+                 * 결제 거래의 안전성과 신뢰성을 확보하려면 이 정보를 전달해야 합니다. [PayPal STC 문서](https://static.tosspayments.com/public/STC.pdf)를 참고해서 업종에 따라 필요한 파라미터를 추가해주세요.
+                 * 문서의 표에 있는 ‘Data Field Name’ 컬럼 값을 객체의 ‘key’로, ‘Description’에 맞는 값을 객체의 ‘value’로 넣어주시면 됩니다.
+                 */
+                setTransactionContext?: unknown;
+            };
+        };
+    };
+}
+
+interface Amount {
+    /**
+     * 결제 금액입니다.
+     */
+    value: number;
+    /**
+     * 결제 통화입니다.
+     */
+    currency: string;
+}
+
+type WithRedirection<T> = T & {
+    /**
+     * 결제 요청이 성공하면 리다이렉트되는 URL입니다. `https://www.example.com/success`와 같이 오리진을 포함한 형태로 설정해주세요.
+     * 리다이렉트되면 URL의 쿼리 파라미터로 `amount`, `orderId`, `paymentKey`가 추가돼요.
+     */
+    successUrl?: string;
+    /**
+     * 결제 요청이 실패하면 리다이렉트되는 URL입니다. `https://www.example.com/fail`와 같이 오리진을 포함한 형태로 설정해주세요.
+     * 리다이렉트되면 URL의 쿼리 파라미터로 에러 코드와 메시지를 확인할 수 있어요.
+     */
+    failUrl?: string;
+};
+
+type WidgetPaymentResult = {
+    /**
+     * 결제 타입입니다. `NORMAL`(일반결제), `BRANDPAY`(브랜드페이) 중 하나입니다.
+     */
+    paymentType: 'NORMAL' | 'BRANDPAY';
+    /**
+     * 토스페이먼츠에서 발급하는 결제 식별 키입니다. 결제 승인, 조회, 취소 등에 사용되니 반드시 저장하세요.
+     */
+    paymentKey: string;
+    /**
+     * 주문번호입니다. 결제를 요청할 때 호출한 `requestPayment()` 메서드로 넘긴 `orderId` 값과 같은지 확인하세요.
+     */
+    orderId: string;
+    /**
+     * 결제 금액 정보입니다. `requestPayment()` 메서드로 넘긴 `amount` 값과 같은지 확인하세요.
+     */
+    amount: Amount;
+};
+
+/**
+ * 결제 UI 위젯을 렌더링합니다
+ * @param {object} params 결제 UI 렌더링 정보입니다.
+ *
+ * @returns 반환되는 결제 UI 객체로 아래 메서드를 호출할 수 있어요.
+ *
+ * @example
+ *  ```javascript
+ *  const paymentMethodWidget = await widgets.renderPaymentMethods({
+ *    selector: "#payment-method",
+ *    variantKey: "CUSTOM-1"
+    });
+ * ```
+
+ * @throws {Widgets.UserCancelError} 사용자가 결제수단 위젯 렌더링을 취소한 경우
+ * @throws {@link PublicError.Widgets.NotSetupAmountError} 결제금액이 설정되지 않은 경우
+ * @throws {@link PublicError.Widgets.PaymentMethodsWidgetAlreadyRenderedError} 이미 결제수단 위젯이 렌더링 된 경우
+ * @throws {@link PublicError.Widgets.InvalidVariantKeyError} variantKey 가 유효하지 않은 경우
+ * @throws {@link PublicError.Widgets.InvalidSelectorError} selector 가 유효하지 않은 경우
+ * @throws {@link PublicError.Widgets.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
+ * @throws {@link PublicError.Widgets.InvalidParametersError} 파라미터가 올바르지 않은 경우
+ * @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
+ */
+type RenderPaymentMethods = (params: {
+    /**
+     * 결제 UI를 렌더링할 위치를 지정합니다. `<div>`와 같은 HTML 요소를 선택할 수 있는 CSS 선택자를 사용합니다. 예를 들어 `<div id="payment-method">`에 결제 UI를 렌더링하려면, `#payment-method`를 전달해야 합니다.
+     */
+    selector: string;
+    /**
+     * 렌더링하고 싶은 결제 UI의 `variantKey`입니다. 2개 이상의 결제 UI를 사용하고 있다면 설정해주세요. `variantKey`는 [상점관리자의 결제위젯 어드민](/guides/v2/payment-widget#2-결제-ui의-variantkey-확인)에서 확인할 수 있어요. 기본 값은 `DEFAULT`입니다.
+     */
+    variantKey?: string;
+}) => Promise<WidgetPaymentMethodWidget>;
+
+/**
+ * 약관 위젯을 렌더링합니다
+ * @param {object} params 약관 UI 렌더링 정보입니다.
+ *
+ * @returns 반환되는 약관 UI 객체로 아래 메서드를 호출할 수 있어요.
+ *
+ * @example
+ *  ```javascript
+ *  const agreementWidget = await widgets.renderAgreement({
+ *    selector: "#agreement",
+ *    variantKey: "AGREEMENT"
+ *  });
+ * ```
+ *
+ * @throws {@link PublicError.Widgets.UserCancelError} 사용자가 약관 위젯 렌더링을 취소한 경우
+ * @throws {@link PublicError.Widgets.AgreementWidgetAlreadyRenderedError} 이미 약관 위젯이 렌더링 된 경우
+ * @throws {@link PublicError.Widgets.InvalidSelectorError} selector 가 유효하지 않은 경우
+ * @throws {@link PublicError.Widgets.InvalidVariantKeyError} variantKey 가 유효하지 않은 경우
+ * @throws {@link PublicError.Widgets.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
+ * @throws {@link PublicError.Widgets.InvalidParametersError} 파라미터가 올바르지 않은 경우
+ * @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
+ */
+type RenderAgreement = (params: {
+    /**
+     * 약관 UI를 렌더링할 위치를 지정합니다. `<div>`와 같은 HTML 요소를 선택할 수 있는 CSS 선택자를 사용합니다. 예를 들어 `<div id="agreement">`에 결제 UI를 렌더링하려면, `#agreement`를 전달해야 합니다.
+     */
+    selector: string;
+    /**
+     * 렌더링하고 싶은 약과 UI의 `variantKey`입니다. 상점관리자의 결제위젯 어드민에서 확인할 수 있어요.
+     */
+    variantKey?: string;
+}) => Promise<WidgetAgreementWidget>;
+
+/**
+ * 결제를 요청합니다
+ *
+ * @param {WidgetPaymentRequest} paymentRequest - 결제 요청 정보입니다.
+ *
+ * @returns 결제 결과
+ *
+ *
+ * @throws {@link PublicError.Widgets.UserCancelError} 사용자가 결제를 취소한 경우
+ * @throws {@link PublicError.Widgets.ProviderStatusUnhealthyError} 결제 기관의 시스템에 문제가 있을 때
+ * @throws {@link PublicError.Widgets.NotSelectedPaymentMethodError} 결제수단이 선택되어있지 않은 경우
+ * @throws {@link PublicError.Widgets.NeedAgreementWithRequiredTermsError} 모든 필수 약관에 동의하지 않은 경우
+ * @throws {@link PublicError.Widgets.NeedCardPaymentDetailError} 신용, 체크카드 결제 시, 카드사나 할부 기간을 선택하지 않은 경우
+ * @throws {@link PublicError.Widgets.NeedRefundAccountDetailError} 가상계좌 결제 시, 환불 계좌 정보를 입력하지 않은 경우
+ * @throws {@link PublicError.Widgets.ExceedDepositAmountLimitError} 가상계좌 결제 시, 입금 가능한 금액보다 큰 금액을 결제한 경우
+ * @throws {@link PublicError.Widgets.ExceedMaxDueDateError} 가상계좌 결제 시, 최대 유효만료 기간을 넘긴 경우
+ * @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.InvalidParametersError} 파라미터가 올바르지 않은 경우
+ * @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
+ */
+type RequestPayment$2 = RequestPaymentWithRedirection$1 & RequestPaymentWithPromise$1;
+/**
+ * @docsAlias Promise 방식
+ * @returns `WidgetPaymentResult` 객체가 응답됩니다. 객체 필드를 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해야 결제가 최종적으로 완료돼요.
+ * @param {WidgetPaymentRequest} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ *  ```js
+ *  widgets.requestPayment({
+      orderId: generateRandomString(),
+      orderName: "토스 티셔츠 외 2건",
+      customerEmail: "customer123@gmail.com",
+      customerName: "김토스",
+      customerMobilePhone: "01012341234",
+    });
+ * ```
+
+ */
+type RequestPaymentWithPromise$1 = (paymentRequest: WidgetPaymentRequest) => Promise<WidgetPaymentResult>;
+/**
+ * @docsAlias Redirect 방식
+ *
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * ```plain theme="grey" copyable="false"
+ * {successUrl}?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 {WidgetPaymentRequest} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ *  ```js
+ *  widgets.requestPayment({
+      orderId: generateRandomString(),
+      orderName: "토스 티셔츠 외 2건",
+      successUrl: window.location.origin + "/success.html",
+      failUrl: window.location.origin + "/fail.html",
+      customerEmail: "customer123@gmail.com",
+      customerName: "김토스",
+      customerMobilePhone: "01012341234",
+    });
+ * ```
+ */
+type RequestPaymentWithRedirection$1 = (paymentRequest: WithRedirection<WidgetPaymentRequest>) => Promise<void>;
+
+/**
+ * 결제 금액을 변경합니다
+ *
+ * @param {Amount} amount 새로운 결제 금액입니다.
+ *
+ * @example
+ *  ```javascript
+ *  widgets.setAmount({
+ *    currency: 'KRW',
+ *    value: amount,
+ *  });
+ * ```
+ *
+ * @throws {@link PublicError.Widgets.InvalidAmountValueError} 결제 금액이 유효하지 않은 경우
+ * @throws {@link PublicError.Widgets.InvalidAmountCurrencyError} 결제 금액의 통화가 유효하지 않은 경우
+ * @throws {@link PublicError.Widgets.BelowZeroAmountError} 결제 금액이 0원 이하인 경우
+ * @throws {@link PublicError.Widgets.InvalidParametersError} 파라미터가 올바르지 않은 경우
+ * @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
+ */
+type SetAmount = (amount: Amount) => Promise<void>;
+
+interface TossPaymentsWidgets {
+    /**
+     * 주문의 결제 금액을 설정합니다. [자세히 >](#widgetssetamount)
+     */
+    setAmount: SetAmount;
+    /**
+     * 결제 UI를 렌더링합니다. [자세히 >](#widgetsrenderpaymentmethods)
+     */
+    renderPaymentMethods: RenderPaymentMethods;
+    /**
+     * 결제를 요청합니다. 구매자가 결제 UI에서 선택한 결제수단의 결제창을 띄워요. [자세히 >](#widgetsrequestpayment)
+     */
+    requestPayment: RequestPayment$2;
+    /**
+     * 약관 UI를 렌더링합니다. [자세히 >](#widgetsrenderagreement)
+     */
+    renderAgreement: RenderAgreement;
+}
+
+interface BrandpayAmount extends Amount {
+    currency: 'KRW';
+}
+
+interface BrandpayPaymentRequest {
+    /**
+     * 결제 금액 정보입니다.
+     */
+    amount: BrandpayAmount;
+    /**
+     * 주문번호입니다. 각 주문을 구분하는 무작위한 고유값을 생성하세요. 영문 대소문자, 숫자, 특수문자 `-`, `_`, `=`로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
+     */
+    orderId: string;
+    /**
+     * 구매상품입니다. 예를 들면 `생수 외 1건` 같은 형식입니다. 최대 길이는 100자입니다.
+     */
+    orderName: string;
+    /**
+     * 구매자 이메일입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다.
+     */
+    customerEmail?: string;
+    /**
+     * 구매자명입니다. 최대 길이는 100자입니다.
+     */
+    customerName?: string;
+    /**
+     * 결제 금액 중 면세 금액입니다. 면세 상점 혹은 복합 과세 상점으로 계약된 상점만 사용하세요. 자세한 내용은 세금 처리 가이드에서 확인하세요.
+     */
+    taxFreeAmount?: number;
+}
+
+interface BrandpayRequestPaymentResult {
+    /**
+     * 토스페이먼츠에서 발급하는 결제 식별 키입니다. 결제 승인, 조회, 취소 등에 사용되니 반드시 저장하세요.
+     */
+    paymentKey: string;
+    /**
+     * 주문번호입니다. 결제를 요청할 때 호출한 `requestPayment()` 메서드로 넘긴 `orderId` 값과 같은지 확인하세요.
+     */
+    orderId: string;
+    amount: BrandpayAmount;
+}
+
+/**
+ * 결제를 요청합니다
+ *
+ * @param {WithRedirection<BrandpayPaymentRequest> | BrandpayPaymentRequest} paymentRequest - 결제 요청 정보
+ *
+ *
+ * @throws {@link PublicError.Brandpay.UserCancelError} 사용자가 결제를 취소한 경우
+ * @throws {@link PublicError.Brandpay.InvalidAmountValueError} 결제 금액이 유효하지 않은 경우
+ * @throws {@link PublicError.Brandpay.BelowZeroAmountError} 결제 금액이 0 미만인 경우
+ * @throws {@link PublicError.Brandpay.IncorrectSuccessUrlFormatError} successUrl이 유효하지 않은 경우
+ * @throws {@link PublicError.Brandpay.IncorrectFailUrlFormatError} failUrl이 유효하지 않은 경우
+ * @throws {@link PublicError.Brandpay.PaymentRequestFailError} 결제 요청에 실패한 경우
+ * @throws {@link PublicError.Brandpay.NotRegisteredRedirectUrlError} redirectUrl이 등록되지 않은 경우
+ * @throws {@link PublicError.Brandpay.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
+ * @throws {@link PublicError.Brandpay.InvalidParametersError} 파라미터가 올바르지 않은 경우
+ * @throws {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
+ */
+type RequestPayment$1 = RequestPaymentWithRedirection & RequestPaymentWithPromise;
+/**
+ * @docsAlias Redirect 방식
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [브랜드페이 결제 승인 API](/reference/brandpay#결제-승인)를 호출해서 결제를 완료하세요.
+ * ```plain theme="grey" copyable="false"
+ * {successUrl}?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 {WithRedirection<BrandpayPaymentRequest>} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ * ```javascript
+ * brandpay.requestPayment({
+ *   amount: {
+ *     currency: 'KRW',
+ *     value: 50000,
+ *   },
+ *   orderId: "<UniqueId name='orderId.brandpay' />",
+ *   orderName: '토스 티셔츠 외 2건',
+ *   successUrl: window.location.origin + '/success.html',
+ *   failUrl: window.location.origin + '/fail.html',
+ *   customerEmail: 'customer123@gmail.com',
+ *   customerName: '김토스',
+ *   customerMobilePhone: '01012341234',
+ * });
+ * ```
+ */
+type RequestPaymentWithRedirection = (paymentRequest: WithRedirection<BrandpayPaymentRequest>) => Promise<void>;
+/**
+ * @docsAlias Promise 방식
+ * @returns `BrandpayRequestPaymentResult` 객체가 응답됩니다. 객체 필드를 확인하고 [브랜드페이 결제 승인 API](/reference/brandpay#결제-승인)를 호출해야 결제가 최종적으로 완료돼요.
+ * @param {BrandpayPaymentRequest} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ * ```javascript
+ * brandpay.requestPayment({
+ *   amount: {
+ *     currency: 'KRW',
+ *     value: 50000,
+ *   },
+ *   orderId: "<UniqueId name='orderId.brandpay' />",
+ *   orderName: '토스 티셔츠 외 2건',
+ *   customerEmail: 'customer123@gmail.com',
+ *   customerName: '김토스',
+ *   customerMobilePhone: '01012341234',
+ * });
+ * ```
+ */
+type RequestPaymentWithPromise = (paymentRequest: BrandpayPaymentRequest) => Promise<BrandpayRequestPaymentResult>;
+
+/**
+ * 등록된 비밀번호를 변경합니다
+ *
+ *
+ * @example
+ * ```javascript
+ * brandpay.changePassword();
+ * ```
+ *
+ * @throws {@link PublicError.Brandpay.UserCancelError} 사용자가 비밀번호 변경을 취소한 경우
+ * @throws {@link PublicError.Brandpay.NotRegisteredRedirectUrlError} redirectUrl이 등록되지 않은 경우
+ * @throws {@link PublicError.Brandpay.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
+ * @throws {@link PublicError.Brandpay.InvalidParametersError} 파라미터가 올바르지 않은 경우
+ * @throws {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
+ *
+ * @returns
+ *
+ */
+type ChangePassword = () => Promise<void>;
+
+/**
+ * 새로운 결제수단을 등록합니다
+ *
+ *
+ * @example
+ * ```javascript
+ * brandpay.addPaymentMethod();
+ * ```
+ *
+ * @throws {@link PublicError.Brandpay.UserCancelError} 사용자가 결제수단 등록을 취소한 경우
+ * @throws {@link PublicError.Brandpay.NotRegisteredRedirectUrlError} redirectUrl이 등록되지 않은 경우
+ * @throws {@link PublicError.Brandpay.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
+ * @throws {@link PublicError.Brandpay.InvalidParametersError} 파라미터가 올바르지 않은 경우
+ * @throws {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
+ *
+ * @returns
+ */
+type AddPaymentMethod = () => Promise<void>;
+
+/**
+ * 설정 화면을 엽니다
+ *
+ *
+ * @example
+ * ```javascript
+ * brandpay.openSettings();
+ * ```
+ *
+ *
+ * @throws {@link PublicError.Brandpay.UserCancelError} 사용자가 설정 화면을 닫은 경우
+ * @throws {@link PublicError.Brandpay.NotRegisteredRedirectUrlError} redirectUrl이 등록되지 않은 경우
+ * @throws {@link PublicError.Brandpay.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
+ * @throws {@link PublicError.Brandpay.InvalidParametersError} 파라미터가 올바르지 않은 경우
+ * @throws {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
+ */
+type OpenSettings = () => Promise<void>;
+
+/**
+ * 원터치 결제 설정을 변경합니다
+ *
+ *
+ * @example
+ * ```javascript
+ * brandpay.changeOneTouchPay();
+ * ```
+ *
+ * @throws {@link PublicError.Brandpay.UserCancelError} 사용자가 원터치 결제 설정 화면을 닫은 경우
+ * @throws {@link PublicError.Brandpay.NeedMerchantOneTouchSettingError} 가맹점에서 원터치 결제 설정을 하지 않은 경우
+ * @throws {@link PublicError.Brandpay.NotRegisteredRedirectUrlError} redirectUrl이 등록되지 않은 경우
+ * @throws {@link PublicError.Brandpay.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
+ * @throws {@link PublicError.Brandpay.InvalidParametersError} 파라미터가 올바르지 않은 경우
+ * @throws {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
+ *
+ * @returns
+ */
+type ChangeOneTouchPay = () => Promise<void>;
+
+/**
+ * 원터치결제가 활성화되어있는지 확인합니다
+ *
+ *
+ * @example
+ * ```javascript
+ * const result = await brandpay.isOneTouchPayEnabled();
+ * alert(result);
+ * ```
+ *
+ * @throws {@link PublicError.Brandpay.NeedAgreementWithTermsError} 약관 동의가 필요한 경우
+ * @throws {@link PublicError.Brandpay.NeedMerchantOneTouchSettingError} 가맹점에서 원터치 결제 설정을 하지 않은 경우
+ * @throws {@link PublicError.Brandpay.NotRegisteredRedirectUrlError} redirectUrl이 등록되지 않은 경우
+ * @throws {@link PublicError.Brandpay.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
+ * @throws {@link PublicError.Brandpay.InvalidParametersError} 파라미터가 올바르지 않은 경우
+ * @throws {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
+ */
+type IsOneTouchPayEnabled = () => Promise<{
+    /**
+     * 원터치결제 활성화 여부입니다. 원터치결제가 설정되어 있다면 `true`, 설정되어 있지 않으면 `false`입니다.
+     */
+    isEnabled: boolean;
+}>;
+
+interface TossPaymentsBrandpay {
+    /**
+     * 브랜드페이 결제창을 띄웁니다. [자세히 >](#brandpayrequestpayment)
+     */
+    requestPayment: RequestPayment$1;
+    /**
+     * 브랜드페이 결제 비밀번호를 변경하는 창을 띄웁니다. [자세히 >](#brandpaychangepassword)
+     */
+    changePassword: ChangePassword;
+    /**
+     * 브랜드페이에 새로운 결제수단을 추가합니다. [자세히 >](#brandpayaddpaymentmethod)
+     */
+    addPaymentMethod: AddPaymentMethod;
+    /**
+     * 브랜드페이 결제 관리 설정창을 띄웁니다. [자세히 >](#brandpayopensettings)
+     */
+    openSettings: OpenSettings;
+    /**
+     * 원터치결제 설정을 변경합니다. [자세히 >](#brandpaychangeonetouchpay)
+     */
+    changeOneTouchPay: ChangeOneTouchPay;
+    /**
+     * 원터치결제 활성화 여부를 확인합니다. [자세히 >](#brandpayisonetouchpayenabled)
+     */
+    isOneTouchPayEnabled: IsOneTouchPayEnabled;
+}
+
+interface PaymentRequest {
+    /**
+     * 결제 금액 정보입니다.
+     */
+    amount: Amount;
+    /**
+     * 구매상품입니다. 예를 들면 `생수 외 1건` 같은 형식입니다. 최대 길이는 100자입니다.
+     */
+    orderName: string;
+    /**
+     * 주문번호입니다. 각 주문을 구분하는 무작위한 고유값을 생성하세요. 영문 대소문자, 숫자, 특수문자 `-`, `_`, `=`로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
+     */
+    orderId: string;
+    /**
+     * 구매자명입니다. 최대 길이는 100자입니다.
+     */
+    customerName?: string;
+    /**
+     * 구매자 이메일입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다.
+     */
+    customerEmail?: string;
+    /**
+     * 구매자의 휴대폰 번호입니다. 가상계좌 안내, 퀵계좌이체 휴대폰 번호 자동 완성에 사용되고 있어요.
+     */
+    customerMobilePhone?: string;
+    /**
+     * 결제 금액 중 면세 금액입니다. 면세 상점 혹은 복합 과세 상점으로 계약된 상점만 사용하세요. 자세한 내용은 세금 처리 가이드에서 확인하세요.
+     */
+    taxFreeAmount?: number;
+    /**
+     * 결제창이 열리는 프레임입니다.
+     * `iframe` 또는 현재 브라우저 화면(`self`)에서 등록창을 열 수 있어요. 기본 값은 `iframe`입니다.
+     */
+    windowTarget?: 'iframe' | 'self';
+}
+
+interface CardPaymentRequest extends PaymentRequest {
+    /**
+     * 결제수단입니다. `CARD`로 설정하면 카드/간편결제 통합결제창, 카드・간편결제 자체창을 사용할 수 있어요.
+     */
+    method: 'CARD';
+    /**
+     * 카드 결제 정보입니다.
+     */
+    card?: {
+        /**
+         * 에스크로 적용 여부입니다. `true`로 설정하면 구매자가 반드시 에스크로 적용에 동의해야 결제가 완료돼요. `false`로 설정하거나 파라미터를 설정하지 않으면 에스크로 적용을 구매자 선택에 맡겨요.
+         */
+        useEscrow?: boolean;
+        /**
+         * 과세를 제외한 결제 금액(컵 보증금 등)입니다.
+         * 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다.
+         */
+        taxExemptionAmount?: number;
+        /**
+         * 결제창을 여는 방법입니다. `DEFAULT`는 카드/간편결제 통합결제창을 열고, `DIRECT`는 카드 또는 간편결제의 자체창을 열어요.
+         * 기본 값은 `DEFAULT`입니다.
+         */
+        flowMode?: 'DIRECT' | 'DEFAULT';
+        /**
+         * 카드사 코드입니다. `flowMode` 값에 따라 아래와 같이 다르게 동작해요.
+         * `flowMode`가 `DIRECT`일 때는 입력한 코드의 카드사 앱이 열려요.
+         * `flowMode`가 `DEFAULT`일 때는 통합결제창에 입력한 코드의 카드사만 보여요.
+         */
+        cardCompany?: string;
+        /**
+         * 간편결제 코드입니다. `flowMode` 값에 따라 아래와 같이 다르게 동작해요.
+         * `flowMode`가 `DIRECT`일 때는 입력한 코드의 간편결제 앱이 열려요.
+         * `flowMode`가 `DEFAULT`일 때는 통합결제창에 입력한 코드의 간편결제만 보여요.
+         */
+        easyPay?: string;
+        /**
+         * 5만원 이상의 신용카드 결제에 적용되는 할부 개월 수입니다.
+         * 예를 들어, `6`으로 설정하면 할부 개월 수가 6개월로 고정돼요. 자체창에서는 구매자가 할부 개월 수를 볼 수 없으니 사전에 충분히 안내를 해주세요.
+         * 0(일시불), 2~12 값으로 설정할 수 있고 `maxCardInstallmentPlan` 파라미터와 함께 사용할 수 없어요.
+         */
+        cardInstallmentPlan?: number;
+        /**
+         * 5만원 이상의 신용카드 결제에 적용할 수 있는 최대 할부 개월 수입니다.
+         * 예를 들어, `6`으로 설정하면 구매자는 일시불부터 6개월 할부를 선택할 수 있어요. 0(일시불), 2~12 값으로 설정할 수 있고 `cardInstallmentPlan` 파라미터와 함께 사용할 수 없어요.
+         */
+        maxCardInstallmentPlan?: number;
+        /**
+         * 5만원 이상의 신용카드 결제에 적용할 수 있는 **상점 부담 무이자** 할부 정보입니다.
+         * 구매자가 선택한 카드, 할부 개월 수가 배열에 등록한 정보와 같다면 무이자가 할부가 자동으로 적용돼요.
+         */
+        freeInstallmentPlans?: Array<{
+            /**
+             * 상점 부담 무이자를 적용할 카드사 코드입니다.
+             */
+            company: string;
+            /**
+             * 상점 부담 무이자를 적용할 할부 개월입니다.
+             */
+            months: number[];
+        }>;
+        /**
+         * 카드사 포인트 사용 여부입니다. `true`로 설정하면 카드사 포인트 사용이 체크된 상태로 결제창이 열려요. `false`로 설정하거나 값을 넣지 않으면 구매자가 직접 카드사 포인트 사용 여부를 선택할 수 있어요.
+         *
+         * \* 추가 계약이 필요한 파라미터입니다. 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.
+         */
+        useCardPoint?: boolean;
+        /**
+         * 앱카드 단독 사용 여부입니다. 'true'로 설정하면 카드사의 앱카드만 열려요. 국민, 농협, 롯데, 삼성, 신한, 우리, 현대 카드 결제에 적용할 수 있어요.
+         */
+        useAppCardOnly?: boolean;
+        /**
+         * 카드사의 프로모션 코드입니다. 프로모션은 `flowMode`가 `DIRECT`로 설정된 자체창 결제에만 사용할 수 있어요. 프로모션 조회 API로 적용할 수 있는 프로모션 코드를 확인하세요.
+         */
+        discountCode?: string;
+        /**
+         * 시간으로 설정하는 결제가 기한입니다. 설정할 수 있는 최대 값은 2160시간(90일)입니다.
+         * 기한이 지나고 시도하는 결제는 실패해요. 예를 들어 `24`로 설정하면, 결제 요청 시점으로부터 24시간 동안 결제할 수 있어요.
+         */
+        validHours?: number;
+        /**
+         * 특정일로 설정하는 결제 기한입니다. `yyyy-MM-dd'T'HH:mm:ss` ISO 8601 형식입니다.
+         * 기한이 지나고 시도하는 결제는 실패해요. 예를 들어 `2025-01-01T00:00:00`으로 설정하면, 2024년 12월 31일 23:59까지 결제할 수 있어요.
+         */
+        dueDate?: string;
+        escrowProducts?: Array<{
+            /**
+             * 각 상품의 고유 ID입니다.
+             */
+            id?: string;
+            /**
+             * 상품명입니다.
+             */
+            name?: string;
+            /**
+             * 내 상점에서 사용하는 상품 관리 코드입니다.
+             */
+            code?: string;
+            /**
+             * 상품의 1개의 개별 가격입니다.
+             */
+            unitPrice?: number;
+            /**
+             * 상품 구매 수량입니다.
+             */
+            quantity?: number;
+        }>;
+    };
+}
+
+interface VirtualAccountPaymentRequest extends PaymentRequest {
+    /**
+     * 결제수단입니다. 가상계좌 결제창을 열려면 `VIRTUAL_ACCOUNT`로 설정하세요.
+     */
+    method: 'VIRTUAL_ACCOUNT';
+    /**
+     * 가상계좌 결제 정보입니다.
+     */
+    virtualAccount?: {
+        /**
+         * 과세를 제외한 결제 금액(컵 보증금 등)입니다.
+         */
+        taxExemptionAmount?: number;
+        /**
+         * 현금영수증 발급 용도입니다.
+         */
+        cashReceipt?: {
+            type: '소득공제' | '지출증빙' | '미발행';
+        };
+        /**
+         * 에스크로 적용 여부입니다.
+         */
+        useEscrow?: boolean;
+        escrowProducts?: Array<{
+            /**
+             * 각 상품의 고유 ID입니다.
+             */
+            id?: string;
+            /**
+             * 상품명입니다.
+             */
+            name?: string;
+            /**
+             * 내 상점에서 사용하는 상품 관리 코드입니다.
+             */
+            code?: string;
+            /**
+             * 상품의 1개의 개별 가격입니다.
+             */
+            unitPrice?: number;
+            /**
+             * 상품 구매 수량입니다.
+             */
+            quantity?: number;
+        }>;
+        /**
+         * 시간으로 설정하는 결제가 기한입니다. 설정할 수 있는 최대 값은 2160시간(90일)입니다.
+         * 기한이 지나고 시도하는 결제는 실패해요. 예를 들어 `24`로 설정하면, 결제 요청 시점으로부터 24시간 동안 결제할 수 있어요.
+         */
+        validHours?: number;
+        /**
+         * 특정일로 설정하는 결제 기한입니다. `yyyy-MM-dd'T'HH:mm:ss` ISO 8601 형식입니다.
+         * 기한이 지나고 시도하는 결제는 실패해요. 예를 들어 `2025-01-01T00:00:00`으로 설정하면, 2024년 12월 31일 23:59까지 결제할 수 있어요.
+         */
+        dueDate?: string;
+    };
+}
+
+interface TransferPaymentRequest extends PaymentRequest {
+    /**
+     * 결제수단입니다. `TRANSFER`로 설정하면 퀵계좌이체 결제창이 열려요.
+     */
+    method: 'TRANSFER';
+    /**
+     * 계좌이체 정보입니다.
+     */
+    transfer?: {
+        /**
+         * 과세를 제외한 결제 금액(컵 보증금 등)입니다.
+         */
+        taxExemptionAmount?: number;
+        /**
+         * 현금영수증 정보입니다.
+         */
+        cashReceipt?: {
+            /**
+             * 현금영수증 발급 용도입니다.
+             */
+            type: '소득공제' | '지출증빙' | '미발행';
+        };
+        /**
+         * 에스크로 적용 여부입니다. `true`로 설정하면 구매자가 반드시 에스크로 적용에 동의해야 결제가 완료돼요.
+         * `false`로 설정하거나 파라미터를 설정하지 않으면 에스크로 적용을 구매자 선택에 맡겨요.
+         */
+        useEscrow?: boolean;
+        /**
+         * 에스크로 상품 정보입니다.
+         * 여러 가지의 상품을 결제했다면 각 상품의 정보를 입력하세요. 예를 들어, 구매자가 세 가지 종류의 상품을 구매했다면 배열의 길이는 3이어야 합니다.
+         */
+        escrowProducts?: Array<{
+            /**
+             * 각 상품의 고유 ID입니다.
+             */
+            id?: string;
+            /**
+             * 상품명입니다.
+             */
+            name?: string;
+            /**
+             * 내 상점에서 사용하는 상품 관리 코드입니다.
+             */
+            code?: string;
+            /**
+             * 상품의 1개의 개별 가격입니다.
+             */
+            unitPrice?: number;
+            /**
+             * 상품 구매 수량입니다.
+             */
+            quantity?: number;
+        }>;
+        /**
+         * 시간으로 설정하는 결제가 기한입니다. 설정할 수 있는 최대 값은 2160시간(90일)입니다.
+         * 기한이 지나고 시도하는 결제는 실패해요. 예를 들어 `24`로 설정하면, 결제 요청 시점으로부터 24시간 동안 결제할 수 있어요.
+         */
+        validHours?: number;
+        /**
+         * 특정일로 설정하는 결제 기한입니다. `yyyy-MM-dd'T'HH:mm:ss` ISO 8601 형식입니다.
+         * 기한이 지나고 시도하는 결제는 실패해요. 예를 들어 `2025-01-01T00:00:00`으로 설정하면, 2024년 12월 31일 23:59까지 결제할 수 있어요.
+         */
+        dueDate?: string;
+    };
+}
+
+interface MobilePhonePaymentRequest extends PaymentRequest {
+    /**
+     * 결제수단입니다. `MOBILE_PHONE`으로 설정하면 휴대폰 결제창이 열려요.
+     */
+    method: 'MOBILE_PHONE';
+}
+
+interface GiftCertificatePaymentRequest extends PaymentRequest {
+    /**
+     * 결제수단입니다. 토스페이먼츠는 세 종류의 상품권을 지원해요: 문화상품권(`CULTURE_GIFT_CERTIFICATE`), 도서문화상품권(`BOOK_GIFT_CERTIFICATE`), 게임문화상품권(`GAME_GIFT_CERTIFICATE`).
+     */
+    method: 'CULTURE_GIFT_CERTIFICATE' | 'BOOK_GIFT_CERTIFICATE' | 'GAME_GIFT_CERTIFICATE';
+}
+
+interface ForeignEasyPayPaymentRequest extends PaymentRequest {
+    /**
+     * 결제수단입니다. `FOREIGN_EASY_PAY`로 설정하면 PayPal 해외 간편결제를 사용할 수 있어요.
+     */
+    method: 'FOREIGN_EASY_PAY';
+    /**
+     * 해외 간편결제 정보입니다.
+     */
+    foreignEasyPay: {
+        /**
+         * 해외간편결제 코드입니다. 현재는 `PAYPAL`만 지원하고 있어요.
+         */
+        provider: string;
+        /**
+         * 구매자가 결제한 국가입니다. ISO-3166의 두 자리 국가 코드를 입력하세요.
+         */
+        country: string;
+        /**
+         * 구매 상품 정보입니다. 여러 가지의 상품을 결제했다면 각 상품의 정보를 입력하세요. 예를 들어, 구매자가 세 가지 종류의 상품을 구매했다면 배열의 길이는 3이어야 합니다.
+         *
+         * PayPal에서 제공하는 판매자 보호를 받고 싶다면 반드시 해당 파라미터를 사용하세요. 판매자 보호 및 위험거래 관리를 위해 PayPal에 제공돼요.
+         */
+        products?: Array<{
+            /**
+             * 상품명입니다.
+             */
+            name: string;
+            /**
+             * 상품의 구매 수량입니다.
+             */
+            quantity: number;
+            /**
+             * 상품의 1개의 개별 가격입니다.
+             */
+            unitAmount: number;
+            /**
+             * 결제 통화입니다.
+             */
+            currency: string;
+            /**
+             * 상품 설명입니다.
+             */
+            description: string;
+        }>;
+        /**
+         * 배송 정보입니다.
+         */
+        shipping?: {
+            /**
+             * 수령인입니다.
+             */
+            fullName?: string;
+            /**
+             * 배송 주소입니다.
+             */
+            address?: {
+                /**
+                 * 국가입니다.
+                 */
+                country: string;
+                /**
+                 * 주소입니다. 도로명 및 건물(Street, Apt), 번지 정보입니다.
+                 */
+                line1?: string;
+                /**
+                 * 상세 주소입니다. 번지 및 동 호수 정보를 입력하세요.
+                 */
+                line2?: string;
+                /**
+                 * 주(State, Province, Region) 정보입니다. 국가의 도시 체계에 따라 없는 경우가 있습니다.
+                 */
+                area1?: string;
+                /**
+                 * 도시입니다.
+                 */
+                area2: string;
+                /**
+                 * 배송지 우편번호입니다. 중국, 일본, 프랑스, 독일 등 [일부 국가](https://developer.paypal.com/api/rest/reference/orders/v2/country-address-requirements/#link-countryandregionaddressrequirements)에서는 필수 파라미터입니다
+                 */
+                postalCode?: string;
+            };
+        };
+        /**
+         * 특정 해외간편결제 수단에만 필요한 정보입니다.
+         */
+        paymentMethodOptions?: {
+            /**
+             * PayPal 결제에 추가로 필요한 정보입니다.
+             */
+            paypal?: {
+                /**
+                 * PayPal에서 추가로 요청하는 STC(Set Transaction Context) 정보입니다. 이 정보는 토스페이먼츠에서 관리하지 않으며, PayPal에서 부정거래, 결제 취소, 환불 등 리스크 관리에 활용합니다.
+                 * 결제 거래의 안전성과 신뢰성을 확보하려면 이 정보를 전달해야 합니다. [PayPal STC 문서](https://static.tosspayments.com/public/STC.pdf)를 참고해서 업종에 따라 필요한 파라미터를 추가해주세요.
+                 * 문서의 표에 있는 ‘Data Field Name’ 컬럼 값을 객체의 ‘key’로, ‘Description’에 맞는 값을 객체의 ‘value’로 넣어주시면 됩니다.
+                 */
+                setTransactionContext?: unknown;
+            };
+        };
+    };
+}
+
+interface RequestPaymentResult {
+    /**
+     * 토스페이먼츠에서 발급하는 결제 식별 키입니다. 결제 승인, 조회, 취소 등에 사용되니 반드시 저장하세요.
+     */
+    paymentKey: string;
+    /**
+     * 주문번호입니다. 결제를 요청할 때 호출한 `requestPayment()` 메서드로 넘긴 `orderId` 값과 같은지 확인하세요.
+     */
+    orderId: string;
+    /**
+     * 결제 금액 정보입니다. `requestPayment()` 메서드로 넘긴 `amount` 값과 같은지 확인하세요.
+     */
+    amount: Amount;
+}
+
+interface BillingAuthRequest {
+    /**
+     * 자동결제(빌링)에 등록할 결제수단입니다. 토스페이먼츠는 현재 신용·체크카드만 자동결제만 지원해요.
+     *
+     */
+    method: 'CARD';
+    /**
+     * 카드 등록이 성공하면 리다이렉트되는 URL입니다. 리다이렉트되면 URL의 쿼리 파라미터로 `authKey`, `customerKey`가 추가돼요. 값을 검증하고 [빌링키 발급 API](/reference#authkey로-카드-빌링키-발급)를 호출하세요.
+     * 반드시 오리진을 포함해야 합니다.
+     *
+     * @example https://www.example.com/success
+     */
+    successUrl: string;
+    /**
+     * 카드 등록이 실패하면 리다이렉트되는 URL입니다. 리다이렉트되면 URL의 쿼리 파라미터로 에러 코드와 메시지를 확인할 수 있어요.
+     * 반드시 오리진을 포함해야 합니다.
+     */
+    failUrl: string;
+    /**
+     * 구매자명입니다. 상점관리자 및 결제내역 이메일에 사용됩니다. 최대 길이는 100자입니다.
+     */
+    customerName?: string;
+    /**
+     * 구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다.
+     */
+    customerEmail?: string;
+    /**
+     * 카드 등록창이 열리는 프레임입니다. iframe 또는 현재 브라우저 화면(self)에서 등록창을 열 수 있습니다. 기본 값은 `iframe`입니다.
+     * 모바일 웹에서는 windowTarget 값과 상관없이 항상 새로운 결제창으로 이동합니다.
+     *
+     * @default 'iframe'
+     */
+    windowTarget?: 'iframe' | 'self';
+}
+
+/**
+ *
+ * @throws {@link PublicError.PaymentGateway.UserCancelError} 사용자가 결제창을 닫은 경우
+ * @throws {@link PublicError.PaymentGateway.InvalidAmountValueError} 결제 금액이 유효하지 않은 경우
+ * @throws {@link PublicError.PaymentGateway.InvalidAmountCurrencyError} 결제 금액의 통화가 유효하지 않은 경우
+ * @throws {@link PublicError.PaymentGateway.BelowZeroAmountError} 결제 금액이 0 미만인 경우
+ * @throws {@link PublicError.PaymentGateway.NotSupportedPromiseError} promise 방식을 지원하지 않는 환경인 경우
+ * @throws {@link PublicError.PaymentGateway.NotSupportedMethodError} 가맹점에서 정의되지 않은 method를 넘겨준 경우
+ * @throws {@link PublicError.PaymentGateway.IncorrectSuccessUrlFormatError} 가맹점에서 유효하지 않은 successUrl을 넘겨준 경우
+ * @throws {@link PublicError.PaymentGateway.IncorrectFailUrlFormatError} 가맹점에서 유효하지 않은 failUrl을 넘겨준 경우
+ * @throws {@link PublicError.PaymentGateway.PaymentRequestFailError} 결제에 실패한 경우
+ * @throws {@link PublicError.PaymentGateway.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
+ * @throws {@link PublicError.PaymentGateway.InvalidParametersError} 파라미터가 올바르지 않은 경우
+ * @throws {@link PublicError.PaymentGateway.UnknownError} 알 수 없는 오류가 발생한 경우
+ */
+type RequestPayment = RequestCardPaymentWithRedirection & RequestCardPaymentWithPromise & RequestVirtualAccountPaymentWithRedirection & RequestVirtualAccountPaymentWithPromise & RequestTransferPaymentWithRedirection & RequestTransferPaymentWithPromise & RequestMobilePhonePaymentWithRedirection & RequestMobilePhonePaymentWithPromise & RequestGiftCertificatePaymentWithRedirection & RequestGiftCertificatePaymentWithPromise & RequestForeignEasyPayPaymentWithRedirection & RequestForeignEasyPayPaymentWithPromise;
+/**
+ * @docsAlias 카드(Promise 방식)
+ * @returns `WidgetPaymentResult` 객체가 응답됩니다. 객체 필드를 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해야 결제가 최종적으로 완료돼요.
+ * @param {RequestCardPaymentWithPromise} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ *  ```javascript
+ *  payment.requestPayment({
+      method: "CARD",
+      amount: {
+        currency: "KRW",
+        value: 50000,
+      },
+      orderId: "<UniqueId name='orderId.card' />",
+      orderName: "토스 티셔츠 외 2건",
+      customerEmail: "customer123@gmail.com",
+      customerName: "김토스",
+      customerMobilePhone: "01012341234",
+      windowTarget: "iframe",
+      card: {
+        useEscrow: false,
+        flowMode: "DEFAULT",
+        useCardPoint: false,
+        useAppCardOnly: false,
+      },
+    });
+ * ```
+ */
+type RequestCardPaymentWithPromise = (paymentRequest: CardPaymentRequest) => Promise<RequestPaymentResult>;
+/**
+ * @docsAlias 카드(Redirect 방식)
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * ```plain theme="grey" copyable="false"
+ * {successUrl}?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 {RequestCardPaymentWithRedirection} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ *  ```javascript
+ *  payment.requestPayment({
+      method: "CARD",
+      amount: {
+        currency: "KRW",
+        value: 50000,
+      },
+      orderId: "<UniqueId name='orderId.card' />",
+      orderName: "토스 티셔츠 외 2건",
+      successUrl: window.location.origin + "/success.html",
+      failUrl: window.location.origin + "/fail.html",
+      customerEmail: "customer123@gmail.com",
+      customerName: "김토스",
+      customerMobilePhone: "01012341234",
+      card: {
+        useEscrow: false,
+        flowMode: "DEFAULT",
+        useCardPoint: false,
+        useAppCardOnly: false,
+      },
+    })
+ * ```
+ */
+type RequestCardPaymentWithRedirection = (paymentRequest: WithRedirection<CardPaymentRequest>) => Promise<void>;
+/**
+ * @docsAlias 가상계좌(Promise 방식)
+ * @returns `WidgetPaymentResult` 객체가 응답됩니다. 객체 필드를 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해야 결제가 최종적으로 완료돼요.
+ * @param {VirtualAccountPaymentRequest} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ *  ```javascript
+ *  payment.requestPayment({
+      method: "VIRTUAL_ACCOUNT",
+      amount: {
+        currency: "KRW",
+        value: 50000,
+      },
+      orderId: "<UniqueId name='orderId.virtualaccount' />",
+      orderName: "토스 티셔츠 외 2건",
+      customerEmail: "customer123@gmail.com",
+      customerName: "김토스",
+      customerMobilePhone: "01012341234",
+      windowTarget: "iframe",
+      virtualAccount: {
+        cashReceipt: {
+          type: "소득공제",
+        },
+        useEscrow: false,
+        validHours: 24,
+      },
+    });
+ * ```
+ */
+type RequestVirtualAccountPaymentWithPromise = (paymentRequest: VirtualAccountPaymentRequest) => Promise<RequestPaymentResult>;
+/**
+ * @docsAlias 가상계좌(Redirect 방식)
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * ```plain theme="grey" copyable="false"
+ * {successUrl}?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 {RequestVirtualAccountPaymentWithRedirection} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ *  ```javascript
+ *  payment.requestPayment({
+      method: "VIRTUAL_ACCOUNT",
+      amount: {
+        currency: "KRW",
+        value: 50000,
+      },
+      orderId: "<UniqueId name='orderId.virtualaccount' />",
+      orderName: "토스 티셔츠 외 2건",
+      successUrl: window.location.origin + "/success.html",
+      failUrl: window.location.origin + "/fail.html",
+      customerEmail: "customer123@gmail.com",
+      customerName: "김토스",
+      customerMobilePhone: "01012341234",
+      virtualAccount: {
+        cashReceipt: {
+          type: "소득공제",
+        },
+        useEscrow: false,
+        validHours: 24,
+      },
+    });
+ * ```
+ */
+type RequestVirtualAccountPaymentWithRedirection = (paymentRequest: WithRedirection<VirtualAccountPaymentRequest>) => Promise<void>;
+/**
+ * @docsAlias 계좌이체(Promise 방식)
+ * @returns `WidgetPaymentResult` 객체가 응답됩니다. 객체 필드를 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해야 결제가 최종적으로 완료돼요.
+ * @param {RequestTransferPaymentWithPromise} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ *  ```javascript
+ *  payment.requestPayment({
+      method: "TRANSFER",
+      amount: {
+        currency: "KRW",
+        value: 50000,
+      },
+      orderId: "<UniqueId name='orderId.transfer' />",
+      orderName: "토스 티셔츠 외 2건",
+      customerEmail: "customer123@gmail.com",
+      customerName: "김토스",
+      customerMobilePhone: "01012341234",
+      transfer: {
+        cashReceipt: {
+          type: "소득공제",
+        },
+        useEscrow: false,
+      },
+    });
+ * ```
+ */
+type RequestTransferPaymentWithPromise = (paymentRequest: TransferPaymentRequest) => Promise<RequestPaymentResult>;
+/**
+ * @docsAlias 계좌이체(Redirect 방식)
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * ```plain theme="grey" copyable="false"
+ * {successUrl}?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 {RequestTransferPaymentWithRedirection} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ *  ```javascript
+ *  payment.requestPayment({
+      method: "TRANSFER",
+      amount: {
+        currency: "KRW",
+        value: 50000,
+      },
+      orderId: "<UniqueId name='orderId.transfer' />",
+      orderName: "토스 티셔츠 외 2건",
+      successUrl: window.location.origin + "/success.html",
+      failUrl: window.location.origin + "/fail.html",
+      customerEmail: "customer123@gmail.com",
+      customerName: "김토스",
+      customerMobilePhone: "01012341234",
+      transfer: {
+        cashReceipt: {
+          type: "소득공제",
+        },
+        useEscrow: false,
+      },
+    });
+ * ```
+ */
+type RequestTransferPaymentWithRedirection = (paymentRequest: WithRedirection<TransferPaymentRequest>) => Promise<void>;
+/**
+ * @docsAlias 휴대폰 결제(Promise 방식)
+ * @returns `WidgetPaymentResult` 객체가 응답됩니다. 객체 필드를 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해야 결제가 최종적으로 완료돼요.
+ * @param {RequestMobilePhonePaymentWithPromise} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ *  ```javascript
+ *  payment.requestPayment({
+      method: "MOBILE_PHONE",
+      amount: {
+        currency: "KRW",
+        value: 50000,
+      },
+      orderId: "<UniqueId name='orderId.mobile' />",
+      orderName: "토스 티셔츠 외 2건",
+      customerEmail: "customer123@gmail.com",
+      customerName: "김토스",
+      customerMobilePhone: "01012341234",
+    });
+ * ```
+ */
+type RequestMobilePhonePaymentWithPromise = (paymentRequest: MobilePhonePaymentRequest) => Promise<RequestPaymentResult>;
+/**
+ * @docsAlias 휴대폰 결제(Redirect 방식)
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * ```plain theme="grey" copyable="false"
+ * {successUrl}?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 {RequestMobilePhonePaymentWithRedirection} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ *  ```javascript
+ *  payment.requestPayment({
+      method: "MOBILE_PHONE",
+      amount: {
+        currency: "KRW",
+        value: 50000,
+      },
+      orderId: "<UniqueId name='orderId.mobile' />",
+      orderName: "토스 티셔츠 외 2건",
+      successUrl: window.location.origin + "/success.html",
+      failUrl: window.location.origin + "/fail.html",
+      customerEmail: "customer123@gmail.com",
+      customerName: "김토스",
+      customerMobilePhone: "01012341234",
+    });
+ * ```
+ */
+type RequestMobilePhonePaymentWithRedirection = (paymentRequest: WithRedirection<MobilePhonePaymentRequest>) => Promise<void>;
+/**
+ * @docsAlias 상품권(Promise 방식)
+ * @returns `WidgetPaymentResult` 객체가 응답됩니다. 객체 필드를 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해야 결제가 최종적으로 완료돼요.
+ * @param {RequestGiftCertificatePaymentWithPromise} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ *  ```javascript
+ *  payment.requestPayment({
+      method: "CULTURE_GIFT_CERTIFICATE",
+      amount: {
+        currency: "KRW",
+        value: 50000,
+      },
+      orderId: "<UniqueId name='orderId.giftcertificate' />",
+      orderName: "토스 티셔츠 외 2건",
+      customerEmail: "customer123@gmail.com",
+      customerName: "김토스",
+      customerMobilePhone: "01012341234",
+    });
+ * ```
+ */
+type RequestGiftCertificatePaymentWithPromise = (paymentRequest: GiftCertificatePaymentRequest) => Promise<RequestPaymentResult>;
+/**
+ * @docsAlias 상품권(Redirect 방식)
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * ```plain theme="grey" copyable="false"
+ * {successUrl}?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 {RequestGiftCertificatePaymentWithRedirection} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ *  ```javascript
+ *  payment.requestPayment({
+      method: "CULTURE_GIFT_CERTIFICATE",
+      amount: {
+        currency: "KRW",
+        value: 50000,
+      },
+      orderId: "<UniqueId name='orderId.giftcertificate' />",
+      orderName: "토스 티셔츠 외 2건",
+      successUrl: window.location.origin + "/success.html",
+      failUrl: window.location.origin + "/fail.html",
+      customerEmail: "customer123@gmail.com",
+      customerName: "김토스",
+      customerMobilePhone: "01012341234",
+    });
+ * ```
+ */
+type RequestGiftCertificatePaymentWithRedirection = (paymentRequest: WithRedirection<GiftCertificatePaymentRequest>) => Promise<void>;
+/**
+ * @docsAlias 해외 간편결제(Promise 방식)
+ * @returns `WidgetPaymentResult` 객체가 응답됩니다. 객체 필드를 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해야 결제가 최종적으로 완료돼요.
+ * @param {RequestForeignEasyPayPaymentWithPromise} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ *  ```javascript
+ *  payment.requestPayment({
+      method: "FOREIGN_EASY_PAY",
+      amount: {
+        currency: "USD",
+        value: 5000,
+      },
+      orderId: "<UniqueId name='orderId.paypal' />",
+      orderName: "토스 티셔츠 외 2건",
+      customerEmail: "customer123@gmail.com",
+      customerName: "김토스",
+      customerMobilePhone: "01012341234",
+      foreignEasyPay: {
+        provider: "PAYPAL",
+        country: "KR",
+      },
+    });
+ * ```
+ */
+type RequestForeignEasyPayPaymentWithPromise = (paymentRequest: ForeignEasyPayPaymentRequest) => Promise<RequestPaymentResult>;
+/**
+ * @docsAlias 해외 간편결제(Redirect 방식)
+ * @returns 결제 요청이 성공하면 파라미터로 설정한 `successUrl`로 이동해요. 쿼리 파라미터의 `amount` 값이 파라미터로 설정한 `amount`와 같은지 반드시 확인하고 [결제 승인 API](/reference#결제-승인)를 호출해서 결제를 완료하세요.
+ * ```plain theme="grey" copyable="false"
+ * {successUrl}?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 {RequestForeignEasyPayPaymentWithRedirection} paymentRequest 결제 요청 정보입니다.
+ *
+ * @example
+ *  ```javascript
+ *  payment.requestPayment({
+      method: "FOREIGN_EASY_PAY",
+      amount: {
+        currency: "USD",
+        value: 5000,
+      },
+      orderId: "<UniqueId name='orderId.paypal' />",
+      orderName: "토스 티셔츠 외 2건",
+      successUrl: window.location.origin + "/success.html",
+      failUrl: window.location.origin + "/fail.html",
+      customerEmail: "customer123@gmail.com",
+      customerName: "김토스",
+      customerMobilePhone: "01012341234",
+      foreignEasyPay: {
+        provider: "PAYPAL",
+        country: "KR",
+      },
+    });
+ * ```
+ */
+type RequestForeignEasyPayPaymentWithRedirection = (paymentRequest: WithRedirection<ForeignEasyPayPaymentRequest>) => Promise<void>;
+
+/**
+ * 자동결제(빌링) 결제창을 열어 구매자의 카드 등록을 요청하는 메서드입니다.
+ *
+ * @param {BillingAuthRequest} billingAuthRequest 자동결제(빌링) 카드 등록에 필요한 정보입니다.
+ * @returns URL이 이동하기 때문에 `void`가 응답됩니다. 파라미터로 설정한 `successUrl` 또는 `failUrl`에서 카드 등록 결과를 확인하고 [빌링키 발급 API](/reference#authkey로-카드-빌링키-발급)를 호출해야 자동결제를 할 수 있어요.
+ *
+ * @example
+ * ```javascript
+ * payment.requestBillingAuth({
+ *   method: 'CARD',
+ *   amount: {
+ *     currency: 'KRW',
+ *     value: 50000,
+ *   },
+ *   successUrl: window.location.origin + '/payment/billing.html',
+ *   failUrl: window.location.origin + '/fail.html',
+ *   customerEmail: 'customer123@gmail.com',
+ *   customerName: '김토스',
+ * });
+ * ```
+ *
+ * @throws {@link PublicError.PaymentGateway.UserCancelError} 사용자가 자동결제 인증창을 닫은 경우
+ * @throws {@link PublicError.PaymentGateway.NotSupportedMethodError} 가맹점에서 정의되지 않은 method를 넘겨준 경우
+ * @throws {@link PublicError.PaymentGateway.IncorrectSuccessUrlFormatError} 가맹점에서 유효하지 않은 successUrl을 넘겨준 경우
+ * @throws {@link PublicError.PaymentGateway.IncorrectFailUrlFormatError} 가맹점에서 유효하지 않은 failUrl을 넘겨준 경우
+ * @throws {@link PublicError.PaymentGateway.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
+ * @throws {@link PublicError.PaymentGateway.InvalidParametersError} 파라미터가 올바르지 않은 경우
+ * @throws {@link PublicError.PaymentGateway.UnknownError} 알 수 없는 오류가 발생한 경우
+ */
+type RequestBillingAuth = (billingAuthRequest: BillingAuthRequest) => Promise<void>;
+
+interface TossPaymentsPaymentGateway {
+    /**
+     * 결제창을 띄웁니다. [자세히 >](#paymentrequestpayment)
+     */
+    requestPayment: RequestPayment;
+    /**
+     * 자동결제(빌링) 카드 등록창을 띄웁니다. [자세히 >](#paymentrequestbillingauth)
+     */
+    requestBillingAuth: RequestBillingAuth;
+}
+interface TossPaymentsInstance {
+    /**
+     *
+     * 결제위젯을 초기화합니다. [자세히 >](#결제위젯)
+     *
+     * @throw {@link PublicError.Widgets.InvalidClientKeyError} clientKey가 올바르지 않은 경우
+     * @throw {@link PublicError.Widgets.InvalidCustomerKeyError} customerKey가 올바르지 않은 경우
+     * @throw {@link PublicError.Widgets.WidgetsSDKInitializeConflictError} widgets SDK 초기화 중 충돌이 발생한 경우
+     * @throw {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
+     * @returns 아래 메서드를 호출할 수 있는 결제위젯 객체를 반환합니다.
+     * @example
+     * ```javascript
+     * // 회원 결제
+     * const widgets = tossPayments.widgets({ customerKey });
+     * // 비회원 결제
+     * // const payment = tossPayments.widgets({ customerKey: TossPayments.ANONYMOUS });
+     * ```
+     * @param {WidgetSDKInitParams} params 결제위젯 초기화 정보입니다.
+     *
+     */
+    widgets: (params: WidgetSDKInitParams) => TossPaymentsWidgets;
+    /**
+     * 브랜드페이를 초기화합니다. [자세히 >](#브랜드페이)
+     *
+     * @throw {@link PublicError.Brandpay.InvalidClientKeyError} clientKey가 올바르지 않은 경우
+     * @throw {@link PublicError.Brandpay.InvalidCustomerKeyError} customerKey가 올바르지 않은 경우
+     * @throw {@link PublicError.Brandpay.BrandpaySDKInitializeConflictError} 브랜드페이 SDK 초기화 중 충돌이 발생한 경우
+     * @throw {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
+     * @example
+     * ```javascript
+     * const brandpay = tossPayments.brandpay({
+     *   customerKey,
+     *   redirectUrl: window.location.origin + '/callback-auth',
+     * });
+     * ```
+     * @returns 아래 메서드를 호출할 수 있는 브랜드페이 객체를 반환합니다.
+     * @param {BrandpaySDKInitParams} params 브랜드페이 초기화 정보입니다.
+     *
+     */
+    brandpay: (params: BrandpaySDKInitParams) => TossPaymentsBrandpay;
+    /**
+     * 결제창을 초기화합니다. [자세히 >](#결제창)
+     *
+     * @throw {@link PublicError.Payment.InvalidClientKeyError} clientKey가 올바르지 않은 경우
+     * @throw {@link PublicError.Payment.InvalidCustomerKeyError} customerKey가 올바르지 않은 경우
+     * @throw {@link PublicError.Payment.PaymentSDKInitializeConflictError} payment SDK 초기화 중 충돌이 발생한 경우
+     * @throw {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
+     * @example
+     * ```javascript
+     * // 회원 결제
+     * const payment = tossPayments.payment({ customerKey });
+     *
+     * //비회원 결제
+     * // const payment = tossPayments.payment({ customerKey: TossPayments.ANONYMOUS });
+     * ```
+     * @returns 아래 메서드를 호출할 수 있는 결제창 객체를 반환합니다.
+     * @param {PaymentGatewaySDKInitParams} 결제창 초기화 정보입니다.
+     *
+     */
+    payment: (params: PaymentGatewaySDKInitParams) => TossPaymentsPaymentGateway;
+}
+/**
+ * @example
+ * ```javascript
+ * const tossPayments = TossPayments("<WidgetClientKey />");
+ * ```
+ * @param {string} clientKey 토스페이먼츠 발급하는 클라이언트 키입니다. 개발자센터의 [API 키 메뉴](https://developers.tosspayments.com/my/api-keys)에서 확인할 수 있어요.
+ *
+ * 결제위젯을 연동한다면 [결제위젯 연동 키](/reference/using-api/api-keys#결제위젯-연동-키)를 사용하세요. 결제창, 자동결제(빌링)을 연동한다면 [API 개별 연동 키](/reference/using-api/api-keys#api-개별-연동-키)를 사용하세요.
+ *
+ * @returns
+ * 아래 메서드를 호출할 수 있는 토스페이먼츠 객체를 반환합니다.
+ */
+type TossPayments = (clientKey: string) => TossPaymentsInstance;
+interface BrandpaySDKInitParams {
+    /**
+     * 구매자를 식별하는 고유 아이디입니다.
+     * 이메일・전화번호나 자동 증가하는 숫자와 같이 유추가 가능한 값은 안전하지 않아요. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요.
+     * 영문 대소문자, 숫자, 특수문자 `-`, `_`, `=`, `.`, `@` 중 최소 1개를 포함하는 최소 2자 이상 최대 50자 이하의 문자열이어야 합니다.
+     */
+    customerKey: string;
+    /**
+     * 브랜드페이 결제 과정에서 [Access Token 발급](/guides/v2/brandpay/auth)을 위해 필요한 URL입니다. Access Token은 브랜드페이 고객을 식별하고 고객의 결제 권한을 증명합니다. 값을 넣지 않으면 개발자센터의 브랜드페이 메뉴에 최초로 등록한 리다이렉트 URL이 기본값으로 들어갑니다.
+     *
+     * \* 브랜드페이 메뉴에 두 개 이상의 리다이렉트 URL을 등록한 상점은 각 도메인에 맞는 redirectUrl 값을 필수로 추가하세요.
+     */
+    redirectUrl?: string;
+}
+/**
+ * @returns 아래 메서드를 호출할 수 있는 토스페이먼츠 객체를 반환합니다.
+ */
+interface WidgetSDKInitParams {
+    /**
+     * 구매자를 식별하는 고유 아이디입니다.
+     * 이메일・전화번호나 자동 증가하는 숫자와 같이 유추가 가능한 값은 안전하지 않아요. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요.
+     * 영문 대소문자, 숫자, 특수문자 `-`, `_`, `=`, `.`, `@` 중 최소 1개를 포함하는 최소 2자 이상 최대 50자 이하의 문자열이어야 합니다.
+     */
+    customerKey: string;
+    /**
+     * 결제위젯으로 브랜드페이로 연동할 때 필요한 정보입니다.
+     */
+    brandpay?: {
+        /**
+         * 브랜드페이 결제 과정에서 [Access Token 발급](/guides/v2/brandpay/auth)을 위해 필요한 URL입니다. Access Token은 브랜드페이 고객을 식별하고 고객의 결제 권한을 증명합니다. 값을 넣지 않으면 개발자센터의 브랜드페이 메뉴에 최초로 등록한 리다이렉트 URL이 기본값으로 들어갑니다.
+         *
+         * \* 브랜드페이 메뉴에 두 개 이상의 리다이렉트 URL을 등록한 상점은 각 도메인에 맞는 redirectUrl 값을 필수로 추가하세요.
+         */
+        redirectUrl?: string;
+    };
+}
+interface PaymentGatewaySDKInitParams {
+    /**
+     * 구매자를 식별하는 고유 아이디입니다.
+     * 이메일・전화번호나 자동 증가하는 숫자와 같이 유추가 가능한 값은 안전하지 않아요. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요.
+     * 영문 대소문자, 숫자, 특수문자 `-`, `_`, `=`, `.`, `@` 중 최소 1개를 포함하는 최소 2자 이상 최대 50자 이하의 문자열이어야 합니다.
+     */
+    customerKey: string;
+}
+
+type TosspaymentsParams = Parameters<TossPayments>;
+declare function loadTossPayments(clientKey: TosspaymentsParams[0], loadOptions?: {
+    src?: string;
+}): Promise<TossPaymentsInstance>;
+
+declare const ANONYMOUS = "@@ANONYMOUS";
+
+export { ANONYMOUS, clearTossPayments, loadTossPayments };