결제창(구버전) JavaScript SDK

결제창(구버전)으로 결제를 요청하는 메서드를 알아봅니다.

결제창(구버전)을 초기화합니다. 토스페이먼츠에서 제공하는 신용/체크카드 통합결제창을 연동하거나 사용하고 싶은 결제수단의 결제창을 각각 연동할 수 있어요.

• params 필수 · object
  

  결제창 초기화 정보입니다.

  • customerKey 필수 · string
    

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

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

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

• requestPayment function
  

  결제창을 띄웁니다. 자세히 >

• requestBillingAuth function
  

  자동결제(빌링) 카드 등록창을 띄웁니다. 자세히 >

• destroy function
  

  떠 있는 결제창 iframe을 닫고 진행 중인 결제 요청을 중단합니다. 자세히 >

결제창을 띄웁니다.

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

• paymentRequest 필수 · object
  

  결제 요청 정보입니다.

  • method 필수 · "CARD"
    

    결제수단입니다. CARD로 설정하면 카드/간편결제 통합결제창, 카드・간편결제 자체창을 사용할 수 있어요.

  • card object
    

    카드 결제 정보입니다.

    • useEscrow boolean
      

      에스크로 적용 여부입니다. true로 설정하면 구매자가 반드시 에스크로 적용에 동의해야 결제가 완료돼요. false로 설정하거나 파라미터를 설정하지 않으면 에스크로 적용을 구매자 선택에 맡겨요.

    • taxExemptionAmount number
      

      과세를 제외한 결제 금액(컵 보증금 등)입니다.

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

    • flowMode enum
      

      결제창을 여는 방법입니다. DEFAULT는 카드/간편결제 통합결제창을 열고, DIRECT는 카드 또는 간편결제의 자체창을 열어요.

      기본 값은 DEFAULT입니다.

    • cardCompany string
      

      카드사 코드입니다. flowMode 값에 따라 아래와 같이 다르게 동작해요.

      flowMode가 DIRECT일 때는 입력한 코드의 카드사 앱이 열려요. flowMode가 DEFAULT일 때는 통합결제창에 입력한 코드의 카드사만 표시돼요. 파이프(|)로 구분해서 여러 카드사를 지정할 수 있어요. 예를 들어, BC|삼성을 입력하면 BC카드와 삼성카드가 결제창에 표시돼요.

    • easyPay string
      

      간편결제 코드입니다. flowMode 값에 따라 아래와 같이 다르게 동작해요.

      flowMode가 DIRECT일 때는 입력한 코드의 간편결제 앱이 열려요. flowMode가 DEFAULT일 때는 해당 파라미터와 상관 없이 기본 통합결제창이 열려요.

    • cardInstallmentPlan number
      

      신용카드 결제에 적용되는 할부 개월 수입니다.

      예를 들어, 6으로 설정하면 할부 개월 수가 6개월로 고정돼요. 자체창에서는 구매자가 할부 개월 수를 볼 수 없으니 사전에 충분히 안내를 해주세요. 0(일시불), 2~12 값으로 설정할 수 있고 maxCardInstallmentPlan 파라미터와 함께 사용할 수 없어요. 카드사 별로 할부결제가 가능한 최소 금액을 확인하세요.

    • maxCardInstallmentPlan number
      

      신용카드 결제에 적용할 수 있는 최대 할부 개월 수입니다.

      예를 들어, 6으로 설정하면 구매자는 일시불부터 6개월 할부를 선택할 수 있어요. 0(일시불), 2~12 값으로 설정할 수 있고 cardInstallmentPlan 파라미터와 함께 사용할 수 없어요. 카드사 별로 할부결제가 가능한 최소 금액을 확인하세요.

    • freeInstallmentPlans array
      

      신용카드 결제에 적용할 수 있는 상점 부담 무이자 할부 정보입니다.

      구매자가 선택한 카드, 할부 개월 수가 배열에 등록한 정보와 같다면 무이자 할부가 자동으로 적용돼요. 카드사 별로 할부결제가 가능한 최소 금액을 확인하세요.

      • company 필수 · string
        

        상점 부담 무이자를 적용할 카드사 코드입니다.

      • months 필수 · array
        

        상점 부담 무이자를 적용할 할부 개월입니다.

    • useCardPoint boolean
      

      카드사 포인트 사용 여부입니다. true로 설정하면 카드사 포인트 사용이 체크된 상태로 결제창이 열려요. false로 설정하거나 값을 넣지 않으면 구매자가 직접 카드사 포인트 사용 여부를 선택할 수 있어요.

      * 추가 계약이 필요한 파라미터입니다. 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

    • useAppCardOnly boolean
      

      앱카드 단독 사용 여부입니다. true로 설정하면 카드사의 앱카드만 열려요. 국민, 농협, 롯데, 삼성, 신한, 우리, 현대 카드 결제에 적용할 수 있어요.

    • discountCode string
      

      카드사의 프로모션 코드입니다. 프로모션은 flowMode가 DIRECT로 설정된 자체창 결제에만 사용할 수 있어요. 프로모션 조회 API로 적용할 수 있는 프로모션 코드를 확인하세요.

    • validHours number
      

      시간으로 설정하는 결제 기한입니다. 설정할 수 있는 최대 값은 2160시간(90일)입니다.

      기한이 지나고 시도하는 결제는 실패해요. 예를 들어 24로 설정하면, 결제 요청 시점으로부터 24시간 동안 결제할 수 있어요.

    • dueDate string
      

      특정 날짜로 설정하는 결제 기한입니다. yyyy-MM-dd'T'HH:mm:ss ISO 8601 형식입니다.

      기한이 지나고 시도하는 결제는 실패해요. 예를 들어 2025-01-01T00:00:00으로 설정하면, 2024년 12월 31일 23:59까지 결제할 수 있어요.

    • escrowProducts array
      
      • id string
        

        각 상품의 고유 ID입니다.

      • name string
        

        상품명입니다.

      • code string
        

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

      • unitPrice number
        

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

      • quantity number
        

        상품 구매 수량입니다.

    • useInternationalCardOnly boolean
      

      해외카드(Visa, MasterCard, JCB, UnionPay 등) 결제 여부입니다. true로 설정하면 해외카드 결제가 가능한 다국어 결제창이 열립니다.

    • language string
      

      결제창 초기 언어입니다. KO(한국어), EN(영어), JA(일본어), ZH(중국어) 중 하나로 설정할 수 있어요. 값을 설정하지 않으면 결제 통화에 따라 자동으로 결정됩니다.

    • showEstimatedAmount boolean
      

      다국어 결제창에서 예상 결제 금액(USD 환산값) 노출 여부입니다. 기본값은 true이고, false로 설정하면 예상 결제 금액이 숨겨집니다. useInternationalCardOnly가 true이고 결제 통화가 KRW일 때만 적용됩니다.

    • appScheme string
      

      페이북/ISP 앱에서 상점 앱으로 돌아올 때 사용됩니다. 상점의 앱 스킴을 지정하면 됩니다. 예를 들면 testapp://같은 형태입니다.

    • keyin object
      

      키인 결제정보입니다.

      • selectableCardTypes array
        

        결제화면에 노출할 카드 타입입니다. PERSONAL(개인카드), CORPORATE(법인카드), FOREIGN(해외카드) 값을 배열 형태로 전달할 수 있습니다. 입력한 순서대로 화면에 노출되며, 첫 번째로 입력한 카드 타입이 기본 선택됩니다.

  • amount 필수 · object
    

    결제 금액 정보입니다.

    • value 필수 · number
      

      결제 금액입니다.

    • currency 필수 · string
      

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

  • orderName 필수 · string
    

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

  • orderId 필수 · string
    

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

  • customerName string
    

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

  • customerEmail string
    

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

  • customerMobilePhone string
    

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

  • taxFreeAmount number
    

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

  • windowTarget enum
    

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

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

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

  • metadata object
    

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

  • 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가 응답됩니다.

자동결제(빌링) 등록창을 띄웁니다. 자동결제는 카드, 계좌를 지원해요.

• billingAuthRequest 필수 · object
  

  자동결제(빌링) 등록에 필요한 정보입니다.

  • method 필수 · enum
    

    자동결제(빌링)에 등록할 결제수단입니다. 토스페이먼츠 자동결제는 신용·체크카드, 계좌이체를 지원해요.

  • successUrl 필수 · string
    

    등록이 성공하면 리다이렉트되는 URL입니다. 리다이렉트되면 URL의 쿼리 파라미터로 authKey, customerKey가 추가돼요. 값을 검증하고 빌링키 발급 API를 호출하세요.

    반드시 오리진을 포함해야 합니다.

  • failUrl 필수 · string
    

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

    반드시 오리진을 포함해야 합니다.

  • customerName string
    

    구매자명입니다. 상점관리자 및 결제내역 이메일에 사용됩니다. 최대 길이는 100자입니다.

  • customerEmail string
    

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

  • windowTarget enum
    

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

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

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

  • selectableCardTypes array
    

    결제화면에 노출할 카드 타입입니다. PERSONAL(개인카드), CORPORATE(법인카드) 값을 배열 형태로 전달할 수 있습니다. 입력한 순서대로 화면에 노출되며, 첫 번째로 입력한 카드 타입이 기본 선택됩니다.

URL이 이동하기 때문에 void가 응답됩니다. 파라미터로 설정한 successUrl 또는 failUrl에서 카드 등록 결과를 확인하고 빌링키 발급 API를 호출해야 자동결제를 할 수 있어요.

payment.destroy()를 실행하면 화면에 떠 있는 결제창 iframe이 닫히고 진행 중인 결제 요청이 중단됩니다.

React 또는 Vue.js로 SPA(Single Page Application) 사이트를 구현했을 때 사용합니다. 데스크톱 브라우저에서 페이지를 전환해도 결제창 iframe이 남아 있다면 payment.destroy()를 실행하세요.

• 진행 중인 payment.requestPayment() 또는 payment.requestBillingAuth()가 있으면 해당 메서드 호출이 PAYMENT_REQUEST_ABORTED 에러로 종료됩니다.
• 진행 중인 결제 요청이 없으면 payment.destroy()가 NO_ACTIVE_PAYMENT_REQUEST 에러를 던집니다.