Version 2

주문서형 결제 JavaScript SDK

주문서에 결제 UI를 직접 렌더링하는 주문서형 결제 메서드를 알아봅니다.

결제위젯의 이름이 주문서형, 결제창형 결제로 변경됩니다.

결제 연동

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

tossPayments.widgets()

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

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

파라미터

params 필수 · object
결제 초기화 정보입니다.
- customerKey 필수 · string
  구매자를 식별하는 고유 아이디입니다.
  이메일・전화번호나 자동 증가하는 숫자와 같이 유추가 가능한 값은 안전하지 않아요. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 중 최소 1개를 포함하는 최소 2자 이상 최대 50자 이하의 문자열이어야 합니다.
- brandpay object
  주문서형, 결제창형으로 브랜드페이를 연동할 때 필요한 정보입니다.
  - redirectUrl string
    브랜드페이 결제 과정에서 Access Token 발급을 위해 필요한 URL입니다. Access Token은 브랜드페이 고객을 식별하고 고객의 결제 권한을 증명합니다. 값을 넣지 않으면 개발자센터의 브랜드페이 메뉴에 최초로 등록한 리다이렉트 URL이 기본값으로 들어갑니다.
    * 브랜드페이 메뉴에 두 개 이상의 리다이렉트 URL을 등록한 상점은 각 도메인에 맞는 redirectUrl 값을 필수로 추가하세요.

응답

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

setAmount function
주문의 결제 금액을 설정합니다. 자세히 >
renderPaymentMethods function
결제 UI를 렌더링합니다. 자세히 >
requestPayment function
결제를 요청합니다. 구매자가 결제 UI에서 선택한 결제수단의 결제창을 띄워요. 자세히 >
renderAgreement function
약관 UI를 렌더링합니다. 자세히 >

widgets.setAmount()

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

파라미터

amount 필수 · object
결제 금액 정보입니다.
- value 필수 · number
  결제 금액입니다.
- currency 필수 · string
  결제 통화입니다. 일반결제는 KRW만 지원합니다. 해외 간편결제(PayPal)는 USD만 지원합니다.

응답

widgets.requestPayment()

결제를 요청합니다. 구매자가 결제 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
    페이북/ISP 앱에서 상점 앱으로 돌아올 때 사용됩니다. 상점의 앱 스킴을 지정하면 됩니다. 예를 들면 testapp://같은 형태입니다.
- 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가 응답됩니다.