주문서형 결제 JavaScript SDK

주문서형 결제 JavaScript SDK 메서드를 알아봅니다. widgets()로 초기화하고 setAmount()로 금액을 설정한 뒤, renderPaymentMethods()로 결제 UI를 그리고 requestPayment()로 결제를 요청하세요.

주문서형 결제는 widgets 메서드로 SDK를 초기화하고 결제 금액을 설정한 다음, 렌더 메서드를 호출해요. 마지막엔 widgets.requestPayment()로 결제를 요청합니다.

주문서형 결제를 초기화합니다. 주문서형 결제는 토스페이먼츠만의 기본 결제 서비스로, 수많은 상점을 분석해서 만든 최적의 주문서 결제 UI예요.

비회원 결제는 customerKey 대신 ANONYMOUS를 넣어요.

• params 필수 · object
  

  결제 초기화 정보입니다.

  • customerKey 필수 · string
    

    구매자를 식별하는 고유 아이디입니다.

    이메일・전화번호나 자동 증가하는 숫자와 같이 유추가 가능한 값은 안전하지 않아요. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 중 최소 1개를 포함하는 최소 22자 이상 최대 50자 이하의 문자열이어야 합니다.

  • brandpay object
    

    주문서형, 결제창형으로 브랜드페이를 연동할 때 필요한 정보입니다.

    • redirectUrl string
      

      브랜드페이 결제 과정에서 Access Token 발급을 위해 필요한 URL입니다. Access Token은 브랜드페이 고객을 식별하고 고객의 결제 권한을 증명합니다. 값을 넣지 않으면 개발자센터의 브랜드페이 메뉴에 최초로 등록한 리다이렉트 URL이 기본값으로 들어갑니다.

      * 브랜드페이 메뉴에 두 개 이상의 리다이렉트 URL을 등록한 상점은 각 도메인에 맞는 redirectUrl 값을 필수로 추가하세요.

아래 메서드를 호출할 수 있는 결제 객체를 반환합니다.

• setAmount function
  

  주문의 결제 금액을 설정합니다. 자세히 >

• renderPaymentMethods function
  

  결제 UI를 렌더링합니다. 자세히 >

• requestPayment function
  

  결제를 요청합니다. 구매자가 결제 UI에서 선택한 결제수단의 결제창을 띄워요. 자세히 >

• renderAgreement function
  

  약관 UI를 렌더링합니다. 자세히 >

결제 금액을 설정합니다. renderPaymentMethods()를 호출하기 전에 반드시 금액을 설정해주세요. 만약에 쿠폰, 할인 등으로 인해 주문서에서 결제 금액이 바뀌면 setAmount()로 결제 금액을 업데이트해주세요.

• amount 필수 · object
  

  결제 금액 정보입니다.

  • value 필수 · number
    

    결제 금액입니다.

  • currency 필수 · string
    

    결제 통화입니다. 일반결제는 KRW만 지원합니다. 해외 간편결제(PayPal)는 USD만 지원합니다.

결제를 요청합니다. 구매자가 결제 UI에서 선택한 결제수단의 결제창을 띄워요. 결제 버튼은 직접 만들어주세요.

결제 요청은 Redirect 방식과 Promise 방식을 지원하고 있어요. 결제 요청이 끝나고 결과를 확인하는 방법의 차이인데요. Redirect 방식을 선택하면 파라미터로 설정한 successUrl 또는 failUrl로 결제 요청의 결과를 확인할 수 있어요. Promise 방식을 선택하면 Promise로 돌아오는 객체로 결과를 확인할 수 있지만, Promise 방식은 모바일 환경에서 사용할 수 없어요.

• paymentRequest 필수 · object
  

  결제 요청 정보입니다.

  • orderId 필수 · string
    

    주문번호입니다. 각 주문을 구분하는 무작위한 고유값을 생성하세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.

  • orderName 필수 · string
    

    구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

  • customerEmail string
    

    구매자 이메일입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다.

  • customerName string
    

    구매자명입니다. 최대 길이는 100자입니다.

  • customerMobilePhone string
    

    구매자의 휴대폰 번호입니다. 가상계좌 안내, 퀵계좌이체 휴대폰 번호 자동 완성에 사용되고 있어요. - 없이 숫자로만 구성된 최소 8자, 최대 15자의 문자열입니다.

  • taxFreeAmount number
    

    결제 금액 중 면세 금액입니다. 면세 상점 혹은 복합 과세 상점으로 계약된 상점만 사용하세요. 자세한 내용은 세금 처리 가이드에서 확인하세요.

  • windowTarget enum
    

    브라우저에서 결제창이 열리는 프레임입니다. self, iframe 중 하나입니다.

    - self는 현재 브라우저를 결제창으로 이동시켜요. 모바일 환경에서 기본 값입니다.

    - iframe은 iframe에서 결제창이 열려요. PC 환경에서 기본 값입니다. 모바일 환경에서는 iframe을 사용할 수 없습니다.

  • metadata object
    

    결제 관련 정보를 추가할 수 있는 객체입니다. 최대 5개의 키-값(key-value) 쌍을 자유롭게 추가해주세요. 키는 [ , ] 를 사용하지 않는 최대 40자의 문자열, 값은 최대 2000자의 문자열입니다.

  • card object
    

    구매자가 카드를 선택하면 결제에 적용되는 옵션입니다.

    • taxExemptionAmount number
      

      과세를 제외한 결제 금액(컵 보증금 등)입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.

      과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다.

    • appScheme string
      

      카드/간편결제 앱에서 상점 앱으로 돌아올 때 사용됩니다. 상점의 앱 스킴을 지정하면 됩니다. 예를 들면 testapp://같은 형태입니다. 지원하는 간편결제는 페이북/ISP, 카카오페이(iOS only), 페이코, 엘페이 앱입니다.

  • transfer object
    

    구매자가 계좌이체를 선택하면 결제에 적용되는 옵션입니다.

    • useEscrow boolean
      

      에스크로 적용 여부입니다. true로 설정하면 구매자가 반드시 에스크로 적용에 동의해야 결제가 완료돼요.

      false로 설정하거나 파라미터를 설정하지 않으면 에스크로 적용을 구매자 선택에 맡겨요.

    • escrowProducts array
      

      각 상품의 상세 정보 객체를 담는 배열입니다. 에스크로를 사용하는 상점이라면 필수 파라미터입니다.

      예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다.

      • id string
        

        각 상품의 고유 ID입니다.

      • name string
        

        상품명입니다.

      • code string
        

        내 상점에서 사용하는 상품 관리 코드입니다.

      • unitPrice number
        

        상품의 1개의 개별 가격입니다.

      • quantity number
        

        상품 구매 수량입니다.

    • isCulturalExpenses boolean
      

      문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다.

  • virtualAccount object
    

    구매자가 가상계좌를 선택하면 결제에 적용되는 옵션입니다.

    • useEscrow boolean
      

      에스크로 사용 여부입니다. 값을 주지 않으면 결제창에서 고객이 직접 에스크로 결제 여부를 선택합니다.

    • escrowProducts array
      

      각 상품의 상세 정보 객체를 담는 배열입니다. 에스크로를 사용하는 상점이라면 필수 파라미터입니다.

      예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다.

      • id string
        

        각 상품의 고유 ID입니다.

      • name string
        

        상품명입니다.

      • code string
        

        내 상점에서 사용하는 상품 관리 코드입니다.

      • unitPrice number
        

        상품의 1개의 개별 가격입니다.

      • quantity number
        

        상품 구매 수량입니다.

    • cashReceipt object
      

      현금영수증 정보입니다.

      • type 필수 · enum
        

        현금영수증 발급 용도입니다. '소득공제', '지출증빙', '미발행' 중 하나입니다.

    • isCulturalExpenses boolean
      

      문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다.

  • foreignEasyPay object
    

    구매자가 해외간편결제를 선택하면 결제에 적용되는 옵션입니다.

    • country 필수 · string
      

      구매자가 위치한 국가입니다. ISO-3166의 두 자리 국가 코드를 입력하세요.

    • products array
      

      구매 상품 정보입니다. 여러 가지의 상품을 결제했다면 각 상품의 정보를 입력하세요. 예를 들어, 구매자가 세 가지 종류의 상품을 구매했다면 배열의 길이는 3이어야 합니다.

      PayPal에서 제공하는 판매자 보호를 받고 싶다면 반드시 해당 파라미터를 사용하세요. 판매자 보호 및 위험거래 관리를 위해 PayPal에 제공돼요.

      • name 필수 · string
        

        상품명입니다. 최대 길이는 100자입니다.

      • quantity 필수 · number
        

        상품의 구매 수량입니다.

      • unitAmount 필수 · number
        

        상품의 1개의 개별 가격입니다.

      • currency 필수 · string
        

        결제 통화입니다.

      • description 필수 · string
        

        상품 설명입니다.

    • shipping object
      

      배송 정보입니다.

      • fullName string
        

        수령인입니다.

      • address object
        

        배송 주소입니다.

        • country 필수 · string
          

          구매자가 위치한 국가입니다. ISO-3166의 두 자리 국가 코드를 입력하세요.

        • line1 string
          

          주소입니다. 도로명 및 건물(Street, Apt), 번지 정보입니다.

        • line2 string
          

          상세 주소입니다. 번지 및 동호수 정보를 입력하세요.

        • area1 string
          

          주(State, Province, Region) 정보입니다. 국가의 도시 체계에 따라 없는 경우가 있습니다.

        • area2 필수 · string
          

          도시입니다.

        • postalCode string
          

          배송지 우편번호입니다. 중국, 일본, 프랑스, 독일 등 일부 국가에서는 필수 파라미터입니다

    • paymentMethodOptions object
      

      특정 해외간편결제 수단에만 필요한 정보입니다.

      • paypal object
        

        PayPal 결제에 추가로 필요한 정보입니다.

        • setTransactionContext unknown
          

          PayPal에서 추가로 요청하는 STC(Set Transaction Context) 정보입니다. 이 정보는 토스페이먼츠에서 관리하지 않으며, PayPal에서 부정거래, 결제 취소, 환불 등 리스크 관리에 활용합니다.

          결제 거래의 안전성과 신뢰성을 확보하려면 이 정보를 전달해야 합니다. PayPal STC 문서를 참고해서 업종에 따라 필요한 파라미터를 추가해주세요. 문서의 표에 있는 ‘Data Field Name’ 컬럼 값을 객체의 ‘key’로, ‘Description’에 맞는 값을 객체의 ‘value’로 넣어주시면 됩니다.

  • successUrl string
    

    결제 요청이 성공하면 리다이렉트되는 URL입니다. https://www.example.com/success와 같이 오리진을 포함한 형태로 설정해주세요.

    리다이렉트되면 URL의 쿼리 파라미터로 amount, orderId, paymentKey가 추가돼요.

  • failUrl string
    

    결제 요청이 실패하면 리다이렉트되는 URL입니다. https://www.example.com/fail와 같이 오리진을 포함한 형태로 설정해주세요.

    리다이렉트되면 URL의 쿼리 파라미터로 에러 코드와 메시지를 확인할 수 있어요.

결제 요청이 성공하면 파라미터로 설정한 successUrl로 이동해요. 쿼리 파라미터의 amount 값이 메서드 파라미터로 설정한 amount와 같은지 반드시 확인하고 결제 승인 API를 호출해서 결제를 완료하세요.

결제 요청이 실패하면 파라미터로 설정한 failUrl로 이동해요. 쿼리 파라미터로 에러 코드와 메시지를 확인하세요.

Redirect 방식에서는 URL이 이동하기 때문에 void가 응답됩니다.

결제 UI를 렌더링합니다. 주문서의 DOM이 생성된 이후에 호출하세요. 토스페이먼츠와 전자결제 계약을 완료했다면 결제 어드민에서 결제수단, 디자인 등 결제 UI를 커스터마이징할 수 있어요.

• params 필수 · object
  

  결제 UI 렌더링 정보입니다.

  • selector 필수 · string
    

    결제 UI를 렌더링할 위치를 지정합니다. <div>와 같은 HTML 요소를 선택할 수 있는 CSS 선택자를 사용합니다. 예를 들어 <div id="payment-method">에 결제 UI를 렌더링하려면, #payment-method를 전달해야 합니다.

  • variantKey string
    

    렌더링하고 싶은 결제 UI의 variantKey입니다. 2개 이상의 결제 UI를 사용하고 있다면 설정해주세요. variantKey는 상점관리자의 결제 어드민에서 확인할 수 있어요. 기본 값은 DEFAULT입니다.

반환되는 결제 UI 객체로 아래 메서드를 호출할 수 있어요.

• on function
  

  결제 UI의 이벤트를 구독합니다. 자세히 >

• getSelectedPaymentMethod function
  

  구매자가 선택한 결제수단을 불러옵니다. 자세히 >

• getSelectedPaymentInfo function
  

  구매자가 고른 결제수단으로 어떻게 결제되는지를 불러옵니다. 자세히 >

• destroy function
  

  결제 UI 객체를 제거합니다. 자세히 >

구매자가 결제 UI에서 현재 선택한 결제수단을 불러옵니다.

method로 결제가 처리되는 경로를, 수단별 객체(card, transfer, brandpay, custom 등)로 카드사, 간편결제사, 계좌이체 제공자를 알 수 있어요. 최초 렌더 직후의 기본 선택과 이전 결제수단 복원은 paymentMethodSelect 이벤트가 발행되지 않으므로, 렌더 직후 이 메서드로 초기 선택을 읽으세요.

• code string
  DEPRECATED
  
  

  이전 버전과의 호환을 위해 남아 있는 화면 항목 코드입니다. 새 연동에서는 method와 수단별 객체를 쓰세요 — 카드사는 card.cardCompany, 앱카드는 card.useAppCardOnly와 card.appCard, 간편결제사는 card.easyPay, 계좌이체 제공자는 transfer.provider.

  code는 결제 어드민의 노출 방식에 따라 달라질 수 있어요. 예를 들어 카드 아래에서 신한카드를 고르면 CARD, 결제수단 목록에서 바로 신한카드를 고르면 SHINHAN이 응답돼요.

• method enum
  

  결제가 처리되는 경로입니다. 일반결제는 결제수단 이름(CARD, TRANSFER 등)이고, 브랜드페이는 BRANDPAY, 키인은 KEYIN, 커스텀 결제수단은 CUSTOM이에요. 간편결제와 앱카드는 카드로 결제되므로 CARD예요.

• card object
  

  카드로 결제할 때의 정보입니다. method가 CARD일 때 응답돼요. 간편결제와 앱카드도 여기에 담겨요.

  • cardCompany enum
    

    카드사 코드입니다. 카드사를 아직 고르지 않았으면 응답되지 않아요. 주문서형에서는 카드사를 고르면 paymentMethodSelect 이벤트가 다시 발행됩니다. 기관 코드를 참고하세요.

  • easyPay enum
    

    간편결제사 코드입니다(예: TOSSPAY). 간편결제가 아니면 응답되지 않아요.

  • useAppCardOnly boolean
    

    true면 구매자가 앱카드 버튼을 골라 카드사 앱으로 결제돼요. 결제 요청 시 SDK가 알아서 진행하므로 이 값을 requestPayment()에 넘길 필요는 없어요. 앱카드 전용 할인을 선택한 것과는 다른 값이에요.

  • appCard "KBPAY"
    

    앱카드 코드입니다(예: KBPAY). 표시 이름이 아니라 식별 코드라 앱 이름이 바뀌어도 유지돼요. 앱카드가 아니면 응답되지 않아요.

• foreignEasyPay object
  

  해외 간편결제 정보입니다. method가 FOREIGN_EASY_PAY일 때 응답돼요.

  • provider enum
    

    해외 간편결제사 코드입니다(예: PAYPAL).

• transfer object
  

  계좌이체 정보입니다. method가 TRANSFER일 때 응답돼요.

  • provider enum
    

    오픈뱅킹 이체는 TOSS_PAYMENTS, 뱅크페이 이체는 BANKPAY로 응답돼요. 제공자가 구분되지 않는 일반 계좌이체는 응답되지 않아요.

• methodId string
  DEPRECATED
  
  

  현재 브랜드페이에서 선택되어 있는 결제수단의 ID입니다. brandpay.methodId와 같은 값이에요.

• brandpay object
  

  브랜드페이로 결제할 때의 정보입니다. method가 BRANDPAY일 때 응답돼요.

  • methodId string
    

    현재 브랜드페이에서 선택되어 있는 결제수단의 ID입니다. 등록된 결제수단이 없거나 아직 목록을 불러오기 전이면 응답되지 않아요.

    주문서형에서는 목록이 준비되면 paymentMethodSelect 이벤트가 한 번 발행되니 그때 다시 읽으세요.

  • method enum
    

    현재 브랜드페이에서 선택되어 있는 결제수단의 종류입니다. 카드면 CARD, 계좌면 ACCOUNT예요.

    methodId와 같은 조건으로 응답되지 않을 수 있어요.

• custom object
  

  커스텀 결제수단 정보입니다. method가 CUSTOM일 때 응답돼요.

  • key string
    

    결제 어드민에 등록한 커스텀 결제수단의 key 값입니다. code와 같은 값이에요.

구매자가 고른 결제수단으로 어떻게 결제되는지를 불러옵니다. getSelectedPaymentMethod()가 무엇을 골랐는지라면, 이 메서드는 그 수단으로 얼마를 어떤 조건(할부, 카드포인트, 즉시할인, 입금기한)으로 결제하는지예요.

값은 부르는 시점에 계산돼요. 저장해 두고 재사용하지 말고, 결제 금액이나 할부 같은 결제 조건을 화면에 보여줄 때, setAmount()를 호출한 뒤, requestPayment()를 호출하기 직전에 다시 부르세요. paymentMethodSelect 이벤트가 오면 다시 읽으세요. 결제 금액을 바꾼 뒤 조회하면 새 금액에서 고를 수 없게 된 할부 개월은 기본값으로 돌아가요.

결제 요청에 넘기는 값이 아니라서 requestPayment()에 전달하지 않아요.

• code string
  DEPRECATED
  
  

  이전 버전과의 호환을 위해 남아 있는 화면 항목 코드입니다. 새 연동에서는 method와 수단별 객체를 쓰세요 — 카드사는 card.cardCompany, 앱카드는 card.useAppCardOnly와 card.appCard, 간편결제사는 card.easyPay, 계좌이체 제공자는 transfer.provider.

  code는 결제 어드민의 노출 방식에 따라 달라질 수 있어요. 예를 들어 카드 아래에서 신한카드를 고르면 CARD, 결제수단 목록에서 바로 신한카드를 고르면 SHINHAN이 응답돼요.

• method enum
  

  결제가 처리되는 경로입니다. 일반결제는 결제수단 이름(CARD, TRANSFER 등)이고, 브랜드페이는 BRANDPAY, 키인은 KEYIN, 커스텀 결제수단은 CUSTOM이에요. 간편결제와 앱카드는 카드로 결제되므로 CARD예요.

• card object
  

  카드로 결제할 때의 정보입니다. method가 CARD일 때 응답돼요. 간편결제와 앱카드도 여기에 담겨요.

  • cardCompany enum
    

    카드사 코드입니다. 카드사를 아직 고르지 않았으면 응답되지 않아요. 주문서형에서는 카드사를 고르면 paymentMethodSelect 이벤트가 다시 발행됩니다. 기관 코드를 참고하세요.

  • easyPay enum
    

    간편결제사 코드입니다(예: TOSSPAY). 간편결제가 아니면 응답되지 않아요.

  • useAppCardOnly boolean
    

    true면 구매자가 앱카드 버튼을 골라 카드사 앱으로 결제돼요. 결제 요청 시 SDK가 알아서 진행하므로 이 값을 requestPayment()에 넘길 필요는 없어요. 앱카드 전용 할인을 선택한 것과는 다른 값이에요.

  • appCard "KBPAY"
    

    앱카드 코드입니다(예: KBPAY). 표시 이름이 아니라 식별 코드라 앱 이름이 바뀌어도 유지돼요. 앱카드가 아니면 응답되지 않아요.

  • cardInstallmentPlan number
    

    구매자가 선택한 할부 개월 수입니다. 0은 일시불이에요.

  • useCardPoint boolean
    

    구매자의 카드사 포인트 사용 선택 여부입니다.

  • discountCode string
    

    결제수단에 적용된 즉시 할인(프로모션) 코드입니다. 조회하거나 결제하기를 누른 시점의 결제 금액으로 계산돼요.

• amount object
  

  결제 UI에 설정된 결제 금액입니다.

  • value number
    

    결제 금액입니다.

  • currency string
    

    결제 통화입니다. 일반결제는 KRW만 지원합니다. 해외 간편결제(PayPal)는 USD만 지원합니다.

• foreignEasyPay object
  

  해외 간편결제 정보입니다. method가 FOREIGN_EASY_PAY일 때 응답돼요.

  • provider enum
    

    해외 간편결제사 코드입니다(예: PAYPAL).

• transfer object
  

  계좌이체 정보입니다. method가 TRANSFER일 때 응답돼요.

  • provider enum
    

    오픈뱅킹 이체는 TOSS_PAYMENTS, 뱅크페이 이체는 BANKPAY로 응답돼요. 제공자가 구분되지 않는 일반 계좌이체는 응답되지 않아요.

• virtualAccount object
  

  가상계좌 정보입니다. method가 VIRTUAL_ACCOUNT일 때 응답돼요.

  • dueDate string
    

    결제 어드민의 가상계좌 설정에 따라 계산된 입금기한입니다. 조회하거나 결제하기를 누른 시점 기준이라 결제 요청 시점에 다시 계산될 수 있어요.

    Payment.virtualAccount.dueDate와 같은 오프셋 포함 형식이에요(예: 2026-09-16T23:59:59+09:00). requestPayment()의 dueDate는 오프셋 없이 한국 시각으로 적는 요청 형식이라 서로 달라요.

• methodId string
  DEPRECATED
  
  

  현재 브랜드페이에서 선택되어 있는 결제수단의 ID입니다. brandpay.methodId와 같은 값이에요.

• brandpay object
  

  브랜드페이로 결제할 때의 정보입니다. method가 BRANDPAY일 때 응답돼요.

  • methodId string
    

    현재 브랜드페이에서 선택되어 있는 결제수단의 ID입니다. 등록된 결제수단이 없거나 아직 목록을 불러오기 전이면 응답되지 않아요.

    주문서형에서는 목록이 준비되면 paymentMethodSelect 이벤트가 한 번 발행되니 그때 다시 읽으세요.

  • method enum
    

    현재 브랜드페이에서 선택되어 있는 결제수단의 종류입니다. 카드면 CARD, 계좌면 ACCOUNT예요.

    methodId와 같은 조건으로 응답되지 않을 수 있어요.

  • cardInstallmentPlan number
    

    구매자가 선택한 할부 개월 수입니다. 0은 일시불이에요.

  • useCardPoint boolean
    

    구매자의 카드사 포인트 사용 선택 여부입니다.

  • discountCode string
    

    결제수단에 적용된 즉시 할인(프로모션) 코드입니다. 조회하거나 결제하기를 누른 시점의 결제 금액으로 계산돼요.

  • cashReceipt object
    

    구매자가 브랜드페이에서 선택한 현금영수증 발급 정보입니다.

    • type enum
      

      현금영수증 발급 용도입니다. 소득공제, 지출증빙, 미발행 중 하나예요.

    • registrationNumberType enum
      

      현금영수증 발급 번호의 종류입니다. 휴대폰 번호는 MOBILE, 현금영수증 카드는 CASH_RECEIPT_CARD, 사업자등록번호는 BUSINESS_REGISTRATION이에요. 미발행이면 응답되지 않아요.

    • registrationNumber string
      

      현금영수증 발급 번호입니다. 미발행이면 응답되지 않아요.

• custom object
  

  커스텀 결제수단 정보입니다. method가 CUSTOM일 때 응답돼요.

  • key string
    

    결제 어드민에 등록한 커스텀 결제수단의 key 값입니다. code와 같은 값이에요.

결제 UI 이벤트를 구독합니다. 현재 지원하는 이벤트는 paymentMethodSelect입니다.

• eventName 필수 · "paymentMethodSelect"
  

  구독할 이벤트입니다. paymentMethodSelect 이벤트로 구매자가 선택한 결제수단을 확인하세요.

• callback 필수 · function
  

  이벤트가 일어나면 호출되는 콜백 함수입니다. 콜백 파라미터로 구매자가 선택한 결제수단(selectedPaymentMethod)이 전달돼요. getSelectedPaymentMethod()의 응답과 같은 값이에요. method로 결제가 처리되는 경로를, 수단별 객체(card, transfer, brandpay, custom 등)로 카드사, 간편결제사, 계좌이체 제공자를 알 수 있어요. 결제 Pro 플랜으로 커스텀 결제수단을 연동했다면 method가 CUSTOM이고 custom.key에 결제 어드민에서 설정한 key 값이 응답돼요. code는 이전 버전과의 호환을 위해 남아 있는 화면 항목 코드예요.

  • selectedPaymentMethod 필수 · object
    

    구매자가 결제 UI에서 선택한 결제수단입니다. method로 결제가 처리되는 경로를 알 수 있고, 카드사, 간편결제사, 계좌이체 제공자 같은 상세 정보는 수단별 객체(card, transfer, brandpay, custom 등)에 담겨요.

    • code 필수 · string
      DEPRECATED
      
      

      이전 버전과의 호환을 위해 남아 있는 화면 항목 코드입니다. 새 연동에서는 method와 수단별 객체를 쓰세요 — 카드사는 card.cardCompany, 앱카드는 card.useAppCardOnly와 card.appCard, 간편결제사는 card.easyPay, 계좌이체 제공자는 transfer.provider.

      code는 결제 어드민의 노출 방식에 따라 달라질 수 있어요. 예를 들어 카드 아래에서 신한카드를 고르면 CARD, 결제수단 목록에서 바로 신한카드를 고르면 SHINHAN이 응답돼요.

    • method 필수 · enum
      

      결제가 처리되는 경로입니다. 일반결제는 결제수단 이름(CARD, TRANSFER 등)이고, 브랜드페이는 BRANDPAY, 키인은 KEYIN, 커스텀 결제수단은 CUSTOM이에요. 간편결제와 앱카드는 카드로 결제되므로 CARD예요.

    • card object
      

      카드로 결제할 때의 정보입니다. method가 CARD일 때 응답돼요. 간편결제와 앱카드도 여기에 담겨요.

      • cardCompany enum
        

        카드사 코드입니다. 카드사를 아직 고르지 않았으면 응답되지 않아요. 주문서형에서는 카드사를 고르면 paymentMethodSelect 이벤트가 다시 발행됩니다. 기관 코드를 참고하세요.

      • easyPay enum
        

        간편결제사 코드입니다(예: TOSSPAY). 간편결제가 아니면 응답되지 않아요.

      • useAppCardOnly boolean
        

        true면 구매자가 앱카드 버튼을 골라 카드사 앱으로 결제돼요. 결제 요청 시 SDK가 알아서 진행하므로 이 값을 requestPayment()에 넘길 필요는 없어요. 앱카드 전용 할인을 선택한 것과는 다른 값이에요.

      • appCard "KBPAY"
        

        앱카드 코드입니다(예: KBPAY). 표시 이름이 아니라 식별 코드라 앱 이름이 바뀌어도 유지돼요. 앱카드가 아니면 응답되지 않아요.

    • foreignEasyPay object
      

      해외 간편결제 정보입니다. method가 FOREIGN_EASY_PAY일 때 응답돼요.

      • provider 필수 · enum
        

        해외 간편결제사 코드입니다(예: PAYPAL).

    • transfer object
      

      계좌이체 정보입니다. method가 TRANSFER일 때 응답돼요.

      • provider enum
        

        오픈뱅킹 이체는 TOSS_PAYMENTS, 뱅크페이 이체는 BANKPAY로 응답돼요. 제공자가 구분되지 않는 일반 계좌이체는 응답되지 않아요.

    • methodId string
      DEPRECATED
      
      

      현재 브랜드페이에서 선택되어 있는 결제수단의 ID입니다. brandpay.methodId와 같은 값이에요.

    • brandpay object
      

      브랜드페이로 결제할 때의 정보입니다. method가 BRANDPAY일 때 응답돼요.

      • methodId string
        

        현재 브랜드페이에서 선택되어 있는 결제수단의 ID입니다. 등록된 결제수단이 없거나 아직 목록을 불러오기 전이면 응답되지 않아요.

        주문서형에서는 목록이 준비되면 paymentMethodSelect 이벤트가 한 번 발행되니 그때 다시 읽으세요.

      • method enum
        

        현재 브랜드페이에서 선택되어 있는 결제수단의 종류입니다. 카드면 CARD, 계좌면 ACCOUNT예요.

        methodId와 같은 조건으로 응답되지 않을 수 있어요.

    • custom object
      

      커스텀 결제수단 정보입니다. method가 CUSTOM일 때 응답돼요.

      • key 필수 · string
        

        결제 어드민에 등록한 커스텀 결제수단의 key 값입니다. code와 같은 값이에요.

renderPaymentMethods()로 생성한 결제 UI 객체를 제거합니다. 한 페이지에서 두 개의 결제 UI를 렌더링할 수 없어요. 새로운 결제 UI를 렌더링하고 싶다면 destroy() 메서드로 기존 결제 UI를 제거한 다음에 렌더링하세요.

약관 UI를 렌더합니다. 약관에는 기본 토스페이먼츠 이용약관이 있는데요. 내 상점만의 약관을 추가하거나 다른 언어로 약관을 추가하고 싶다면 결제 어드민에서 수정해주세요.

• params 필수 · object
  

  약관 UI 렌더링 정보입니다.

  • selector 필수 · string
    

    약관 UI를 렌더링할 위치를 지정합니다. <div>와 같은 HTML 요소를 선택할 수 있는 CSS 선택자를 사용합니다. 예를 들어 <div id="agreement">에 결제 UI를 렌더링하려면, #agreement를 전달해야 합니다.

  • variantKey string
    

    렌더링하고 싶은 약관 UI의 variantKey입니다. 상점관리자의 결제 어드민에서 확인할 수 있어요.

반환되는 약관 UI 객체로 아래 메서드를 호출할 수 있어요.

• on function
  

  약관 UI의 이벤트를 구독합니다. 자세히 >

• destroy function
  

  약관 UI 객체를 제거합니다. 자세히 >

약관 UI 이벤트를 구독합니다. 현재 지원하는 이벤트는 agreementStatusChange입니다.

• eventName 필수 · "agreementStatusChange"
  

  구독할 이벤트입니다. agreementStatusChange 이벤트로 구매자가 약관에 동의했는지 확인하세요.

• callback 필수 · function
  

  이벤트가 일어나면 호출되는 콜백 함수입니다. 콜백 파라미터로 구매자의 약관 동의 상태(agreementStatus)가 전달돼요.

  • agreementStatus 필수 · object
    

    구매자의 약관 동의 상태입니다.

    • agreedRequiredTerms 필수 · boolean
      

      구매자가 모든 필수 약관에 동의했는지 알려줍니다.

    • agreements 필수 · array
      

      개별 약관에 동의했는지 알려줍니다.

      • term 필수 · object
        

        약관 정보입니다.

        • id 필수 · string
          

          약관의 식별자입니다.

        • required 필수 · boolean
          

          약관의 필수 여부입니다.

      • agreed 필수 · boolean
        

        구매자의 약관 동의 여부입니다.

renderAgreement() 메서드로 생성한 약관 UI 객체를 제거합니다. 한 페이지에서 두 개의 약관 UI를 렌더링할 수 없어요. 새로운 약관 UI를 렌더링하고 싶다면 destroy() 메서드로 기존 약관 UI를 제거한 다음에 렌더링하세요.