결제 연동
9. 결제 연동
온라인 쇼핑몰이나 서비스를 만들다 보면 반드시 마주치는 관문이 있습니다. 바로 결제 연동입니다. 아무리 Claude Code가 뛰어난 코드를 생성해도, 결제 연동은 단순히 코드만으로 해결되는 문제가 아닙니다. 사업자 등록, PG사 계약, 보안 인증 등 복잡한 절차가 기다리고 있습니다. 이 챕터에서는 한국에서 결제를 연동하는 과정과 현실적인 어려움, 그리고 이를 가장 쉽게 만들어주는 토스페이먼츠에 대해 이야기하겠습니다.
코드를 작성하는 것은 전체 과정의 일부에 불과합니다. 결제 연동은 사업자 등록, PG사 선택, 가맹점 신청, 심사 대기, 심사 결과, 계약 체결, API 키 발급, 개발 환경 설정, 테스트 결제 구현, 보안 검수, 실제 결제 테스트, 서비스 오픈의 단계를 거칩니다.
2. 한국의 결제 시스템 이해하기
한국의 온라인 결제는 독특한 구조를 가지고 있습니다. 가맹점(여러분의 쇼핑몰)과 카드사 사이에 PG사(Payment Gateway)라는 중간 역할을 하는 회사가 있습니다. PG사는 복잡한 카드사 연동을 대신 처리해주고, 통합된 API를 제공합니다. 대표적인 PG사로는 KG이니시스, NHN KCP, 나이스페이, 토스페이먼츠 등이 있습니다.
PG사를 통해 결제를 연동하려면 먼저 사업자 등록이 필수입니다. 개인 사업자든 법인 사업자든 사업자 등록증이 있어야 PG사와 계약할 수 있습니다. 이것이 첫 번째 진입 장벽입니다. 취미로 만든 프로젝트나 포트폴리오용 사이트에는 실제 결제를 연동할 수 없다는 뜻입니다.
사업자 등록을 마쳤다면 PG사를 선택해야 합니다. 각 PG사마다 수수료율, 정산 주기, 지원하는 결제 수단이 다릅니다. 신용카드 수수료는 보통 2.53.5%, 계좌이체는 1.52% 정도입니다. 정산 주기는 D+2(결제 후 2일)부터 D+7까지 다양합니다. 초기 사업자는 신용도가 낮아 정산 주기가 길어질 수 있습니다.
3. 가맹점 신청의 현실
PG사를 선택했다면 가맹점 신청을 해야 합니다. 이 과정이 생각보다 까다롭습니다. 사업자 등록증은 기본이고, 통신판매업 신고증, 사업장 임대차 계약서, 대표자 신분증, 통장 사본 등 다양한 서류를 제출해야 합니다. 판매할 상품이나 서비스에 대한 상세한 설명도 필요합니다.
특히 온라인 교육, 디지털 콘텐츠, 구독 서비스 같은 무형 상품은 심사가 더 까다롭습니다. 환불 정책, 서비스 이용 약관, 개인정보 처리방침 등을 명확히 작성해야 합니다. 심사 기간은 보통 3~7일이지만, 서류 보완 요청이 있으면 2주 이상 걸리기도 합니다.
심사를 통과하고 계약을 체결하면 드디어 API 키를 받을 수 있습니다. 하지만 이것이 끝이 아닙니다. 테스트 환경과 실제 환경의 키가 다르고, 각각 설정해야 할 것들이 있습니다. 웹훅(Webhook) URL 설정, 허용 도메인 등록, 보안 설정 등을 해야 합니다.
4. 토스페이먼츠가 만든 변화
이런 복잡한 과정을 획기적으로 개선한 것이 토스페이먼츠입니다. 토스페이먼츠는 개발자 경험(Developer Experience)에 집중하여 결제 연동의 진입 장벽을 크게 낮췄습니다.
먼저 문서가 정말 잘 되어 있습니다. 한국어로 된 명확한 가이드, 실제 작동하는 예제 코드, 단계별 튜토리얼이 제공됩니다. 다른 PG사들의 문서가 마치 90년대에 작성된 것처럼 보인다면, 토스페이먼츠는 2020년대의 현대적인 문서를 제공합니다.
테스트 환경도 혁신적입니다. 사업자 등록 없이도 테스트 계정을 만들어 바로 개발을 시작할 수 있습니다. 테스트 카드 번호를 제공하여 실제와 동일한 결제 플로우를 체험할 수 있습니다. 이렇게 먼저 개발하고 테스트한 후, 나중에 사업자 등록을 하고 실제 결제로 전환할 수 있습니다.
코드도 정말 간단합니다. 토스페이먼츠의 결제 위젯을 사용하면 몇 줄의 코드로 결제 화면을 구현할 수 있습니다.
5. 그럼에도 남는 어려움
토스페이먼츠가 많은 부분을 개선했지만, 여전히 개발자가 아니면 넘기 힘든 산들이 있습니다. 가장 큰 문제는 에러 처리입니다. 결제는 돈이 오가는 민감한 부분이므로 수많은 예외 상황이 발생합니다.
카드 한도 초과, 정지된 카드, 본인인증 실패, 네트워크 오류, 중복 결제, 부분 취소 등 처리해야 할 에러 케이스가 수십 가지입니다. 각 에러마다 사용자에게 적절한 안내 메시지를 보여주고, 로그를 남기고, 필요하면 관리자에게 알림을 보내야 합니다.
보안도 큰 이슈입니다. 결제 정보는 절대 클라이언트에 노출되어서는 안 됩니다. 서버 사이드에서 검증하고, HTTPS를 적용하고, SQL 인젝션이나 XSS 같은 공격을 방어해야 합니다.
정산과 세금 처리도 복잡합니다. 매출이 발생하면 부가가치세를 신고해야 하고, 현금영수증과 세금계산서를 발행해야 합니다. 환불이 발생하면 정산 내역을 수정해야 하고, 부분 환불의 경우 계산이 더 복잡해집니다.