✣Toss Ops Showcase
Next.js 15 · Prisma · Neon · Toss Payments

결제 연동과 운영 어드민을 한 흐름으로 검증하는 시연 페이지

위시켓 제안 범위를 실제 동작하는 제품 화면으로 구성했습니다. 결제 상품, 결제위젯, 서버 승인, DB 로그 저장, 관리자 조회, 환불 증빙까지 하나의 포트폴리오 화면에서 빠르게 확인할 수 있습니다.

결제위젯 테스트관리자 화면

Payment Flow

상품 선택부터 승인 저장까지

Admin Ops

결제 조회, 영수증, 환불 증빙

Data Layer

Prisma ORM + Neon 로그

Auth Guard

NextAuth ADMIN Role 보호

Implementation Scope

요구사항을 화면, 서버, 데이터 흐름으로 나누어 구현했습니다

목업이지만 단순 소개 페이지가 아니라, 결제 요청과 취소 요청이 실제 API와 데이터베이스 로그까지 이어지도록 구성했습니다.

결제 진행 흐름

  1. 1상품 상세 또는 홈 주문서에서 결제 상품과 금액을 선택합니다.
  2. 2클라이언트는 Toss Payments V2 SDK로 결제위젯을 렌더링합니다.
  3. 3결제 요청 전 서버 API가 DB에 READY 주문 초안을 생성합니다.
  4. 4success URL에서 서버가 저장 금액과 URL 금액을 다시 비교합니다.
  5. 5서버가 Toss Confirm API를 호출하고 승인 결과와 이벤트 로그를 저장합니다.
  6. 6관리자 페이지에서 결제 상태, 매출전표, 최근 이벤트를 확인합니다.

환불 및 증빙 흐름

  1. 1관리자가 DONE 결제의 취소 모달을 엽니다.
  2. 2취소 사유와 선택적 부분 취소 금액을 입력합니다.
  3. 3Server Action이 Toss Cancel API를 호출합니다.
  4. 4응답의 cancels 배열 기준으로 누적 취소 금액을 계산합니다.
  5. 5DB 상태와 이벤트 로그를 갱신하고 어드민 테이블에 즉시 반영합니다.
  6. 6환불 증빙 모달에서 transactionKey, Trace ID, 취소 사유와 금액을 확인합니다.

Screen Evidence

README의 검증 화면을 배포 페이지에서 더 보기 좋게 재배치했습니다

GitHub README에는 WebP와 GIF로 가볍게 노출하고, Vercel 배포 화면에서는 WebM 영상과 주요 캡처를 섹션별로 확인할 수 있습니다.

상품형 결제 랜딩
상품형 결제 랜딩제안 범위를 상품 카드와 주문서 흐름으로 연결한 첫 화면입니다.
관리자 결제 대시보드
관리자 결제 대시보드승인, 취소, 합계, 영수증, 이벤트 상태를 한 화면에서 확인합니다.
결제 성공 결과
결제 성공 결과서버 승인 후 DONE 상태와 후속 액션을 노출합니다.
결제위젯 인증
결제위젯 인증Toss 결제위젯의 QR 및 간편결제 인증 화면입니다.
환불 처리 모달
환불 처리 모달취소 사유와 부분 취소 금액을 입력하는 관리자 액션입니다.
Toss API 로그
Toss API 로그Confirm과 Cancel 호출 결과를 개발자센터 로그로 검증했습니다.

Build Notes

제안서에서 설명해야 할 기술 포인트를 코드 단위로 정리했습니다

Next.js 15 App RouterReact 19TypeScriptTailwind CSS v4shadcn/uiPrisma ORMNeon PostgreSQLNextAuth CredentialsToss Payments V2 SDKToss Payments REST API
src/app/page.tsx상품형 결제 랜딩과 결제위젯 데모
src/app/products/[slug]/page.tsx상품 상세 및 상품별 주문서
src/components/payments/payment-widget-checkout.tsxToss 결제위젯 클라이언트 컴포넌트
src/app/payments/success/page.tsx결제 성공 후 서버 승인
src/app/admin/payments/page.tsx관리자 결제 관리 대시보드
src/components/admin/payment-evidence-dialog.tsx결제 및 환불 증빙 모달
src/lib/payments/toss.tsToss REST API 클라이언트
prisma/schema.prismaUser, Payment, PaymentEvent 스키마

관리자 접근 제어

NextAuth Credentials와 User.role 기반으로 ADMIN 권한만 결제 관리 화면에 접근하도록 보호했습니다.

환불 증빙 모달

취소 거래별 금액, 사유, 일시, transactionKey, Trace ID를 관리자 화면 안에서 확인할 수 있습니다.

운영 전환 체크

운영 DB 전환, Toss 키 교체, 관리자 계정 정책, 웹훅 동기화까지 README에 인수 항목으로 정리했습니다.