[WORKSOUT] 결제 (일반 회원)
화면 정보
섹션 제목: “화면 정보”| Screen ID | Screen Title | Screen Path |
|---|---|---|
| PAY-CHK-01 | 결제 (일반 회원) | /checkout |
로그인 회원의 일반 결제 화면(SH_131_Payment). 장바구니에서 선택한 상품으로 배송지·할인·결제 수단을 확정해 주문을 생성하고 결제를 실행한다. 소스: 결제 메인 마스터.md(베이스) + 결제·주문 프로세스.md(병합, 중복 흡수·상충은 미결 사항에 기록).
PDP 즉시구매 바텀시트(PAY-CHK-02)와는 별개 화면이다. 이 문서는 PAY-CHK-01만 다룬다.
화면 구성
섹션 제목: “화면 구성”헤더 및 주문 상품 섹션
섹션 제목: “헤더 및 주문 상품 섹션”| 항목 | 기준 |
|---|---|
| 헤더 제목 | “주문 정보” |
| 뒤로가기 | 장바구니 화면으로 이동 |
| 주문 상품 제목 | “주문 상품 (N개)” |
| 상품 정렬 | 장바구니 추가 최신순(최근 담은 상품이 상단) |
| 주문 상품 드롭다운 | 삭제됨 — 상품 목록은 항상 전체 펼침 상태로 노출 |
채택 기준: 결제·주문 프로세스.md는 “3개 이하 펼침 / 4개 이상 첫 상품만 노출 + 더보기” 규칙을 명시하나, 결제 메인 마스터.md(최종 수정 2025-08-21, 더 최신)는 “드롭다운 삭제됨”으로 서술한다. 본 문서는 결제 메인 마스터 기준을 채택한다. 상충 내용은 미결 사항 참고.
상품 카드 표시 항목: 썸네일 · 브랜드명 · 상품명 · 사이즈 · 수량 · 쿠폰 할인 정보 · 마일리지 할인 정보 · 가격
가격 표시 기준
| 상황 | 표시 방식 |
|---|---|
| 할인 미적용 | currentPrice |
| 세일 상품 | 원가 취소선 + 할인율 + 현재가 |
| 쿠폰/마일리지 적용 | 최대 할인가 기준 표시 |
배송 정보 섹션
섹션 제목: “배송 정보 섹션”| 항목 | 기준 |
|---|---|
| 주문자 이름 | user.name 자동 채움 |
| 주문자 전화번호 | user.phone 자동 채움 |
| 기본 배송지 | 가장 최근 주문 배송지 자동 선택 |
| 배송지 없을 때 | “새 배송지 추가” 버튼 + 빈 입력 상태 |
| 배송지 변경 | “배송지 변경” 텍스트 버튼 → Bottom Sheet |
| 배송 메모 | 선택 사항 |
배송지 API: GET /v1/users/addresses
할인 섹션
섹션 제목: “할인 섹션”| 항목 | 기준 |
|---|---|
| 쿠폰 | 드롭다운 선택 + 할인코드 입력, 팝업으로 목록 표시. 라플 상품 등 일부 상품은 적용 불가 |
| 마일리지 | 직접 입력, 전체 사용 버튼, 배송비 제외 금액 한도. 라플 상품 등 일부 상품은 사용 불가 |
| 예치금 | 직접 입력, 전체 사용 버튼, 총 결제 금액 한도 |
| 마일리지 + 예치금 동시 사용 | 먼저 적용한 항목 우선, 서버 응답 기준 동기화 |
| 10만원 기준 무료배송 | 마일리지 사용으로 기준 미달 시 배송비 재발생 가능 |
운영 주의: 금액 계산은 프론트 임의 계산이 아니라 백엔드 할인 계산 API 응답 우선으로 반영한다.
할인 계산 API: POST /v1/order/{orderNumber}/discount — 요청 필드: couponId, discountCode, usedMileage, usedMoney
현금영수증 섹션
섹션 제목: “현금영수증 섹션”| 항목 | 기준 |
|---|---|
| 노출 조건 | 예치금 1원 이상 입력 시 |
| 기본값 | 미선택 |
| 체크 시 노출 항목 | 개인소득공제용 / 사업자증빙용 선택 + 번호 입력 |
| 개인소득공제 | 휴대폰 번호 또는 현금영수증 카드 번호 |
| 사업자증빙 | 사업자등록번호 |
결제 정보 섹션
섹션 제목: “결제 정보 섹션”| 항목 | 기준 |
|---|---|
| 기본 결제 수단 | 간편결제 |
| 간편결제 미등록 | “간편결제 등록하고 1초만에 결제하세요.” 버튼 |
| 간편결제 등록 상태 | 카드사 로고 + 마스킹 번호 + 유효기간, 가로 스크롤 |
| 할부 | 카드 선택 시 드롭다운 (기본 일시불, 2~12개월) |
| 기타 결제 수단 | 신용카드 / 에스크로 계좌이체 / 카카오페이 / 네이버페이(Npay) / 토스페이 |
| 결제 수단 선택 | 한 번에 하나만 선택 가능 |
금액 정보 표시 항목: 상품 금액 · 상품 할인 · 쿠폰 할인 · 마일리지 할인 · 예치금 사용 · 배송비 · 총 결제 금액 · 멤버십 마일리지 적립 예상치
동의 체크박스 및 결제 버튼
섹션 제목: “동의 체크박스 및 결제 버튼”| 항목 | 기준 |
|---|---|
| 필수 동의 항목 | 주문 정보 동의 + 제3자 데이터 공유 동의 |
| 결제 버튼 활성 조건 | 배송지 입력 완료 + 결제 수단 선택 + 필수 동의 2종 체크 + (현금영수증 선택 시 번호 입력 완료) |
| 버튼 텍스트 | “총 결제 금액원 (상품 N개) 결제하기” |
결제 실행 플로우
섹션 제목: “결제 실행 플로우”| 단계 | 내용 |
|---|---|
| 1단계: 주문 생성 | POST /v1/order/port/payment/order/{orderNumber} |
| 2단계: 결제 모듈 | 주문 생성 성공 시 Portone / 간편결제 모듈 호출 |
| 3단계: 결제 확인 | POST /v1/orders/port/payment/confirm |
| 성공 시 | 결제 완료 화면 이동 |
| 실패 시 | 결제 실패 안내 + 재시도 유도 |
운영 주의: 주문 생성 API(
/v1/order)와 결제 확인 API(/v1/orders)는 단수/복수 경로가 다르다. 실제 연동 시 엔드포인트 최종 확인 필요.
예외 상황 처리
섹션 제목: “예외 상황 처리”- 결제 프로세스 중 오류 발생 시 오류 내용과 함께 재시도 안내 메시지 표시.
- 잔액 부족, 한도 초과 등의 경우 구체적인 사유와 함께 대체 결제 수단 안내 제공.
API 연동
섹션 제목: “API 연동”1. 배송지
섹션 제목: “1. 배송지”| 기능 | API |
|---|---|
| 배송지 목록 조회 | GET /v1/users/addresses |
| 배송지 추가 | PUT /v1/users/address |
| 배송지 수정 | PUT /v1/users/address/{addressId} |
2. 할인 계산
섹션 제목: “2. 할인 계산”| 기능 | API |
|---|---|
| 쿠폰 목록 조회 | GET /v1/coupon/user |
| 할인 재계산 | POST /v1/order/{orderNumber}/discount |
할인 재계산 요청 필드: couponId, discountCode, usedMileage, usedMoney
3. 주문 생성
섹션 제목: “3. 주문 생성”엔드포인트: POST /v1/order/port/payment/order/{orderNumber}
| 필드 | 설명 |
|---|---|
customerName / customerPhone |
주문자 이름/전화번호 |
receiverName / receiverPhone |
수령인 이름/전화번호 |
receiverAddress / receiverDetailAddress / receiverPostcode |
배송지 주소 |
shippingRequest |
배송 요청사항 |
payMethod |
결제 수단 코드 (BRAND_PAY, CARD, KAKAOPAY 등 — 결제사 코드표 기준 확인 필요) |
usedCouponIds / usedCouponCode |
쿠폰 |
usedMileage |
마일리지 |
usedMoney |
예치금 |
isUsedCashReceipt / cashReceiptType / cashReceiptNumber |
현금영수증 |
userAddressId |
기존 배송지 ID |
newUserAddress |
신규 배송지 객체 |
4. 결제 확인
섹션 제목: “4. 결제 확인”엔드포인트: POST /v1/orders/port/payment/confirm
요청 필드: imp_uid, merchant_uid, utm_campaign, utm_content, utm_creative, utm_medium, utm_source, utm_term
에러 처리 요약
섹션 제목: “에러 처리 요약”| 증상 | 예상 원인 | 1차 조치 |
|---|---|---|
| 배송지 미노출 | GET /v1/users/addresses 응답 |
저장된 주소 1개 이상 확인 |
| 쿠폰 목록 미노출 | GET /v1/coupon/user 응답 |
보유 쿠폰 존재 여부 확인 |
| 할인 금액 미반영 | POST /v1/order/{orderNumber}/discount 응답 |
서버 계산 결과 동기화 확인 |
| 현금영수증 미노출 | 예치금 입력 금액 확인 | 1원 이상 입력 여부 |
| 결제 버튼 비활성 | 배송지/결제 수단/동의 상태 | 3종 모두 완료 여부 |
| 주문 생성 실패 | 요청 payload / 주문번호 확인 | API 정상 응답 확인 |
| 결제 확인 실패 | imp_uid / merchant_uid 전달 여부 |
누락 없이 전달 확인 |
| 간편결제 카드 미노출 | 결제 시스템 카드 목록 응답 | 등록 카드 1개 이상 확인 |
관련 QA 패턴
섹션 제목: “관련 QA 패턴”결제 도메인은 QA에서 가장 많이 버그가 몰리는 영역이다. PG 회귀 테스트, 에러코드별 안내 문구 확인, 쿠폰×적립금×예치금 조합 테스트, 재진입 시 배송지/결제수단 선택값 유지 여부를 체크할 것.
자세히: QA 체크리스트 §1 결제/PG
미결 사항
섹션 제목: “미결 사항”| 항목 | 내용 |
|---|---|
| 주문 상품 리스트 노출 방식 상충 | 결제·주문 프로세스.md는 “3개 이하 펼침 / 4개 이상 첫 상품만+더보기” 규칙 명시, 결제 메인 마스터.md는 “드롭다운 삭제됨”으로 서술 — 본 문서는 최신 문서(결제 메인 마스터)를 채택했으나 실제 구현 최종본 확인 필요 |
| 주문 생성/결제 확인 API 경로 | /v1/order (단수) vs /v1/orders (복수) 혼용 — 실제 연동 시 엔드포인트 확인 필요 |
payMethod 코드표 |
BRAND_PAY, CARD, KAKAOPAY 등 결제사 코드 전체 목록 확인 필요 |
변경 이력
섹션 제목: “변경 이력”| 버전 | 날짜 | 변경 내용 |
|---|---|---|
| v1.0 | 2026-07-30 | 최초 작성 (결제 메인 마스터.md + 결제·주문 프로세스.md 병합) |