Version 1
결제 연동하기
결제위젯 SDK v1은 더 이상 업데이트되지 않습니다. 토스페이먼츠 SDK v2 연동을 추천합니다.
모든 결제수단을 한 번에 연동할 수 있는 샘플 프로젝트입니다. 프로젝트 언어를 선택하고 빠르게 시작하세요. 연동이 끝나면 노코드로 결제수단 설정과 디자인을 변경할 수 있어요.
아래 문서용 테스트 키 또는 전자결제 신청 이후에 확인 가능한 결제 연동 키를 사용하세요.
스크립트 태그 또는 npm 패키지로 결제위젯 SDK를 설치하세요.
클라이언트 키, customerKey로 결제위젯 SDK를 초기화하세요.
개발자센터에서 결제 연동 키 > 클라이언트 키를 불러오세요. 결제 연동 키는 토스페이먼츠 전자결제 신청 이후에만 확인할 수 있어요. 신청 전에는 아래 테스트 키로 연동해보세요.
회원 구매자의 customerKey를 불러오는 로직을 추가하세요.
비회원 구매자는 ANONYMOUS 값으로 결제위젯을 초기화할 수 있어요.
customerKey는 구매자와 1:1 관계로 연결되는 값입니다. UUID와 같이 충분히 무작위적인 고유 값을 사용하세요. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다.
결제 UI, 이용약관 UI를 보여주고 싶은 영역을 각각 div 태그로 정의하세요.
결제 버튼도 만들어주세요.
DOM이 생성된 이후에 renderPaymentMethods() 메서드로 결제 UI를 렌더링하세요.
결제 영역의 div CSS 선택자(Selector)와 결제 금액을 파라미터로 넣으세요. 여러 결제 UI를 만들었다면, variantKey를 결제위젯 어드민에서 확인하고 파라미터로 넘기세요.
어드민에서 결제 UI를 여러 개 만들었다면, 각 UI에 부여되는 키에요. 더 자세한 내용은 새로운 결제 UI 추가하기를 참고하세요.
네. ready 이벤트로 결제 UI 렌더링 완료 이벤트를 받을 수 있습니다.
애플페이는 iPhone 및 Mac Safari 에서만 노출돼요. 어드민 페이지에서는 예상 이미지를 확인할 수 있습니다.
UNAUTHORIZED_KEY에러가 나면 클라이언트 키를 다시 확인하세요.NOT_REGISTERED_PAYMENT_WIDGET에러가 나면 상점관리자에서 결제 UI를 추가하세요. 결제 UI가 생성되지 않았을 때 발생하는 에러입니다.- CSS 선택자(Selector)를 정확히 입력했는지 확인하세요.
- 특정 브라우저 환경에서만 렌더링이 안 된다면 익스텐션을 확인하세요. IE 환경은 지원하지 않습니다.
renderAgreement() 메서드로 이용약관 UI를 렌더링하세요.
이용약관 영역의 div CSS 선택자(Selector)를 파라미터로 넣으세요.
할인 쿠폰, 가격 정보 등 구매자에게 보여주고 싶은 기타 결제 UI를 직접 만들어서 추가해주세요.
결제 금액을 업데이트하려면 updateAmount()를 호출하세요. 파라미터에 새로운 결제 금액을 넣어주세요. 예를 들어, 5만원 주문에 5천원이 할인됐다면 4만5천원을 넣어주세요.
* 결제 금액이 UI에서 바뀌는 시점에 해당 메서드를 호출하세요.
결제를 요청하기 전에 orderId와 amount를 서버에 임시로 저장하세요. 결제 요청과 승인 사이에 데이터 무결성을 확인할 때 필요해요. 더 자세한 내용은 결제 흐름 가이드에서 확인하세요.
결제 버튼에 결제 요청 메서드 requestPayment()를 이벤트로 걸어주세요. 더 많은 파라미터는 SDK 문서에서 확인하세요.
결제 UI가 렌더링된 이후에 결제 요청 메서드를 호출하세요. ready 이벤트로 결제 UI 렌더링 완료 이벤트를 받을 수 있습니다.
구매자가 선택한 결제수단의 결제창이 정상적으로 열리지 않습니다. 반드시 결제 UI가 렌더링된 이후에 결제 요청 메서드를 호출하세요.
네. 결제를 요청하기 전에 getSelectedPaymentMethod()를 호출해서 구매자가 선택한 결제수단을 확인할 수 있습니다.
결제 성공 후 이동하는 successUrl로 받으세요. 적은 양의 데이터라면 successUrl의 쿼리 파라미터로 추가하세요.
만약 데이터가 많거나 결제 완료 전에 데이터를 처리해야 한다면, 결제 요청을 하기 전에 데이터베이스에 저장하세요.
결제 UI에서 자주 사용하는 결제수단을 선택하고 '결제하기' 버튼을 누르세요. 선택한 결제수단의 결제창에서 정보를 입력하세요. 테스트 환경에서는 결제가 가상으로만 이뤄지기 때문에 결제수단에서 금액이 차감되지 않아요. 결제를 마치면 결제 인증이 완료된 거예요.
클라이언트는 결제 인증이 성공하면 successUrl로 이동하고, 실패하면 failUrl로 이동해요.
아직 결제 요청 중이에요. 이어서 successUrl, failUrl 페이지에서 요청 결과를 확인한 뒤, 결제 승인 API까지 호출해야 결제가 완료돼요. iframe을 사용하고 있다면 요청 결과 페이지(successUrl, failUrl)로 이동할 수가 없어요.
카드사 앱스킴을 등록해야 돼요. 자세한 내용은 웹뷰 가이드에서 확인하세요.
iframe을 이용한 결제창 팝업 형태는 PC에서만 제공하고 있습니다.
결제 인증과 승인 사이에는 클라이언트가 이동하는 리다이렉트 과정이 있습니다.
결제 요청 과정에서 인증 결과를 받고 다음 단계로 넘어가기 위해 리다이렉트 URL 확인과 처리가 필요합니다. 토스페이먼츠에서 인증 결과를 URL의 쿼리 파라미터에 담아 리다이렉트하면, 상점에서는 리다이렉트 URL을 받아 결제를 승인할 수 있어요.
더 자세한 내용은 리다이렉트 처리하기, 결제 흐름 이해하기에서 확인해보세요.
결제 요청이 성공하면 successUrl로 이동합니다. URL에 아래 네 가지 쿼리 파라미터가 추가돼요.
쿼리 파라미터의 amount 값과 renderPaymentMethods()의 amount 파라미터의 값이 같은지 반드시 확인하세요. 클라이언트에서 결제 금액을 조작하는 행위를 방지할 수 있습니다.
만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요.
서버로 paymentKey, amount, orderId 값을 전달하세요. 결제 승인에 필요한 데이터입니다.
결제 승인 결과에 따라 클라이언트에서 필요한 결제 성공 및 실패 로직을 추가하세요.
결제 요청이 실패하면 failUrl로 이동합니다. 쿼리 파라미터로 돌아오는 에러 코드, 메시지를 확인하고 필요한 로직을 구현해주세요.
오류원인
구매자에 의해 결제가 취소되면 PAY_PROCESS_CANCELED 에러가 발생합니다. 결제 과정이 중단된 것이라서 failUrl로 orderId가 전달되지 않아요.
오류원인
결제가 실패하면 PAY_PROCESS_ABORTED 에러가 발생합니다.
해결 방법
-
오류 메시지를 확인하세요. 계약 관련 오류는 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.
-
기타 오류는 토스페이먼츠 실시간 기술지원 채널에서 문의해주세요.
오류원인
구매자가 입력한 카드 정보에 문제가 있다면 REJECT_CARD_COMPANY 에러가 발생합니다.
해결 방법
- 오류 메시지를 확인하고 구매자에게 안내를 해주세요.
개발자센터에서 결제 연동 키 > 시크릿 키를 불러오세요. 결제 연동 키는 토스페이먼츠 전자결제 신청 이후에만 확인할 수 있어요. 신청 전에는 아래 테스트 키로 연동해보세요.
시크릿 키와 :을 base64로 인코딩해서 Basic 인증 헤더를 아래와 같이 만들어주세요. :을 빠트리지 않도록 주의하세요. 비밀번호가 없다는 것을 알리기 위해 시크릿 키 뒤에 콜론을 추가합니다.
* 시크릿 키는 클라이언트, GitHub 등 외부에 노출되면 안 됩니다.
결제를 승인하면 결제수단에서 금액이 차감돼요. 토스페이먼츠 결제 승인 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로 결제를 조회 또는 취소해보세요.
실시간으로 결제 알림을 받고 싶다면 웹훅을 연동하세요.