[FEAT] 환불 → 정산 지급이체 차감 자동화 (Payple 정산지급대행 연동)

[minij02]

✨ 기능 설명

#485에서 환불 시 Settlement.status='Refunded'로 마킹은 되지만, 이미 지급된 정산금 회수 또는 다음 정산에서 차감하는 실제 회계 처리가 없음. Payple 정산지급대행 명세(파트너 인증 → 계좌인증 → 빌링키 이체 대기 → 실행 → Webhook)를 활용해 정산 사이클 자동화 + 환불 차감 정책 구현.

✨ 결정 필요 사항 (기획/회계 확정 필요)

정산 정책

1. 정산 사이클 주기
   • A. 주간 (예: 매주 월요일) — 빠른 정산
   • B. 월간 (예: 매월 15일) — 회계 단순 ← 권장 (Payple 정산 D+N 보통)
   • C. 실시간 (Succeed 시 즉시) — Payple rate-limit/수수료 부담
2. 정산 최소 금액 — 예: 1만원 이상부터 지급 (그 이하는 다음 사이클로 이월)
3. 환불 차감 정책 — 잔액 음수 처리
   • A. 다음 사이클로 이월 (계속 차감)
   • B. 즉시 청구 (관리자 알림 + 사용자에게 청구서)
   • C. 무시 (음수 잔액 그대로 유지)
4. 테스트 환경 이체 금액 — 명세상 sandbox는 tran_amt=1000 고정. 운영 전환 시 검증 필요

인프라

5. 빌링키 발급 시점 — 현재 verify-account 흐름은 Payple 실명인증만 호출. 정산지급대행 명세 2의 계좌인증은 billing_tran_id 반환 — 이걸 SettlementAccount에 저장해야 지급이체 가능
   • 본 이슈에서 verify-account 흐름을 정산지급대행 인증으로 전환? 또는 별도 endpoint?
6. Webhook 인증 — Payple Webhook 인증 방식 명세 확인 필요 (IP allowlist / 서명)

✨ 핵심 흐름 (구상)

[정산 사이클 cron — 매월 15일 KST 09:00]
  for each 판매자:
    1. 미정산 금액 계산
       = SUM(Settlement.status=Succeed 직전 사이클 이후)
       - SUM(Settlement.status=Refunded 직전 사이클 이후)
       - 이월 음수 잔액
    2. 최소 금액 미만이면 SKIP (다음 사이클 이월)
    3. billing_tran_id 미보유 시 SKIP + ERROR (계좌 재등록 안내)
    4. Payple 이체 대기 (3) → group_key 받음
    5. Payple 이체 실행 (4, NOW)
    6. SettlementPayout row 생성 (status=Pending)
  Webhook 수신 시:
    1. SettlementPayout 상태 업데이트 (Succeed/Failed)
    2. 알림 (선택)

✨ 개발 목록

Prisma 스키마

• SettlementAccount.billing_tran_id String? 추가 (계좌인증 응답 빌링키 저장)
• SettlementPayout 모델 신규 — 정산 지급이체 이력

  user_id / amount_gross(Succeed합) / amount_refund(Refunded합) / amount_net /
  cycle_start / cycle_end / payple_group_key / payple_api_tran_id /
  status(Pending|Succeed|Failed) / requested_at / completed_at
  

• 마이그레이션

Payple 정산지급대행 유틸 (utils/payple-payout.ts 신규)

• fetchPayoutAuth() — 파트너 인증 (code 10자리 영문+숫자, access_token 60초)
  • 기존 verify(실명인증)와 같은 인증인지 확인 필요 — 응답 필드 같음
  • 응답 access_token Redis 30초 캐시 (60초 만료보다 짧게)
• fetchPayoutAccountVerification({ bankCode, accountNumber, accountHolderInfoType, accountHolderInfo }) — 명세 2. 계좌인증, 빌링키(billing_tran_id) 반환
• requestPayoutDeposit({ billingTranId, tranAmt }) — 명세 3. 이체 대기 요청, group_key 반환
• executePayout({ groupKey, billingTranId, executeType: 'NOW' }) — 명세 4. 이체 실행
• redactor 적용 (billing_tran_id, access_token, api_tran_id 등)

빌링키 발급 통합

• 현재 verify-account 흐름이 실명인증만 호출 — 정산지급대행 계좌인증과 통합 검토
  • 옵션 A: verify-account 통합 (한 번에 빌링키까지 발급) — 인증 흐름 단순화
  • 옵션 B: 별도 endpoint (POST /settlements/issue-billing-key) — 분리 유지
• SettlementAccount.billing_tran_id에 저장 + 응답 마스킹

Webhook 수신

• POST /api/payouts/webhook 신규 (Payple 이체 결과)
• IP allowlist + (가능하면) 서명 검증
• SettlementPayout.status 업데이트, api_tran_id 저장
• 멱등성 (같은 webhook 중복 수신 안전)

정산 사이클 cron

• src/settlements/jobs/settlement-payout.job.ts 신규
• cron 표현식 (월간 / 주간 결정 후)
• Redis 분산 락
• 판매자별 미정산 금액 계산 + 환불 차감
• 빌링키 보유 + 최소 금액 충족 시 Payple 호출
• 결과를 SettlementPayout row로 기록

환수 회계 (환불 차감)

• 환불 발생 시 next-cycle 미지급 잔액에 자동 차감
• 잔액 음수 시 정책 (이월 / 청구 / 무시)에 따라 처리
• 통계 표시: 다음 정산 예정 금액 = net ([FEAT] 정산 통계에서 환불(Refunded) 거래 분리 표시 (#485 follow-up) #488 기반)

알림 / 리포트

• 정산 완료 / 실패 / 환수 차감 알림 (선택, 별도 이슈로 분리 가능)

환경변수

• PAYPLE_PAYOUT_AUTH_PATH (필요 시)
• PAYPLE_PAYOUT_WEBHOOK_URL (등록용)
• PAYPLE_PAYOUT_MIN_AMOUNT (최소 정산 금액)
• PAYPLE_PAYOUT_CYCLE_CRON (사이클 cron 표현식)

검증

• pnpm build / pnpm tsc --noEmit
• sandbox e2e: 빌링키 발급 → 이체 대기 → 실행 → Webhook 수신
• 환불 차감 동작 (환불 후 다음 사이클에서 정산금 차감 검증)
• 잔액 음수 정책 동작

✨ 별도 이슈로 분리 가능 (작업 분할)

범위가 크므로 단계별로 분리:

1. 빌링키 발급 인프라 (verify 통합 + Prisma)
2. Payple 지급이체 유틸 (utils/payple-payout.ts)
3. Webhook 수신 (/payouts/webhook + 멱등성)
4. 정산 사이클 cron (자동 지급 + 환불 차감)

각 단계별로 PR 분할 권장.

✨ 기타 / 질문

• Payple 정산지급대행과 결제용(cpay) 계약/키가 동일한지 확인 — 같으면 기존 PAYPLE_CST_ID/CUST_KEY 재사용. 별도면 신규 env
• 빌링키 만료/재발급 정책 확인 (장기 미사용 시 만료?)
• Webhook URL은 운영 환경에서만 등록 — sandbox/dev에는 어떻게 처리?
• 관련: [FEAT] 환불 - 7일 이내 미열람 자동 환불 흐름 (CANCEL) 및 Refund 모델 구현 #485, [FEAT] 환불 - 7일 이내 미열람 자동 환불 흐름 및 Refund 모델 (#485) #486, [FEAT] 정산 통계에서 환불(Refunded) 거래 분리 표시 (#485 follow-up) #488

[minij02]

📌 정산 정책 확정 사항 (기획 안내)

1. 정산 금액 = 수수료 + VAT 공제 후
2. 정산일 = 매월 15일, 직전 한 달 수익 정산
3. 최소 정산 금액 = 10,000원, 미달 시 다음 달 이월
4. VAT = 수수료의 10% 공제 (수수료 별도)

→ 이슈 본문의 결정 사항 1, 2, 3은 위로 확정:

• 정산 사이클: 월간, 매월 15일 KST
• 최소 정산: 10,000원
• 잔액 음수: 이월 (안내 사항의 "미달성 시 다음달로 이월"과 일관)

⚠️ 코드 갭 발견 — 별도 항목 추가

현재 결제 시점 fee 계산:

• src/purchases/services/purchase.complete.service.ts:46-47, src/purchases/services/purchase.webhook.service.ts:58-59
• FEE_RATE = 0.1 하드코딩
• fee = Math.floor(serverPrice * 0.1) — VAT 별도 공제 없음
• Settlement.amount = serverPrice - fee

명세는 "수수료 10% + VAT(= 수수료의 10%)" → 통합 공제율 11% 필요. 예: 판매가 10,000원이면

• 수수료 = 1,000원
• VAT = 100원
• 정산금 = 8,900원 (현재 코드는 9,000원으로 100원 더 지급됨)

본 이슈에 추가할 작업

• FEE_RATE와 VAT_RATE 상수 분리 (또는 TOTAL_DEDUCT_RATE = 0.11)
• Settlement row 생성 시 fee 컬럼에 (수수료 + VAT) 합계 저장하거나, 또는 fee / vat 컬럼 분리
• 옵션 A: Settlement.fee만 (값 = 수수료+VAT, 단순)
• 옵션 B: Settlement.fee + 신규 Settlement.vat 컬럼 (회계 명세 별도, 마이그레이션 필요)
• purchase.complete / purchase.webhook 양쪽 fee 계산 통일
• 기존 Settlement row의 fee 값 정정 정책 결정 (과거 데이터 그대로 / 일괄 갱신)

결정 필요

• 수수료 표시 분리 (옵션 A vs B) — 회계 리포트에서 VAT 분리 표시 필요한지에 따라 결정
• 기존 Settlement 정정 여부 — 0.1로 잘못 계산된 과거 거래를 0.11로 정정할지

여전히 미결정 (이슈 본문에 명시)

• 빌링키 발급 시점 (verify-account 통합 vs 별도 endpoint)
• Webhook 인증 방식 (Payple IP allowlist 보유 여부)