[공통] 반품 신청

화면 정보

Screen ID	Screen Title	Screen Path
ORD-RTN-01	반품 신청	`/mypage/order/{orderNumber}/return`
ORD-RTN-02	반품 신청 완료	`/mypage/order/{orderNumber}/return/complete`

개요

주문 상세(ORD-DETAIL-01)에서 반품 신청 버튼 클릭 후 진입하는 반품 신청 및 완료 화면. 반품 배송비는 아임포트를 통해 결제 후 반품이 접수된다.

ORD-RTN-01 — 반품 신청

반품 신청 진입 조건 (주문 상세 기준)

조건	기준
상품 상태	`productStatus == DELIVERED` 또는 `RETURNED`
최종 처리 제외	`productStatus != CANCELED` AND `!= CONFIRMED`
중복 신청 방지	`latestRequest == null`

화면 구성

반품 신청 (ORD-RTN-01)
├── 헤더                    ← 뒤로가기 / "반품 신청"
├── 반품 사유 선택          ← 드롭다운 (기타 선택 시 입력 필드 추가 — 필수 입력)
├── 반품 비용 결제 수단     ← 신용카드 / 실시간 계좌이체
├── 반품 상품 정보
├── 환불 정보
└── 결제 후 반품 신청 버튼

반품 사유 선택

옵션	비고
상품 오배송	—
단순 변심	—
상품 불량	—
기타 사유	선택 시 텍스트 입력 필드 추가 노출, 필수 입력

사유 미선택 시 “결제 후 반품 신청” 버튼 비활성화
기타 사유 선택 후 텍스트 미입력 시 “반품 사유를 입력해주세요” 토스트

반품 비용 결제 수단

옵션
신용카드
실시간 계좌이체

결제 수단 미선택 시 “결제 후 반품 신청” 버튼 비활성화

환불 정보 표시 기준

항목	기준
반품 비용	`totalPrepayingAmount`
반송 비용	취소 완료 시 “취소완료” (빨간색/굵게) / 일반 시 `deliveryAmount`
교환 비용	`totalPrepayingAmount - deliveryAmount`
총 할인 금액	라플 유형 주문이면 숨김
총 환불 금액	`totalPaidProductAmount - willReturnMoney` (빨간색 표시)
반환 예치금	`willReturnMoney`
반환 적립금	`willReturnMileage`
환불일	현재일 기준 +7일 (YYYY.MM.DD)
환불 수단	`payMethod` 값에 따른 한국어 안내

“결제 후 반품 신청” 버튼 동작

반품 사유 + 결제 수단 선택 완료 시 활성화
클릭 → “정말 반품신청을 하시겠습니까?” 팝업
확인 → 반품 배송비 결제(아임포트) → 결제 성공 시 반품 신청 API 호출
완료 → 반품 신청 완료 화면으로 이동
실패 → 오류 메시지, 현재 화면 유지

ORD-RTN-02 — 반품 신청 완료

화면 구성

반품 신청 완료 (ORD-RTN-02)
├── 헤더                    ← "반품 신청 완료"
├── 완료 안내               ← "반품 신청이 완료되었습니다" + 처리 절차 안내
├── 수거지 정보
│   ├── 배송 정보 변경 버튼 ← Bottom Sheet 표시
│   └── 수거지 상세         ← 이름 / 연락처 / 주소 / 요청사항
└── 액션 버튼
    ├── 주문/배송 조회      ← 전체 주문 내역(ORD-LIST-01)으로 이동
    └── 계속 쇼핑           ← 메인으로 이동

배송 정보 변경 (Bottom Sheet)

항목	기준
진입 방법	“배송 정보 변경” 클릭 → 하단 슬라이드업
변경 가능 조건	수거 업체가 아직 방문하지 않은 상태
변경 불가 시	“수거지 변경이 불가능한 상태입니다” + CS 연락 안내
완료 시	“수거지 정보가 변경되었습니다” 토스트

화면 네비게이션 주의

반품 완료 화면에서 뒤로가기 불가 (반품이 이미 접수된 상태)
하드웨어 뒤로가기 버튼 비활성화 또는 메인으로 강제 이동

API 연동

1. 반품 사전 정보 조회

엔드포인트: POST /v1/orders/requests/{orderNumber}/pre-paid

{
  "customerName": "string",
  "customerPhone": "string",
  "orderProductIds": [0],
  "orderRequestType": "RETURN"
}

응답 필드	활용
`totalPrepayingAmount`	반품 비용
`deliveryAmount`	반송 비용
`willReturnMoney`	반환 예치금
`willReturnMileage`	반환 적립금
`totalPaidProductAmount`	총 환불 금액 계산 기준

2. 반품 배송비 결제

엔드포인트: POST /v1/orders/port/payment/confirm

아임포트 결제 모듈 연동
성공 시 반품 신청 API 호출

외부 결제 모듈: POST https://service.iamport.kr/events

3. 반품 신청 실행

엔드포인트: POST /v1/orders/port/payment/cancel/{orderNumber}

{
  "returnOrderProducts": [
    {
      "returnOrderProductId": 0,
      "returnReason": "상품 오배송"
    }
  ],
  "customerName": "string",
  "customerPhone": "string"
}

returnReason: 기타 사유 선택 시 입력 텍스트 사용
성공 → 반품 신청 완료 화면으로 이동

에러 처리 요약

증상	예상 원인	1차 조치
환불 정보 로드 실패	사전 정보 API 실패	API 응답 확인, 재시도 버튼 제공
결제 실패	카드 승인 실패 / 타임아웃	오류 메시지 + 결제 수단 재선택 유도
결제 후 반품 신청 실패	반품 API 오류	결제 성공 여부와 반품 API 응답 분리 확인
아임포트 연결 실패	외부 결제 모듈 오류	“결제 서비스에 연결할 수 없습니다” 안내
완료 화면에서 뒤로가기 됨	네비게이션 스택 처리 누락	완료 화면 진입 시 이전 스택 제거 확인
수거지 변경 실패	변경 API 오류 또는 수거 완료 상태	상태 확인 후 CS 안내

변경 이력

버전	날짜	변경 내용
v1.0	2026-07-06	최초 작성