Recychool 프로젝트에서 PortOne API 결제 흐름 정리

Recychool 프로젝트에서 예약 결제를 구현하면서
PortOne에서 제공하는 Browser SDK v2를 사용해
프론트와 서버의 역할을 분리한 결제 구조로 구성

프론트에서는 결제 UI와 결제 요청만 담당하고,
결제 성공 여부 판단과 상태 변경은 서버 기준으로 처리하는 방식

결제 전체 흐름

예약 생성 (PENDING)
→ 결제 페이지 진입 (/payment/:reserveId)
→ PortOne 결제창 호출
→ 결제 성공 응답 (impUid, merchantUid)
→ 서버 결제 검증
→ 결제 완료 / 상태 변경

PortOne 결제창 호출 (Frontend)

결제 페이지에서 PortOne Browser SDK v2를 사용해 결제창을 호출

• 결제 수단별로 channelKey 분리
• 프론트에서 paymentId 생성 → merchantUid 역할
• PortOne 결제 성공 시 반환되는 고유 ID를 서버 검증용으로 사용

결제 요청 시에는 최소한의 필수 정보만 전달

• storeId
• channelKey
• paymentId (merchantUid)
• amount
• customer 정보 (name, email, phone)

결제 성공 후에는 PortOne SDK 응답으로 받은 결제 식별자를 서버에 전달해
실제 결제 완료 처리 요청

결제 완료 처리 (Backend)

POST /private/payment/complete

프론트에서 전달받은 결제 정보에 대해
서버에서 결제 검증 → 저장 → 상태 변경 순서로 처리

처리 순서

1. impUid 중복 검사
2. reserveId 기준 결제 가능 여부 확인
3. PortOne 서버 결제 정보 조회 및 검증
4. 결제 금액 위·변조 여부 검증
5. Payment 저장
6. Reserve 상태 변경

이미 처리된 결제 요청에 대해서는
→ HTTP 409 (Conflict) 로 응답해 중복 결제를 차단