이 문서에 대한 내용에 대한 문의는 토스페이먼츠 디스코드 사이트(https://discord.gg/44w6tQkw8N) 를 통해 언제든 가능합니다.

기본적인 결제 방식

모든 토스페이먼츠의 결제창을 통한 결제방식(결제위젯 포함) 은 2 transaction 으로 구성됩니다.

• 첫번째는 토스페이먼츠 결제창을 통해 paymentkey 를 발급받는 단계
• 두번째는 발급받은 paymentkey 와 결제금액을 확인하고 최종적으로 승인 요청하는 단계입니다.

첫번째 단계에서는 상점의 clientKey 를 이용해서 javascript 를 이용해서 결제창을 호출하고 (customerkey와 혼동하지 마십시오) 두번째 단계에서는 secretKey를 이용해 RESTful API 를 호출하시면 됩니다.

clientKey 는 FrontEnd 에서 사용되고 그러므로 외부에 노출되어도 무관합니다만, secretKey 는 BackEnd 에서 사용하셔야 하고 절대 FrontEnd 에서 사용되면 안됩니다. Javascript 나 FE platform 등에 secretKey 가 노출되지 않도록 주의해 주시기 바랍니다.

첫번째 단계가 완료되었을때 paymentkey 를 받는 방법은 2가지 가 있습니다.

• successURL, failURL 을 requestPayment 호출시 입력하고 해당 url로 redirect 하는법
• successURL, failURL 을 requestPayment 호출시 입력하지 않고 requestPayment 의 promise로 받는 법

다만 promise 로 받는 방법은 PC 에서만 사용가능하고 Mobile 에서는 사용할수 없으므로 특별한 제약이 없는 경우 첫번째 방식을 사용해 주시기 바랍니다.

첫번째 방식은 successURL 에 Get 방식 queryString 형태로 전달되고, 두번째 방식에서는 promise 에 paymentKey, orderId, amount 이 정보들이 바로 전달됩니다.

API 버전

API 의 요청이나 응답 파라미터는 버전에 따라 다르게 됩니다. 연동문서에서 언급된 특정 파라미터가 테스트나 라이브에서 보이지 않으시는 경우 대부분 API 버전이 다르기 때문입니다.

API 버전은 개발자 센터에서 수정이 가능하고 수정하면 즉시 적용됩니다. 그러므로 응답 처리가 준비 되지 않은 상태에서 API 버전을 변경하시면 갑자기 모든 결제에 문제가 발생할수 있습니다. 테스트 와 라이브의 API 버전을 별개로 설정할수 있으니 테스트키로 꼭 테스트 완료하신 후 라이브에 적용하시기 바랍니다.

API 릴리즈 노트는 https://docs.tosspayments.com/reference/release-note 여기를 참고하시고 각 버전별 추가/삭제된 파라미터는 https://docs.google.com/spreadsheets/d/1p9mVbIgOyi4U6R_4kUBXsvIhPQfabjtl6lV4DCRpAgM/edit?usp=share_link 여기서 확인이 가능합니다.