기본적인 결제 방식
모든 토스페이먼츠의 결제창을 통한 결제방식(결제위젯 포함) 은 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 여기서 확인이 가능합니다.
승인 요청시 고려사항
결제가 완료된 후, 가맹점에서 DB에 넣는 작업중에 에러가 발생하거나, 잘못 주문을 받았거나, 재고가 없는등 여러가지 사유로 해당 주문을 롤백(망취소) 해야 하는 상황이 발생할 수 있습니다. 이경우 별도의 망취소용 API 는 제공하고 있지 않으므로, 일반 결제취소 API [링크] 를 이용하셔서 취소해 주시면 됩니다. 망취소 상황임을 구분하시려면 cancelReason 에 구분가능하도록 취소 사유를 적어 주시기 바랍니다.
승인 API [링크] 를 호출했는데, 네트워크 단절이나, time out 등으로 가맹점에서 정상적으로 응답을 받지 못하는 상황이 발생할수 있습니다. 하지만 실제로 토스페이먼츠 결제 서버는 요청을 받은 상태이므로 실제로 결제는 진행이 되었을 수도 있습니다. 이런경우 고객은 결제가 되었지만 가맹점에서는 결제가 되지 않은 상태로 보이므로, 이렇게 승인 API 에 대한 요청을 정상적으로 받지 못한 경우에는 다음과 같이 처리가 필요합니다.
정상응답을 받지 못하면 승인을 요청한 paymentKey로 결제조회 API [링크] 를 호출해서 status 가 Done 인지를 확인하신 후, Done 이라면 정상적인 결제 성공 처리를 하시면 됩니다. 혹시라도 정상 결제 성공 처리를 못한다면 결제 취소를 해주시면 됩니다.
동일한 paymentKey 에 대해 취소나 조회 API 를 짧은 시간(1초)에 반복적으로 요청하면 아래와 같은 에러를 받는 경우가 있습니다. {“code”:“FORBIDDEN_CONSECUTIVE_REQUEST”,“message”:“반복적인 요청은 허용되지 않습니다. 잠시 후 다시 시도해주세요.“} 이런 에러를 받으신다면 잠시후(1초) 에 다시 API 를 요청하시면 정상적으로 응답을 받을 수 있습니다. 취소나 조회의 Transaction 을 보장하기 위해 반복 요청을 제한하고 있습니다.
결제 건에 대한 상태
결제 상태는 결제 조회등에서 응답으로 확인 가능한 Payment.status 항목으로 확인이 가능합니다.
https://docs.tosspayments.com/reference#payment-객체 의 status 항목이 설명되어 있고, 각status 별로 이동하는 이벤트는 아래 그림과 같습니다.
결제건에 대한 Status 변경
결제 건에 대한 객체 Payment 객체는 아래와 같이 여러가지 상태를 가질수 있습니다.
테스트환경
테스트 환경에서 개발 테스트 상점의 경우(라이브 상점이 없는 경우) 결제 응답상의 MID(상점ID) 는 tvivarepublica 라는 단일 MID 로 응답하고 있습니다. (결제의 종류에 따라 tvivarepublica2,3,4 등으로도 응답할 수 있습니다.) 하지만 라이브 상점이 있는 경우는 t[MID] 라는 계약하신 MID 앞에 t 를 추가한 상점으로 응답합니다. 라이브 환경에서는 정상적으로 요청하신 상점 ID 가 표시 됩니다. 테스트 하실때 참고해 주시기 바랍니다.
원화 결제만 허용
모든 카드 결제는 원화 결제만 가능합니다. 해외 카드사 결제의 경우도 원화로 결제창 호출되며, 달러로 호출은 불가능합니다.
결제수단별 최소 결제 가능 금액
•
신용/체크 카드 - 100원
•
휴대폰 - 300원
•
실시간 계좌이체 - 200원
•
가상계좌 - 1원
환불정책
상점관리자를 통해서 결제를 취소할 수 있으며, 결제 취소 API [링크]를 통해서도 동일하게 결제를 취소할 수 있습니다. 상점에 각 결제 수단별 부분취소가 허용되어 있다면 모든 결제수단에 대해서 부분취소를 지원하고 있습니다.
환불이 진행되는 시점은 결제수단 및 취소 요청 시기에 따라 차이가 있습니다.
각 결제 수단별 당일 환불요청시 환불 일자와 환불 방법
•
신용카드
◦
당일 취소 : 취소 요청 직후 즉시
◦
부분취소는 당일 취소요청 이더라도 무조건 매입 후 취소가 진행 되어 취소 요청 후 영업일 3~4일 소요
•
체크카드
◦
전액 취소의 경우 취소요청 당일 환불
◦
당일 환불이 불가한 예외대상 - 부분취소, 프로모션(포인트, 청구할인 등)
•
가상계좌
◦
환불 요청 후 영업일 기준 D+2일 소요
◦
환불 계좌번호, 계좌주 입력 필요함
•
계좌이체
◦
실시간 환불
•
휴대폰
◦
통신사 정책으로 결제발생 당월에만 취소 가능, 그 이후에는 가맹점에서 자체 환불 진행 필요
◦
부분환불 - 전체금액 취소 후 취소된 금액을 제외한 나머지 금액이 재결제 되는 방식
•
상품권
◦
실시간 환불 - 상품권 금액이 복원됨
각 결제 수단별 익일 이후 환불요청시 환불 일자와 환불 방법
•
신용카드
◦
매입 후 취소 : 취소 요청 후 영업일 3~4일 소요
•
체크카드
◦
최대 10일 정도 소요, 전액 취소의 경우 취소요청 당일 환불
•
가상계좌
◦
환불 요청 후 영업일 기준 D+2일 소요
◦
환불을 위한 은행, 계좌 번호, 예금주명 정보가 필요함
•
계좌이체
◦
6개월(180일) 이내 거래에 대해 실시간 환불
•
휴대폰
◦
통신사 정책으로 결제발생 당월에만 취소 가능, 그 이후에는 가맹점에서 자체 환불 진행 필요
◦
부분환불 - 전체금액 취소 후 취소된 금액을 제외한 나머지 금액이 재결제 되는 방식
•
상품권
◦
실시간 환불 - 상품권 금액이 복원됨
결제 결과에 대한 이메일/SMS 정책
결제 진행 내용에 따라 이메일이나 SMS 로 고객에게 결제 상황을 알리고 있습니다.
•
신용카드(인증/비인증)
◦
결제 완료시 이메일 발송
◦
결제 취소시 이메일 발송
•
빌링
◦
빌링키 발급시 아무것도 보내지 않음
◦
결제 완료시 이메일 발송(레거시(=xpay)는 SMS 도 발생)
◦
결제 취소시 이메일 발송
•
계좌이체
◦
결제 완료시 이메일 발송
◦
결제 취소시 이메일 발송
•
가상계좌
◦
계좌 발급시 이메일/SMS 발송
◦
입금 완료시 이메일/SMS 발송
◦
결제 취소시에는 별도로 이메일 발송안함
•
휴대폰
◦
결제 완료시 이메일 발송
◦
결제 취소시 이메일 발송
•
상품권
◦
결제 완료시 이메일 발송
◦
결제 취소시 이메일 발송
결제 완료 이메일 샘플
가상계좌 SMS 샘플
모바일 App 을 사용하는 경우 고려사항
기본적으로 토스페이먼츠의 결제창은 web browser 환경만을 지원하고 있습니다. 그렇기 때문에 모바일 app 을 사용하는 경우 에도 결제창을 띄우는 부분은 webview 를 이용해서 구현해 주셔야 합니다.
Native 결제창은 현재 지원하지 않고 있고, 또한 모든 카드사의 인증창이 web browser 에만 호환되기 때문에 무조건 webview 를 이용해 연동을 하셔야 합니다.
토스페이먼츠는 다양한 연동방식을 제공하고 있으며, Native SDK 역시 지원하고 있습니다.
모바일 webview 사용시에는 카드사 앱으로 이동했다가 인증이 완료되면 다시 가맹점 앱으로 자동적으로 이동하기 위해 결제창을 띄우실 때 iOS 에서는 appScheme 이라는 파라미터에 가맹점 App 의 scheme 을 입력해 주셔야 합니다.
입력한 appScheme 을 이용해서 다시 가맹점 앱으로 이동하는 것을 지원하는 카드사는
•
안드로이드 : 모든 카드사 (appScheme 을 넘기지 않아도 가능)
•
iOS : 삼성, 현대, 신한, 비씨
이외의 경우는 사용자가 인증이 끝난후에 직접 가맹점앱으로 이동해야 합니다.
모바일 App 에서 외부 앱을 띄우기 위한 설정
토스페이먼츠에서 제공하는 방식으로 안드로이드, iOS webview 코드를 사용하게 되면 별도의 외부 패키지나, 앱스킴을 설정하지 않아도 카드사 앱을 띄우는데 문제가 발생하지 않습니다.
다만 저희가 가이드 하는 방법
•
안드로이드 : shouldOverrideUrlLoading 를 오버라이딩 하는 방법
•
iOS : WKNavigationDelegate protocol 의 특정 코드에 해당하는 메소드 구현
을 사용하지 않으시는 경우 별도로 3rd party App 을 띄우기 위해 특정 앱을 허용해 주셔야 합니다.
Android
•
AndroidManifest.xml 에 외부 패키지 명을 추가해야 합니다.
•
추가 해야 하는 외부 앱 패키지는 별도로 문의 주시기 바랍니다.
•
이부분이 설정되지 않으면, 카드사 앱이 오픈 되어야 할때 앱이 설치 되어 있음에도 불구하고 구글 플레이 스토어로 이동하는 현상이 발생합니다.
iOS
•
Info.plist 파일에 LSApplicationQueriesSchemes 를 수동으로 추가한 후 실행하고자 하는 외부 앱 스킴을 배열에 넣어 주면 됩니다.
•
추가 해야 하는 외부 앱 스킴은 별도로 문의 주시기 바랍니다.
•
이부분이 설정되지 않으면, 앱이 열리지 않고 콘솔쪽에 canOpenURL : failed for URL 에러가 발생합니다.
