최종 결제 승인 실패 또는 failUrl 호출된 후 실패에 대한 처리 관련 문의
안녕하세요, 스프링 프레임워크(EgovFramework) 환경에서 '토스페이먼츠' Javascript SDK를 이용하여 카드결제, 가상계좌, 계좌이체 일반 결제 모듈을 순차적으로 연동중에 있습니다.
토스페이먼츠에서 깃헙에 제공하는 'Spring boot' 샘플 소스코드를 바탕으로 작업 진행 중 successUrl 호출 시 동작하는 소스코드에서의 실패 처리와, failUrl 호출 시 동작하는 소스코드에서의 실패 처리는 어떤 차이가 있으며, 각각이 어떤 상황에서 동작하게되는지 궁금합니다.
또한, 테스트 모드로 실패처리를 진행해 볼 수 있는 방법이 있을까요?
(첫 번째 이미지는 successUrl 호출 시 동작하는 소스코드, 두 번째 이미지는 failUrl 호출 시 동작하는 소스코드입니다.)
23 Replies
안녕하세요! 먼저 테스트 환경에서 에러코드 진행 방법 설명 링크 보내드립니다.
https://docs.tosspayments.com/guides/testing#%ED%85%8C%EC%8A%A4%ED%8A%B8-%EC%BD%94%EB%93%9C-%ED%97%A4%EB%8D%94-%EC%82%AC%EC%9A%A9%ED%95%98%EA%B8%B0
테스트 환경 | 토스페이먼츠 개발자센터
테스트 환경에서 개발할 때 사용할 수 있는 기능과 라이브 환경과는 다른 부분을 알아봅니다.
success fail url 차이는 아래 링크 참고바랍니다!
일반 결제 JavaScript SDK | 토스페이먼츠 개발자센터
토스페이먼츠 일반 결제 JavaScript SDK 사용을 위한 준비와 메서드 사용법, 결제 실패 및 에러 처리 방법을 알아봅니다.
답변 감사드립니다. failUrl이 호출되는 경우에는 paymentKey 값이 전달되지 않다고 이해하는게 맞을까요? 왜 이런 질문을 했냐면 현재 저희 상점(쇼핑몰) DB상에서 결제 정보와 결제 실패 정보를 저장시키기 위함이기 때문입니다.
예를 들어, successUrl 호출 이후 결제 승인 API 처리 부분에서 에러가 발생한다면 이미 paymentKey는 발급되었기 때문에 응답 데이터에 paymentKey, transactionKey 등 여러 값들과 합께 'failure'라는 값으로 에러 정보가 포함되어 반환되는 것으로 알고 있기에 이를 활용하면 되지만
failUrl이 호출되어 에러 처리를 해야하는 경우 paymentKey가 별도로 존재하지 않아 저희가 하고자 하는 결제 실패 정보를 저장할 수는 없을 것으로 보여서요!
즉, 저희쪽에서 하고자 하는 '결제 실패 정보 저장' 기능처럼 결제 승인 API가 호출되는 시점 이후의 실패 정보만을 저장하려고 한다면 failUrl은 단지 '결제 실패화면 전환'용도로 사용할까 합니다.
paymentKey는 인증에 성공했을 때만 전달되기 때문에, failURL로도 전달되지 않습니다!
다만 failurl로 orderId는 전달해드리고 있기때문에. 해당주문건이 어떤 이유로 결제승인까지 못하고 실패했는지 정보의 관리가 필요하실 경우, orderID를 활용해주시면 됩니다.
감사합니다.
저희 상점(쇼핑몰) DB의 결제 정보와 관련된 스키마 구조상
'PG 결제 기본 정보 관리 테이블(부모)'과 'PG 결제 실패 정보 관리 테이블(자식)'이 존재하고
이 둘은 1:1 연관관계를 맺고 있으며,
자식 테이블의 경우 부모 테이블의 paymentKey를 참조하고 있는 형태이기 때문에 orderId 외 필수로 paymentKey를 받아 처리해야하는 이슈가 있더라구요.
항상 친절하고, 자세한 답변 감사드립니다!
안내해주신 문서를 읽고, 테스트 환경에서 에러코드 테스트 진행을 해보았습니다.
다만 SuccessUrl 호출 후 결제 승인 API를 호출하는 상황에서
요청 header에 임의의 에러코드를 전달하니, 그 결과의 HTTP Status code가 400번으로 반환되어 Exception(예외)로 넘어가서 소스코드 상의 if 문에 의한 실패 처리가 불가한 상황입니다.
이런 경우는 예외처리 코드에서 실패에 대한 처리를 진행해야하는게 맞을까요?(예를 들어, paymentKey에 대한 결제 실패정보를 상점 DB에 저장 등)
에러코드 링크를 보시면 HTTP 400으로 return 해드리는게 맞습니다. (https://docs.tosspayments.com/reference/error-codes#%EC%9D%BC%EB%B0%98-%EA%B2%B0%EC%A0%9C-api%EB%B3%84-%EC%97%90%EB%9F%AC-%EC%BD%94%EB%93%9C)
더불어 사용하신 '결제승인API'에는 입력하신 에러코드가 없으니 위 링크 다시한번 확인바랍니다.
감사합니다!
결제 실패 처리에 대해 마지막으로 질문드립니다.
successUrl 이후 '어떠한 이유'로 결제 실패되어 처리하는 로직과
다르게 failUrl(/fail.do 로 설정하였음)은 어떤 상황에 호출 되는 것인지 알 수 있을까요?
제가 이해를 못한 것인지...
failUrl에 대한 백엔드쪽 처리 소스코드를 작성해 놓아도, 호출되지 않는 것 같더라구요.
제가 테스트해본 상황은 세 가지였습니다.
1. 결제모듈을 띄운 후 ‘닫기’ 버튼 클릭을 통한 결제창 종료
2. 결제모듈 Javascript 메소드(requestPayment) 호출 시 결제 금액을 0원으로 설정(카드 결제로 테스트하였음)
3. successUrl 처리 로직에서 결제 승인 API를 호출하는 시점에서 header에 임의의 에러 코드 전달(이전 덧글에 첨부된 소스코드와 동일)
테스트환경은 로컬에서 진행했습니다.(localhost:8080)
추가로 '상점 DB 상의 주문 결제 금액'과 결제창을 열때 요청 값으로 전달한 'amount' 값이 상이한 경우에 대한 에러코드는 따로 없는 것일까요?
이 경우 개발자가 직접 알맞게 처리하면 되는 것이지요?
'amount' 값이 상이한 경우에 대한 에러코드는 FOR_BIDDEN_REQUEST를 보내줍니다
그렇군요. 토스페이먼츠측에서 제공하는 문서 페이지에서 찾아볼 수 없어서 질문드렸었습니다!
오타가 있었네요..! FORBIDDEN_REQUEST 입니다!
아, 문서에도 있네요! 감사합니다!
실례지만 이전 덧글중 failUrl에 대한 질문도 확인 부탁드리겠습니다!
급한건은 아니오니 천천히 답변 주셔도 될 것 같습니다.
fail URL로 반환해드리는 에러는. 에러 코드가 query params전달되기 때문에 http status 코드를 전달하거나 받을 수 없습니다.
이에 '테스트 코드 헤더'로도 에러 테스트도 불가합니다!
아... 그렇군요. 결국 failUrl에 대한 테스트는 저희가 포스트맨과 같은 툴을 이용하여 요청이 잘 들어가는지만 확인하면 되겠네요.
failURL은 sdk로 결제창 호출할 때 파라미터로 보낸 후, 실패시 return하는 곳이기 때문에 포스트맨으로도 에러코드 테스트가 어렵습니다.
어떤 절차로 진행하시려는 걸까요?
우선 저희 상점에서 토스페이먼츠 결제모듈 연동과 관련해서 하고자하는 것은 * 주문정보 마다의 결제 이력을 보관 * 하고자 합니다.
개발적인 부분으로 말씀을 드릴 수 밖에 없을 것 같은데요..!
위 요구사항을 달성하기 위해 DB에서
1. 주문건에 대한 결제 정보 테이블
2. 결제 정보에 대한 카드/가상계좌/계좌이체 각각 정보를 담는 테이블(결제 정보와 1:1 관계)
3. 결제 정보에 대한 결제 취소 테이블(결제 정보와 1:N 관계)
4. 결제 실패 테이블(결제 정보와 1:1 관계)
와 같이 설계를 하였습니다.
이는 고객이 상점 주문정보 입력 페이지에서 결제창을 호출하고 나서
successUrl -> 결제 승인 API를 통해 결제 정보를 처리하는 중 에러(잔액부족, 통신상의 오류 등)가 발생하거나,
어떠한 이유로 failUrl에 호출이 되는 경우 결제 실패 정보를 저장하기 위해서입니다.
절차를 물으신다면
1. 고객의 결제창 호출 --> 인증 성공 --> successUrl 호출 --> 결제 승인 API 호출 ---> 에러발생! --> 상점 DB상의 결제 실패 이력 저장
=> 이 경우는 HTTP Status Code가 400번으로 떨어져 예외를 처리하는 부분에서 주문정보를 취소, 결제가 승인된 건이라면 결제 취소 API를 호출할 예정입니다.
2. 고객의 결제창 호출 --> 에러발생! --> failUrl 호출 --> 상점 DB상의 결제 실패 이력 저장
두가지 경우로 생각하고 있습니다.
댓글 해주신 내용으로보아 failUrl은 Javascript SDK를 통해 '결제창' 호출에 실패 했을 때 호출되는 것으로 이해하면 될까요?
그렇다면 결제 승인 API 호출 이후 실패에 대한 처리와는 무관하며, 단순 '결제창 호출 실패'에 대한 이벤트라고 보면 되겠네요.
결제창 호출 실패(X)
결제창 호출 후 인증(앱카드, 카드번호 등) 단계에서 실패하여, paymentKey를 발급 받지 못하는 상황이 발생했을 때 입니다.
아..! 예를 들어, 저같은 경우 '국민은행'이 주거래여서 토스페이먼츠 결제모듈을 이용하는 경우 '국민 앱카드'로 결제를 진행하곤 했는데요.
이때 실패하는 경우라고 이해하면 되겠군요.
네네 맞습니다! 이해하고 계신 것처럼 '국민은행 앱카드' 인증이 성공하더라도 바로 결제되는 게 아니라.
'successUrl로 이동 > 결제승인 API호출' 단계를 거쳐야 결제가 성공합니다. (API호출단계에서 에러는 테스트헤더코드로 테스트 가능)
failUrl은 결제창에서 인증 등에서 이상이 생겼을 때 이동하는 url입니다.
드디어 이해를 했네요!
제가 말씀드린 내용 어려우셨을텐데 상세히 답변해주셔서 감사합니다.
항상 상세하게 문의해주셔서 감사드립니다.