안녕하세요, HM소프트입니다.
오늘은 실제 프로젝트에서 토스페이먼츠 결제를 연동했던 경험을 공유드리겠습니다.
결제 기능은 쇼핑몰, 예약 플랫폼, 매칭 서비스 등 거의 모든 웹서비스에서 필수적인 기능입니다. 그중에서도 토스페이먼츠는 국내에서 가장 많이 사용되는 PG사 중 하나인데요, 실제로 연동해보니 문서는 잘 되어 있지만 실전에서 마주치는 문제들이 꽤 있었습니다.
1. 토스페이먼츠를 선택한 이유
여러 PG사를 비교했을 때 토스페이먼츠를 선택한 이유는 다음과 같습니다.
첫째, 개발자 문서가 깔끔합니다. REST API 기반이라 연동이 직관적이고, 테스트 환경도 잘 갖춰져 있습니다.
둘째, 수수료가 합리적입니다. 소규모 서비스 기준으로 다른 PG사 대비 경쟁력이 있습니다.
셋째, 다양한 결제 수단을 지원합니다. 카드, 가상계좌, 계좌이체, 간편결제 등을 하나의 API로 처리할 수 있습니다.
2. 연동 전 준비사항
토스페이먼츠 연동을 시작하기 전에 준비해야 할 것들이 있습니다.
사업자등록증이 필요합니다. 개인사업자도 가능합니다.
토스페이먼츠 가맹점 가입을 해야 합니다. 심사에 보통 3~5영업일 정도 걸립니다.
테스트용 API 키를 먼저 발급받아서 개발을 진행하는 것이 좋습니다.
제출 자료로는 서비스 화면 캡처, 결제 플로우 설명서 등이 필요합니다. 저는 PPT로 결제 프로세스 플로우를 만들어서 제출했습니다.
3. 결제 프로세스 플로우 설계
결제 연동에서 가장 중요한 것은 전체 플로우를 먼저 설계하는 것입니다.
기본 흐름은 다음과 같습니다.
사용자가 상품 선택 후 결제 버튼 클릭
-> 프론트엔드에서 토스페이먼츠 SDK 호출
-> 결제창 표시 (카드번호 입력 등)
-> 결제 성공 시 successUrl로 리다이렉트
-> 백엔드에서 결제 승인 API 호출 (paymentKey, orderId, amount 전달)
-> 승인 완료 후 주문 상태 업데이트
-> 사용자에게 결제 완료 페이지 표시
여기서 핵심은 백엔드에서 반드시 결제 승인을 한 번 더 해야 한다는 것입니다. 프론트엔드에서 결제가 완료되었다고 해서 끝이 아닙니다. 서버에서 금액 검증과 함께 최종 승인을 해야 실제로 결제가 처리됩니다.
4. 프론트엔드 구현 포인트
프론트엔드에서는 토스페이먼츠 JavaScript SDK를 사용합니다.
주의할 점은 orderId를 고유하게 생성해야 한다는 것입니다. 중복되면 결제가 실패합니다. UUID나 타임스탬프 조합을 사용하는 것이 좋습니다.
amount는 프론트에서 보내는 값과 백엔드에서 검증하는 값이 반드시 일치해야 합니다. 클라이언트에서 금액을 조작하는 것을 방지하기 위해 서버에서 반드시 원래 주문 금액과 비교 검증을 해야 합니다.
5. 백엔드 구현 포인트
백엔드에서 결제 승인 API를 호출할 때는 시크릿 키를 사용합니다.
가장 많이 실수하는 부분이 에러 처리입니다. 네트워크 오류, 타임아웃, 이미 승인된 결제 등 다양한 예외 상황을 처리해야 합니다.
또한 웹훅(Webhook)을 반드시 설정하세요. 결제 상태 변경(취소, 환불 등)을 실시간으로 받을 수 있습니다.
6. 실전에서 겪은 문제들
문제 1: 테스트 환경과 운영 환경의 차이
테스트에서는 잘 되던 결제가 운영에서 실패하는 경우가 있었습니다. 대부분 도메인 설정이나 리다이렉트 URL 설정 문제였습니다.
문제 2: 모바일 결제창 이슈
모바일에서 결제창이 제대로 표시되지 않는 경우가 있었습니다. iframe 관련 설정과 viewport 메타태그를 확인해야 합니다.
문제 3: 가상계좌 입금 확인
가상계좌는 결제 즉시 완료되는 것이 아니라 고객이 입금할 때까지 기다려야 합니다. 웹훅으로 입금 완료 알림을 받아서 처리해야 합니다.
7. 정리
토스페이먼츠 결제 연동은 문서만 보면 간단해 보이지만, 실제로는 예외 처리와 보안 검증에 상당한 시간이 들어갑니다. 특히 금액 검증, 웹훅 처리, 환불 로직은 꼼꼼하게 구현해야 합니다.
결제 연동이 필요한 프로젝트가 있으시면 HM소프트에 문의해 주세요.
실제 결제 시스템을 여러 차례 구축한 경험을 바탕으로 안정적인 결제 기능을 만들어 드리겠습니다.
홈페이지: https://hmsoft.it.kr
