가이드/결제위젯/결제 연동하기

Version 2

새로 나온

결제 연동하기

결제위젯을 사용하면 모든 결제수단을 한 번에 연동할 수 있어요. 프로젝트 언어를 선택하고 빠르게 시작하세요. 연동이 끝나면 노코드로 결제수단 설정과 디자인을 변경할 수 있어요.

신용・체크 카드

계좌이체(퀵계좌이체)

간편결제

휴대폰

가상계좌

상품권

아래 문서용 테스트 키 또는 전자결제 신청 이후에 확인 가능한 결제위젯 연동 키를 사용하세요.

샌드박스로 시작하기

토스페이먼츠 결제위젯 흐름

SDK 설치

스크립트 태그 또는 npm 패키지로 결제위젯 SDK를 설치하세요.

결제위젯 인스턴스 생성

토스페이먼츠 SDK를 초기화한 다음에 결제위젯 인스턴스를 생성하세요.

클라이언트 키로 토스페이먼츠 SDK를 초기화하세요.

개발자센터에서 결제위젯 연동 키 > 클라이언트 키를 불러오세요. 결제위젯 연동 키는 토스페이먼츠 전자결제 신청 이후에만 확인할 수 있어요. 신청 전에는 아래 테스트 키로 연동해보세요.

클라이언트 키로 TossPayments() 초기화 메서드를 호출하면 토스페이먼츠 객체가 생성돼요.

결제위젯 인스턴스를 생성하세요.

초기화된 토스페이먼츠 객체로 widget()을 호출해서 결제위젯 객체를 생성해주세요. 메서드 파라미터로 각 회원 구매자에게 발급한 고유 customerKey 값을 넣어주세요. customerKey는 와 같이 충분히 무작위적인 고유 값을 사용하세요. 비회원 구매자는 ANONYMOUS 값을 사용하세요.

결제 금액 설정

결제위젯 인스턴스로 setAmount() 메서드로 주문의 결제 금액을 설정해주세요. 쿠폰, 할인 등으로 결제 금액을 업데이트할 일이 있다면 같은 메서드를 사용하세요.

결제 영역 정의

결제 UI, 이용약관 UI를 보여주고 싶은 영역을 각각 div 태그로 정의하세요. 결제 버튼도 만들어주세요.

결제 UI 렌더링

DOM이 생성된 이후에 renderPaymentMethods() 메서드로 결제 UI를 렌더링하세요. 결제 영역의 div CSS 선택자(Selector)와 결제 금액을 파라미터로 넣으세요. 여러 결제 UI를 만들었다면, variantKey를 결제위젯 어드민에서 확인하고 파라미터로 넘기세요.

어드민에서 결제 UI를 여러 개 만들었다면, 각 UI에 부여되는 키에요. 더 자세한 내용은 새로운 결제 UI 추가하기를 참고하세요.

구매자가 처음 주문서에 진입하면 항상 첫 번째 결제수단이 선택되어 있습니다. 재방문하는 구매자는 이전에 구매할 때 사용한 결제수단이 선택되어 있습니다.

renderPaymentMethods()는 비동기 메서드입니다.

  • UNAUTHORIZED_KEY 에러가 나면 클라이언트 키를 다시 확인하세요.
  • NOT_REGISTERED_PAYMENT_WIDGET 에러가 나면 상점관리자에서 결제 UI를 추가하세요. 결제 UI가 생성되지 않았을 때 발생하는 에러입니다.
  • CSS 선택자(Selector)를 정확히 입력했는지 확인하세요.
  • 특정 브라우저 환경에서만 렌더링이 안 된다면 익스텐션을 확인하세요. IE 환경은 지원하지 않습니다.

애플페이는 iPhone 및 Mac Safari 에서만 노출돼요. 어드민 페이지에서는 예상 이미지를 확인할 수 있습니다.

가상계좌는 문서용 테스트 키로 테스트할 수 없습니다. 토스페이먼츠와 전자결제 계약 체결 이후 발급되는 내 상점만의 API 테스트 키로 테스트해보세요.

이용약관 UI 렌더링

renderAgreement() 메서드로 이용약관 UI를 렌더링하세요. 이용약관 영역의 div CSS 선택자(Selector)를 파라미터로 넣으세요.

(선택) 기타 결제 UI 추가

할인 쿠폰, 가격 정보 등 구매자에게 보여주고 싶은 기타 결제 UI를 직접 만들어서 추가해주세요.

결제 버튼 이벤트 설정

결제를 요청하기 전에 orderId와 amount를 서버에 임시로 저장하세요. 결제 요청과 승인 사이에 데이터 무결성을 확인할 때 필요해요. 더 자세한 내용은 결제 흐름 가이드에서 확인하세요.

결제 버튼에 결제 요청 메서드 requestPayment()를 이벤트로 걸어주세요. 더 많은 파라미터는 SDK 문서에서 확인하세요.

결제 UI가 렌더링된 이후에 결제 요청 메서드를 호출하세요.

결제 요청 및 인증이 끝난 뒤에 리다이렉트 되는 URL입니다. 결제 요청이 성공하면 successUrl로, 실패하면 failUrl로 이동해요.

구매자가 선택한 결제수단의 결제창이 정상적으로 열리지 않습니다. 반드시 결제 UI가 렌더링된 이후에 결제 요청 메서드를 호출하세요.

네. 결제를 요청하기 전에 getSelectedPaymentMethod()를 호출해서 구매자가 선택한 결제수단을 확인할 수 있습니다.

결제 성공 후 이동하는 successUrl로 받으세요. 적은 양의 데이터라면 successUrl의 로 추가하세요.

만약 데이터가 많거나 결제 완료 전에 데이터를 처리해야 한다면, 결제 요청을 하기 전에 데이터베이스에 저장하세요.

결제창 띄우기

결제 UI에서 자주 사용하는 결제수단을 선택하고 '결제하기' 버튼을 누르세요. 선택한 결제수단의 결제창에서 정보를 입력하세요. 테스트 환경에서는 결제가 가상으로만 이뤄지기 때문에 결제수단에서 금액이 차감되지 않아요. 결제를 마치면 결제 인증이 완료된 거예요.

클라이언트는 결제 인증이 성공하면 successUrl로 이동하고, 실패하면 failUrl로 이동해요.

아직 결제 요청 중이에요. 이어서 successUrl, failUrl 페이지에서 요청 결과를 확인한 뒤, 결제 승인 API까지 호출해야 결제가 완료돼요. iframe을 사용하고 있다면 요청 결과 페이지(successUrl, failUrl)로 이동할 수가 없어요.

카드사 앱스킴을 등록해야 돼요. 자세한 내용은 웹뷰 가이드에서 확인하세요.

iframe을 이용한 결제창 팝업 형태는 PC에서만 제공하고 있습니다.

결제 인증과 승인 사이에는 클라이언트가 이동하는 리다이렉트 과정이 있습니다.

결제 요청 과정에서 인증 결과를 받고 다음 단계로 넘어가기 위해 리다이렉트 URL 확인과 처리가 필요합니다. 토스페이먼츠에서 인증 결과를 URL의 에 담아 리다이렉트하면, 상점에서는 리다이렉트 URL을 받아 결제를 승인할 수 있어요.

더 자세한 내용은 리다이렉트 처리하기, 결제 흐름 이해하기에서 확인해보세요.

successUrl로 이동한 경우

결제 요청이 성공하면 successUrl로 이동합니다. URL에 아래 네 가지 쿼리 파라미터가 추가돼요.

쿼리 파라미터의 amount 값과 setAmount()의 amount 파라미터의 값이 같은지 반드시 확인하세요. 클라이언트에서 결제 금액을 조작하는 행위를 방지할 수 있습니다. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요.

일반결제 및 해외 간편결제의 paymentType은 NORMAL입니다. 브랜드페이 결제의 paymentType은 BRANDPAY입니다.

서버로 결제정보 전달

서버로 paymentKey, amount, orderId 값을 전달하세요. 결제 승인에 필요한 데이터입니다. 결제 승인 결과에 따라 클라이언트에서 필요한 결제 성공 및 실패 로직을 추가하세요.

failUrl로 이동한 경우

결제 요청이 실패하면 failUrl로 이동합니다. 쿼리 파라미터로 돌아오는 에러 코드, 메시지를 확인하고 필요한 로직을 구현해주세요.

오류원인

구매자에 의해 결제가 취소되면 PAY_PROCESS_CANCELED 에러가 발생합니다. 결제 과정이 중단된 것이라서 failUrl로 orderId가 전달되지 않아요.

오류원인

결제가 실패하면 PAY_PROCESS_ABORTED 에러가 발생합니다.

해결 방법

오류원인

구매자가 입력한 카드 정보에 문제가 있다면 REJECT_CARD_COMPANY 에러가 발생합니다.

해결 방법

  • 오류 메시지를 확인하고 구매자에게 안내를 해주세요.
시크릿 키로 Basic 인증 헤더 설정

개발자센터에서 결제위젯 연동 키 > 시크릿 키를 불러오세요. 결제위젯 연동 키는 토스페이먼츠 전자결제 신청 이후에만 확인할 수 있어요. 신청 전에는 아래 테스트 키로 연동해보세요.

시크릿 키와 :을 로 인코딩해서 Basic 인증 헤더를 아래와 같이 만들어주세요. :을 빠트리지 않도록 주의하세요. 비밀번호가 없다는 것을 알리기 위해 시크릿 키 뒤에 콜론을 추가합니다.

* 시크릿 키는 클라이언트, GitHub 등 외부에 노출되면 안 됩니다.

결제 승인 API 호출

결제를 승인하면 결제수단에서 금액이 차감돼요. 토스페이먼츠 결제 승인 API를 호출해서 결제를 완료하세요.

Authorization 헤더에 인코딩된 시크릿 키값을 추가하세요. orderId, amount, paymentKey를 요청 데이터로 사용하세요.

성공 응답

결제 승인에 성공하면 HTTP 200 OK와 Payment 객체를 받습니다.

데이터 저장

paymentKey, orderId는 서버에 필수로 저장하세요. 결제 조회, 결제 취소에 사용되는 값입니다. 나머지 값들은 필요에 따라 저장하세요.

결제수단

응답 객체에 선택한 결제수단 정보를 확인하세요. 결제 UI에서 신용・체크를 선택했다면, card 필드에 카드 정보 객체가 돌아와요. method 필드도 카드로 나와요.

API 버전

응답 객체는 API 버전에 따라 조금씩 달라집니다. 개발자센터에 설정된 API 버전을 확인하고, 원하는 필드가 있는 버전으로 변경해보세요. API 버전 업데이트 사항은 릴리즈 노트에서 확인할 수 있습니다.

실패 응답

결제 승인에 실패하면 HTTP 4XX 또는 5XX 코드와 에러 객체를 받습니다. 결제 승인의 전체 오류 목록은 에러 코드를 참고하세요.

오류원인

결제 승인에서 요청에 문제가 있으면 NOT_FOUND_PAYMENT_SESSION 에러가 발생합니다.

해결 방법

  • 결제 요청이 완료된 이후 10분 이내에 결제를 승인해야 됩니다. 10분이 지나면 결제 데이터가 유실되어 승인이 불가합니다.

  • 결제 요청했을 때 돌려받은 paymentKey와 결제 승인에 사용한 paymentKey가 같은 값인지 확인하세요.

  • 결제 요청에 사용한 클라이언트 키와 결제 승인에 사용한 시크릿 키가 매칭된 키값인지 확인하세요.

오류원인

카드사에서 해당 카드를 거절했을 때 REJECT_CARD_COMPANY 에러가 발생합니다. 원인은 비밀번호 오류, 한도 초과, 포인트 부족 등 다양합니다.

해결 방법

에러 메시지를 확인해서 원인을 파악하고 구매자에게 올바른 안내를 해주세요.

오류원인

API 키값 또는 주문번호가 최초 요청한 값과 다르면 FORBIDDEN_REQUEST가 발생합니다.

해결 방법

  • 결제 요청에 사용한 클라이언트 키와 API 호출에 사용한 시크릿 키가 매칭된 키값인지 확인하세요.

  • orderId, paymentKey 값이 최초 결제 요청한 값과 같은지 확인하세요.

오류원인

API 키를 잘못 입력하면 UNAUTHORIZED_KEY 에러가 발생합니다.

해결 방법

  • 클라이언트 키와 매칭된 시크릿 키를 사용하고 있는지 확인하세요. API 키는 토스페이먼츠에 로그인한 뒤에 개발자센터의 API 키 메뉴에서 확인할 수 있어요.

  • 시크릿 키 인코딩을 다시 확인하세요. 시크릿 키 뒤에 :을 추가하고 base64로 인코딩해서 사용해야 됩니다.

다음 단계

결제 연동을 완성하셨어요. 이제 개발자센터에서 테스트 결제내역을 확인하거나 토스페이먼츠 코어 API로 결제를 조회 또는 취소해보세요.

실시간으로 결제 알림을 받고 싶다면 웹훅을 연동하세요.

Client
Server