프로젝트 개요

<aside> 📎

Github : ‣

기간 2025.04.21 ~ 2025~05.01
구성원 BE 1명
담당 역할 BE
구현 기능 - HMAC 기반 요청 검증 및 인증 시스템 - 비동기 결제 처리 흐름 + Webhook 수신 처리 - 결제 상태 관리 및 이력 로그 시스템 - 재시도 가능한 안정적 Webhook 전송 (Fail-safe 처리)
기술 스택 Java, Spring Framework 5.3.37, MyBatis, MySQL, Postman
</aside>

<aside> 📝

SimplePG는 스프링 레거시와 MyBatis를 사용하여 MVP로 구현한 전자결제(PG) 서비스입니다.

턴키 방식을 사용해 가맹점의 결제 요청 등록, 상태 조회, 웹훅 응답 처리를 지원하는 백엔드 API를 제공합니다. 보안성 과 데이터 무결성 그리고 이 후 확장성을 우선적으로 고려했으며, 다양한 결제 수단과 플랫폼에 유연하게 대응할 수 있도록 구조화했습니다. 특히 HMAC을 활용한 인증 방식, 비동기 기반의 웹훅 처리, 세밀한 상태 흐름 제어를 통해 신뢰할 수 있는 결제 환경을 구현하기 위해 고민했습니다.

</aside>

동작 흐름도

image.png

  1. 결제 요청 생성
    1. 가맹점 서버가 SimplePG에 결제 요청을 보냅니다.
    2. HMAC 서명을 검증하고, 입력 데이터를 확인한 후 paymentKey를 생성합니다.
    3. 결제 정보와 로그를 데이터베이스에 저장하고, 결제 URL을 응답합니다.
  2. 외부 결제 시스템 연동
    1. 사용자가 결제 URL을 통해 외부 결제 시스템에서 결제를 진행합니다.
    2. 결제 완료 후 성공/실패 URL로 리다이렉션됩니다.
  3. 웹훅 처리
    1. 외부 결제 시스템(Mock Controller)이 SimplePG에 웹훅으로 결제 결과를 알립니다.
    2. 서명을 검증하고, WebhookServiceFactory를 통해 상태를 처리합니다.
    3. 결제 상태와 로그를 업데이트하고, 가맹점에 결과를 알립니다.
  4. 결제 상태 조회
    1. 가맹점이 paymentKey로 결제 상태를 조회합니다.
    2. SimplePG는 서명을 검증하고, 데이터베이스에서 상태를 조회하여 응답합니다.

설계 포인트

  1. 보안: API간 모든 요청/응답에 HMAC 서명 검증 적용하도록 하였습니다. (가맹점 ↔ PG ↔ 외부 결제)

  2. 확장성: WebhookServiceFactory로 추후 다양한 웹훅 처리를 지원하도록 설계하였습니다.

  3. 추적성: payment_log로 모든 결제에 관련한 상태 변경 기록을 기록하도록 하였습니다.

  4. 안정성: 트랜잭션 관리로 데이터 일관성 보장하였습니다. 추가로, Payment 상태 업데이트와PaymentLog 생성이 동시에 이루어지는 로직에서는 비관적락을 적용하여 동시처리를 방지하였습니다.