환불 처리¶

이 페이지에서 찾을 수 있는 것

환불 처리 / 부분 환불 / 전액 환불 / PG 취소 / 카드 취소 / 현금 환불 / 환불 목록 / 결제 취소 / 당일 취소 / 상계 처리

이미 결제된 진료비를 부분 또는 전액 환불하는 흐름입니다. 카드 결제는 PAY-STORY PG 자동 취소 + DB 정정, 현금/계좌이체는 수동 환불 + DB 정정으로 처리됩니다. 환불 후 차트의 paid_amount와 reservation status가 자동으로 재정렬됩니다.

환불 진입 경로 — 3가지¶

경로	사용 시점
수납 팝업 > 수납목록 탭 → 환불할 결제 항목 클릭 → "환불" 버튼	가장 일반적, 환자 차트에서 진입
매출/결산 > 환불 목록 (`RefundListPage`)	기간별 환불 이력 조회 + 환불 정정
환자 검색 > 환자 클릭 > 수납/미수	환자 단위로 진입

자주 쓰는 동작¶

시나리오 1 — 부분 환불 (카드 결제 일부)¶

100만원 카드 결제 중 30만원 환불

환자 차트 → 수납 팝업 → 수납목록 탭
100만원 카드 결제 항목에서 "환불" 버튼 클릭
환불 모달 열림
환불 금액 = 300,000원 입력
환불 사유 메모 입력 (예: "환자 요청 부분 환불")
확인 버튼
시스템 자동 처리:
- PAY-STORY PG 자동 취소 API 호출 (카드사 취소 승인)
- payments INSERT (is_refund=1, refund_amount=300,000)
- 원래 결제 status='refunded', refund_amount 업데이트
- progress_notes.paid_amount: 1,000,000 → 700,000
- reservation status 자동 재평가 (미수 발생 시 수납대기로 전환)

시나리오 2 — 전액 환불¶

잘못 결제한 100만원 전체 환불

위와 동일하게 진입
환불 금액 = 1,000,000원 (전액)
환불 사유 입력
확인
결과:
- PG 카드 취소 + DB 정리
- paid_amount = 0
- reservation status = "수납대기" (청구액은 그대로, 미수 100만원)

시나리오 3 — 현금/계좌이체 환불¶

현금 50만원 환불

차트 → 수납 팝업 → 수납목록 탭
현금 결제 항목 → "환불" 버튼
환불 금액 = 500,000원, 환불 수단 = "현금"
메모: "현금 환불 완료" 또는 환불 영수증 번호
확인 → DB만 정정 (현금은 직원이 환자에게 직접 지급)

시나리오 4 — PG 자동 취소 (카드 결제)¶

PG 카드 결제 자동 취소 흐름

카드 결제 환불 시 시스템이 자동으로:

pg_tid 확인 (PG 거래 식별자)
PAY-STORY 취소 API 호출 (/api/pg/cancel)
PG 응답 확인:
- 2001 (취소 성공) 또는 2013 (이미 취소됨) → DB 정정 진행
- 그 외 → 에러 메시지 표시, DB 변경 안 함
카드사 승인 → 환자 카드사로 환불 금액 회수 (1~3 영업일 소요)

→ PG 결제 환불은 DB뿐 아니라 카드사도 자동 취소.

시나리오 5 — 당일 결제 당일 취소 (상계)¶

오늘 결제하고 오늘 환불

매출 통계상 상계 처리 적용:

original.payment_date == refund.payment_date인 경우
일일결산에서 매출/환불 모두 0으로 표시 (상계)
매출 부풀림 방지

→ 다른 날짜에 환불된 경우는 매출-환불 별도 표시.

환불 목록 페이지 (`RefundListPage`)¶

매출/결산 메뉴의 환불 목록 페이지에서 기간별 환불 이력 조회.

컬럼	의미
환불일	refund_date
환자명 / 차트번호
원래 결제일	원결제 payment_date
결제 방법	카드/현금 등
원금액	원래 결제액
환불액	refund_amount
환불 사유	refund_reason
처리자	created_by

→ 기간 필터로 한 달치 환불 이력 한꺼번에 조회 가능.

자동 처리 로직¶

환불 처리 시 백엔드에서 자동 수행:

새 환불 레코드 생성 (payments INSERT, is_refund=1)
원래 결제 status='refunded'로 변경 (refund_amount, refund_date 기록)
progress_notes.paid_amount 자동 차감
payments.unpaid_amount/is_unpaid 재계산 (미수 잔액 갱신)
patient_reservations status 자동 재평가:
환불로 미수 발생 → 수납완료 → 수납대기로 전환
PG 결제였으면 PAY-STORY 취소 API 자동 호출

→ 직원은 환불 금액만 입력하면 나머지는 자동 정리.

권한별 차이¶

기능	권한
환불 처리 (전체/부분)	🟢 모든 직원
PG 카드 자동 취소	🟢 모든 직원 (시스템 자동)
환불 사유 메모 입력	🟢 모든 직원
환불 목록 조회	🟢 모든 직원
환불 레코드 삭제	🔴 Level 1~2 관리자
환불 금액 정정 (잘못 입력)	🟡 환불 후엔 직접 정정 어려움 → #dev 문의

자동 검증 (정합성)¶

환불 관련 정합성 봇 알림:

검사 번호	내용	처리
5	초과 결제 (paid_amount > total_amount)	환불 처리로 보정
10	환불 상태/금액 불일치 (status='refunded'인데 refund_amount=0)	🔴 #dev 문의 (이중환불 위험)

→ 정합성 점검 처리 #issue-5 · #issue-10

자주 발생하는 문제 / FAQ¶

Q1. 카드 결제 환불 시 카드사 승인이 안 났어요. A. PG 응답 확인: - 2001/2013: 취소 성공 - 그 외: 에러 메시지 표시. DB는 변경 안 됨.

PG 시스템 일시 장애일 수 있으니 잠시 후 재시도하거나 #dev 문의.

Q2. 현금 환불을 입력했는데 환자에게 현금을 안 줬어요. A. 시스템은 DB만 정정합니다. 실제 현금은 직원이 환자에게 직접 지급해야 합니다. 환불 영수증 발급 후 현금 인도.

Q3. 환불 금액을 잘못 입력했어요. A. 환불 후 직접 정정은 어렵습니다. 다음 중 선택: - 추가 환불 등록 (부족분 환불) - 추가 결제 등록 (과다 환불 보정) - #dev 문의

Q4. 같은 결제에 환불이 두 번 들어갔어요. A. 정합성 봇 10번 "환불 상태/금액 불일치"에 잡힐 수 있습니다. 한 번만 환불 처리하시고, 잘못된 환불은 #dev 문의로 정리.

Q5. 환불 후에도 paid_amount가 그대로예요. A. 새로고침 후에도 그대로면 시스템 결함. #dev 문의. 정상이면 paid_amount가 환불액만큼 자동 차감되어야 합니다.

Q6. 환불 사유 메모를 안 적었어요. A. 메모는 필수 아니지만 운영상 권장. 후속 추적을 위해 환불 영수증 번호, 사유 등 기록 권장.

Q7. 당일 환불은 매출에 어떻게 잡히나요? A. 상계 처리 — 매출과 환불 모두 0으로 표시되어 일일결산이 깔끔. 다른 날짜 환불은 별도 표시.

Q8. 선납권 결제를 환불하고 싶어요. A. 선납권으로 차감된 진료비는 패키지/선납권 페이지의 "사용 이력 취소" 흐름으로 처리 (회차/잔액 복원). 일반 환불 흐름과 다릅니다.

Q9. PG 결제 취소 결과는 어떻게 확인하나요? A. 환불 후 payments.pg_tid + 환불 레코드 자동 생성. PG 어드민 사이트에서 동일 거래 ID로 취소 확인 가능 (PAY-STORY).

Q10. 환불 후 현금영수증/카드매출전표는 어떻게 처리되나요? A. PG 카드 환불은 자동으로 카드매출전표 취소됨. 현금영수증은 별도 시스템(국세청)에서 취소 신고 필요.