리다이렉트 URL은 어떻게 설정해야 돼요?

2024년 4월 19일 ・ 읽는 시간 7분

토스페이먼츠 결제 과정에서는 결제 요청과 승인, 크게 두 개의 단계가 있어요. 결제 요청이 성공하면 승인 API를 호출해서 결제를 완료하고, 실패하면 에러를 처리해요. 결제 요청의 성공, 실패 결과는 각각 successUrl, failUrl 리다이렉트 URL로 받는데요. 자세한 설명은 리다이렉트 URL로 결제 정보 받는 법을 참고하세요.

근데 리다이렉트 URL은 어떤 URL로 설정해야 되나요? 클라이언트 페이지? 서버의 엔드포인트? 정답은 원하는 방식대로입니다. 가맹점 결제, 주문 시스템 및 기술 스택에 가장 적합한 방법을 선택하면 되는데요. successUrl을 다르게 설정할 수 있는 방법 세 가지를 알아볼게요.

가장 직관적인 방법은 successUrl을 결제 완료 페이지로 설정하는 거예요.

하지만 승인까지 끝나야 결제가 최종적으로 완료되죠. 클라이언트가 결제 완료 페이지에서 서버를 호출해요. 서버에서 승인을 요청한 뒤에 데이터를 처리하고요.

승인이 완료되기 전까지 구매자에게 “결제 완료” 메시지가 보이지 않게끔 조건부 렌더링을 사용해주세요. 승인 요청이 성공하면 “결제 완료” 메시지를 구매자에게 보여주고, 만약 실패하면 “결제 실패” 메시지를 보여주던가 결제 실패 페이지로 리다이렉트 시켜주세요. 토스페이먼츠 결제위젯 Vue 예시가 이런 방법으로 구현되어 있어요.

• 장점: 구현이 비교적 간단하기 때문에 관리 및 유지보수가 수월해요.
• 단점: 구매자가 성공 페이지를 새로고침하면 다시 결제 승인이 호출되어 오류가 발생할 수 있어요. 저장한 데이터로 결제 상태를 확인하거나, 멱등키를 활용해야 돼요.ALREADY_PROCESSED_PAYMENT와 같이 중복 처리와 관련된 에러를 무시하는 로직을 추가할 수도 있고요.

조건부 렌더링이나 승인 중복 문제가 어렵게 느껴지면successUrl을 결제 로딩 페이지로 설정하세요.

로딩 페이지에서 서버를 호출하고 결제 승인을 요청하세요. 승인 결과에 따라 클라이언트를 실패, 성공 페이지로 리다이렉트해주세요. 성공 페이지 방법보다 구현해야 되는 화면은 늘지만 결제 과정의 로직은 더 간단해요. 구현 예시는 토스페이먼츠 개발자센터 샌드박스에서 확인할 수 있어요. 다만 샌드박스는 결제 과정의 이해를 도우려고 수동으로 승인을 요청하고 있기 때문에 참고만 해주세요.

• 장점: 승인이 중복 호출될 위험이 없어요. 구매자에게 결제 단계를 자세히 안내할 수 있어요.
• 단점: 로딩 페이지, 리다이렉트 과정을 추가해야 돼요.

마지막 방법은 successUrl을 서버에 있는 엔드포인트로 설정하는 거예요.

클라이언트를 거치지 않고 결제 요청이 성공하면 바로 서버 엔드포인트가 호출돼요. 해당 서버 엔드포인트에서는 결제 승인 API를 호출하고 필요한 주문 및 결제 데이터를 처리해요. 서버는 승인 결과에 따라 클라이언트를 결제 성공, 실패 페이지로 리다이렉트 시켜줘요.

• 장점: 클라이언트에 새로운 페이지가 필요 없고 승인이 두 번 호출되는 위험도 없어요.
• 단점: 승인을 호출하는 과정이 오래 걸리면 구매자는 같은 페이지를 계속 보고 있어요. 백엔드 로직이 복잡해져요.

이번 아티클에서는 successUrl을 설정할 수 있는 세 가지 방법을 알아봤는데요. 가맹점의 개발 환경, 결제 시스템에 따라 적절한 방법을 사용해주세요. 마지막으로는 리다이렉트 과정에서 successUrl 관련해서 자주 묻는 질문을 공유드려요.

Q. 리다이렉트 URL은 아무거나 사용해도 되나요?

아니요. 결제창을 호출한 URL과 같은 Origin을 사용해주세요.

Q. successUrl에 커스텀 파라미터를 추가할 수 있나요?

특별히 커스텀 파라미터를 추가하는 것을 지원하지는 않아요. 필요하다면 쿠키, 세션에 데이터를 저장하거나 successUrl에 쿼리 파라미터를 임의로 붙이세요. successUrl은 일반적인 GET 방식의 URL이어야 해요. 가능하면 200자 내로 설정하는 것을 추천드려요.

Q. paymentKey, orderId, amount가 구매자에게 노출돼도 괜찮나요?

successUrl로 이동하면 토스페이먼츠는 paymentKey, orderId, amount 값을 쿼리 파라미터로 넘겨줘요. 이 값은 모두 구매자에게 노출이 되어도 보안 문제는 없습니다. paymentKey, orderId를 구매자가 알아도 시크릿 키가 없다면 결제를 승인하거나 취소할 수 없어요. 그렇기 때문에 시크릿 키를 외부에 노출되지 않는 게 더 중요해요! 클라이언트 코드, GitHub 등 외부에서 볼 수 있는 곳에 시크릿 키를 노출하면 안 돼요.

Q. 특정 환경, 기기에서만 리다이렉트가 안돼요.

브라우저 확장 프로그램 또는 VPN을 사용하고 있는지 확인하세요. 사용하고 있다면, 잠시 사용을 해지하고 다시 결제를 시도해보세요. 해지한 뒤에도 문제가 지속된다면 토스페이먼츠 실시간 기술 문의로 찾아와주세요.

Writer 박수연 Graphic 이은호, 이나눔

📍 함께 읽으면 좋을 콘텐츠

• 리다이렉트 URL로 결제 정보 받는 법
• 결제 흐름 이해하기