[Froppy 개발기 5편] 결제 시스템 구축 — PortOne 연동과 PG 심사에서 배운 것
9일 전
▣Froppy7개 기록▲ 목록 접기
결제 시스템 구축 — PortOne 연동과 PG 심사에서 배운 것
결제창을 띄우는 것과 결제 서비스를 운영하는 것은 다른 문제였다.
Froppy에는 1회성 후원과 멤버십 정기 구독이 있었다.
결제 SDK를 연결하고 성공 화면을 보여주는 것은 구현의 일부였다. 실제로 더 신경 써야 했던 것은 주문 상태를 관리하고, 서버에서 결제 결과를 확인하고, 취소나 웹훅에도 데이터가 일관되게 반응하도록 만드는 일이었다.
그리고 코드가 잘 동작한다고 해서 PG사의 심사까지 통과하는 것은 아니었다.
이 글에서는 Froppy가 실제로 사용한 PortOne 중심의 결제 흐름과, PG 심사를 거치며 배운 현실을 정리한다.
먼저 바로잡을 점: Toss Payments 직접 연동은 아니었다
개발 환경에는 Toss Payments 관련 설정값이 있었고, 화면에도 Toss Pay 결제 채널이 표시됐다. 그래서 처음에는 “Toss Payments와 PortOne을 각각 연동했다”고 생각하기 쉬웠다.
하지만 코드를 확인해보니 실제 흐름은 달랐다.
- 후원 결제 요청은 PortOne SDK를 사용한다.
- 결제 화면에서 Kakao Pay, Toss Pay, 카드 등 PortOne에 설정한 채널을 선택한다.
- 정기 구독 빌링키 발급과 결제도 PortOne API를 사용한다.
- 별도로 설정된 Toss client key는 현재 결제 코드에서 직접 사용하는 경로를 확인하지 못했다.
따라서 정확히 표현하면 PortOne을 통해 여러 결제 채널을 연결한 구조였다. Toss Pay 채널을 쓴 것과 Toss Payments API를 직접 연동한 것은 같은 말이 아니다.
결제 기능을 두 가지로 나눴다
Froppy의 결제 흐름은 크게 두 가지였다.
1회성 후원
사용자가 크리에이터에게 원하는 금액을 한 번 결제한다.
- 후원 주문 생성
- PortOne 결제창 실행
- 결제 결과를 백엔드에 전달
- 백엔드에서 결제 상태 확인
- 후원 완료 처리와 알림 발송
멤버십 정기 구독
사용자가 멤버십에 가입하고, 이후 주기적으로 결제한다.
- 구독을 대기 상태로 생성
- 결제 수단 등록 및 빌링키 발급
- 빌링키로 첫 결제
- 스케줄러가 다음 결제일에 정기 결제 요청
1회성 결제와 정기 구독은 화면에서는 모두 “결제”지만, 서버의 상태와 후속 처리는 달랐다.
1회성 후원: 주문을 먼저 만들고 결제를 시작한다
후원 결제를 시작할 때 Flutter가 처음부터 결제창을 띄우지는 않는다. 먼저 백엔드에 후원 요청을 보내고, DB에 PENDING 상태의 후원 주문을 만든다.
Flutter 앱
→ POST /payments/sponsorships
→ 백엔드에서 PENDING 후원 생성
→ orderId 반환
→ PortOne 결제 실행
이때 백엔드는 최소 후원 금액도 확인하고, 결제 전에 사용할 orderId를 발급한다. Flutter는 PortOne 결제 요청에 필요한 paymentId를 준비한 뒤 주문 정보와 함께 결제 흐름으로 넘어간다.
결제 UI 실행 방법은 플랫폼별로 달랐다.
- 모바일 앱: Flutter용 PortOne 결제 위젯 사용
- 모바일 웹: 결제 전용 페이지로 현재 탭 이동
- 데스크톱 웹: 새 탭에서 결제 후 부모 창으로 결과 전달
결제창을 새 탭으로 열면 결제 도중 원래 화면 상태를 유지할 수 있지만, 팝업 차단이나 창 간 결과 전달을 고려해야 한다. 모바일 웹에서는 새 창보다 같은 탭 리다이렉트가 더 자연스러운 경우가 있었다.
결제 성공 화면을 믿지 않고 서버에서 다시 확인한다
결제창에서 성공 결과를 받았다고 곧바로 DB의 후원 상태를 완료로 바꾸면 안 된다. 클라이언트가 보낸 결과만으로는 결제가 실제로 성공했는지 확정할 수 없기 때문이다.
Froppy의 Flutter 앱은 결제 결과를 받은 후 백엔드의 POST /payments/confirm을 호출한다. 백엔드는 PortOne API로 해당 paymentId의 결제 정보를 다시 조회하고, 결제 상태와 금액을 확인한 다음 후원 상태를 완료로 바꾼다.
결제창 결과
→ Flutter가 paymentId, orderId, amount 전달
→ 백엔드가 PortOne API에서 결제 조회
→ 상태가 PAID인지 확인
→ 후원 데이터 완료 처리
→ 수혜자에게 알림
금액이 일치하지 않으면 결제를 취소하도록 요청하는 코드도 있었다. 완료된 주문은 중복 처리하지 않도록 확인하는 로직도 들어가 있었다.
여기서 중요했던 검증의 경계
현재 구현은 PortOne에서 조회한 결제 금액을 confirm 요청으로 전달된 금액과 비교한다. 하지만 확인한 코드만으로는 다음 항목까지 검증한다고 말할 수 없다.
- 요청의 금액이 DB에 저장된 후원 주문 금액과 같은지
- 주문의 소유자가 현재 인증된 사용자와 같은지
- PortOne 결제의 주문 정보가 해당 DB 주문과 연결되는지
즉, “서버에서 PortOne 결제 정보를 조회한다”와 “주문·사용자·금액의 모든 관계를 완전하게 검증한다”는 다른 수준이다. 결제 검증을 설명할 때 이 둘을 같은 의미처럼 쓰면 안 된다.
운영 수준으로 마무리하려면 서버가 DB의 주문을 기준으로 기대 금액과 후원자 정보를 가져오고, 결제 레코드와 주문의 연결 관계를 확인하도록 설계해야 한다. 클라이언트가 보낸 금액을 최종 기준으로 삼지 않는 것이 핵심이다.
웹훅: 서버가 결제 상태 변경을 놓치지 않게 하기
결제 완료 요청은 Flutter에서 오지만, 결제 상태 변경을 서버가 직접 통지받을 수 있도록 PortOne 웹훅 경로도 만들었다.
PortOne
→ POST /payments/webhook
→ 백엔드에서 결제 이벤트 처리
→ 후원/구독 상태 동기화
웹훅은 사용자가 결제창에서 앱으로 돌아오지 않거나, 클라이언트 요청이 네트워크 문제로 누락되는 상황에도 서버가 상태를 확인하는 데 도움이 된다.
결제 완료 이벤트가 중복으로 올 수 있으므로 이미 완료된 결제인지 확인하는 멱등성 처리도 필요하다. 웹훅이 한 번만 온다고 가정하면 재시도나 네트워크 상황에서 중복 처리가 발생할 수 있다.
실제 구현에서 발견한 보완점
Froppy 코드에는 웹훅 서명 검증을 시도하는 부분이 있지만, 검증에 실패해도 경고 로그를 남긴 뒤 처리를 계속하는 경로가 있었다. 따라서 이 구현을 “웹훅 서명을 검증해 안전하게 처리한다”고 설명할 수는 없다.
또한 주석에는 요청 본문을 다시 직렬화할 때 서명 검증에 문제가 생길 수 있어 raw body가 필요하다는 내용이 있다. 웹훅의 서명 검증은 실패 시 이벤트 처리를 중단하도록 하고, 제공자가 요구하는 원본 body를 기준으로 검증하도록 다듬어야 한다.
웹훅은 외부에서 들어오는 결제 이벤트다.
서명 검증이 실패했는데도 상태 변경을 계속하는 것은 운영 전에 반드시 고쳐야 할 항목이다.
정기 구독: 카드 등록과 빌링키 결제
정기 구독은 단순히 매달 같은 결제 API를 호출하는 기능이 아니었다. 먼저 고객이 반복 결제를 허용하는 결제 수단을 등록해야 했다.
Froppy의 흐름은 다음과 같았다.
- 백엔드에
PENDING구독을 생성한다. - Flutter가 PortOne 빌링키 발급 페이지를 연다.
- 고객이 결제 수단을 등록한다.
- 발급된 빌링키를 백엔드에 전달한다.
- 백엔드가 빌링키로 첫 결제를 시도한다.
- 구독을 활성화하고 다음 결제일을 기록한다.
- 스케줄러가 이후 결제일에 PortOne API로 결제를 요청한다.
빌링키는 정기 결제에 사용할 수 있는 민감한 식별 정보다. 결제 수단 정보와 마찬가지로 클라이언트 로그나 일반 로그에 노출하지 않도록 주의해야 한다.
스케줄러와 중복 실행
Froppy는 NestJS 스케줄러를 이용해 구독의 다음 결제 시점을 처리했다. 결제가 실패하면 실패 상태와 횟수를 기록하는 흐름도 있었다.
다만 애플리케이션 인스턴스를 여러 대로 늘리면 각 인스턴스의 스케줄러가 같은 작업을 실행할 수 있다. 단일 인스턴스에서 동작하던 코드가 서버 확장 후 중복 청구를 만들지 않도록 분산 락, 작업 큐, DB 기반 선점 등 별도의 중복 실행 방지 전략이 필요하다.
결제와 약관 동의를 함께 기록하기
후원 결제 요청 화면에서는 이용약관, 개인정보처리방침, 환불정책 관련 동의를 다뤘다. 결제가 완료되면 백엔드가 동의 항목과 함께 결제 컨텍스트, 주문 ID, 결제 ID, 금액, 요청 IP와 User-Agent 등을 기록하도록 구성했다.
결제와 관련된 동의는 화면의 체크박스만으로 끝나는 데이터가 아니다. 언제, 어떤 문서 버전에, 어떤 흐름에서 동의했는지 기록할 수 있어야 나중에 확인할 근거가 된다.
다만 실제 적용할 법적 문구와 동의 방식은 서비스 형태와 관련 법률에 따라 검토가 필요하다. 구현 코드가 법률 적합성을 보장하는 것은 아니다.
PG 심사는 SDK 연동과 별개의 문제였다
결제 SDK를 연결하고 테스트 결제를 성공시켰다고 해서 실제 서비스가 결제를 받을 수 있는 것은 아니었다.
나는 KG 이니시스에 여러 차례 심사를 신청했고, 최종 심사 전에 피벗을 결정했다. NHN KCP에서는 후원이라는 서비스 사유로 최종 반려를 받았다.
이 경험을 통해 분명히 알게 된 점이 있다.
- 결제 API 연결은 기술적인 연동 문제다.
- PG 계약과 심사는 사업 모델, 판매 상품, 자금 흐름, 환불·민원 처리 등 운영과 정책의 문제다.
- 테스트 결제 성공은 PG사의 실제 서비스 승인과 다르다.
서비스 코드가 결제 완료를 처리할 수 있어도, PG사가 해당 사업 모델을 취급할 수 없다고 판단하면 운영 결제는 시작할 수 없다. 이 부분은 개발을 다 끝낸 뒤 확인할 게 아니라, 아이디어 검증 단계에서 먼저 확인해야 했다.
삽질하며 배운 점
1. 결제 요청 전에 서버 주문을 만든다
클라이언트에서 금액과 수혜자를 임의로 정해 결제를 시작하지 않도록, 서버에서 주문을 먼저 생성하고 상태를 추적하는 구조가 필요했다.
2. 결제창 응답은 최종 근거가 아니다
브라우저나 앱이 보낸 “성공” 표시만 믿지 않고, 백엔드가 PG/결제 플랫폼에서 결제 상태를 다시 확인해야 한다.
3. 주문 금액은 DB를 기준으로 검증한다
클라이언트가 전달한 금액과 PG 응답 금액이 같다는 것만으로는 부족하다. DB에 보관된 주문 금액, 사용자, 주문 ID와 결제 데이터를 연결해 확인해야 한다.
4. 웹훅 검증 실패는 무시하지 않는다
서명 검증이 실패하면 이벤트 처리도 실패로 끝내야 한다. 원본 body 처리와 재시도, 중복 이벤트까지 함께 설계해야 한다.
5. 정기 결제에는 실패와 중복 처리가 따라온다
빌링키 발급, 첫 결제, 다음 결제일, 결제 실패, 재시도, 구독 해지까지 하나의 상태 흐름으로 다뤄야 한다.
6. PG 정책을 제품 개발보다 먼저 확인한다
PG사가 취급할 수 없는 모델이라면 결제 화면을 더 다듬어도 해결되지 않는다. 개발 착수 전에 사업 모델과 심사 가능성을 확인하는 것이 훨씬 효율적이었다.
마치며
Froppy를 만들며 PortOne 결제창을 Flutter 웹과 모바일에 연결했고, 후원 주문과 구독 상태를 NestJS에서 관리했다. 빌링키와 스케줄러도 구현하면서 결제 시스템이 단순히 “결제 버튼을 붙이는 일”이 아니라는 것을 배웠다.
그리고 PG 심사는 코드 바깥의 문제였다. 기술적으로 결제를 받을 준비가 되어 있어도 사업 모델이 승인되지 않으면 서비스는 운영될 수 없었다.
돌아보면 결제 기능을 구현하기 전에 먼저 물었어야 할 질문은 “어떤 SDK를 쓸까?”가 아니었다.
“이 사업 모델이 실제 PG 계약과 심사를 통과할 수 있을까?”
이 시리즈는 총 8편으로 구성됩니다.
- [1편] 기획 & 아키텍처 — Flutter + NestJS + Cloudflare를 선택한 이유
- [2편] Flutter로 Web과 Mobile 동시 개발하기
- [3편] NestJS로 스타트업 백엔드 설계하기
- [4편] 소셜 로그인 3종 세트 — Google / Kakao / Naver OAuth 연동 실전
- [5편] 결제 시스템 구축 — PortOne 연동과 PG 심사에서 배운 것 ← 현재 글
- [6편] Supabase + Cloudflare로 인프라 구성하기
- [7편] 실시간 채팅 — WebSocket Gateway + Cloudflare R2
- [8편] 피벗 — Froppy를 접기로 한 결정

