NestPay 선불전자지급수단 · 회원앱 · 매장앱 · 관리자 · API · DB 5계층
본 문서는 (주)페이네스트가 개발하는 NestPay(선불카드형 지갑)의 기능·화면 요구사항을 실제 산출물(프로토타입·API 스펙·DB 표준 SQL)을 근거로 정리한 확정 기준입니다. 모든 수치는 실제 코드/파일에서 추출했으며, 계약 전 스텁(대역) 상태인 외부연동은 별도 표기했습니다.
구현상태 범례: 구현완료 서버 로직·DB 구현됨 · 스텁 외부기관 연동 전 개발용 대역(계약 후 실연동 교체) · 예정 계획됨(미구현)
NestPay 는 회원이 본인 명의 계좌에서 무통장(가상계좌/입금자 코드) 방식으로 충전한 금액을 선불전자지급수단(포인트)으로 보관하고, 앱 카드(가상 카드번호)로 매장 QR 결제·회원 간 선물·본인 계좌 출금에 사용하는 선불카드형 지갑입니다. 실물 카드는 발행하지 않고 앱 내 가상 카드로 동작합니다.
| 계층 | 대상 | 기술 스택 / 원천 | 비고 |
|---|---|---|---|
| 회원앱 | 일반 이용자 | Flutter(user_app) · Material 3 · 퍼플 #5613CC | iOS/Android 단일 UI/UX 통일 |
| 매장앱 | 가맹점(사업자) | Flutter(store_app) · 공유패키지 nestpay_shared | QR 결제 수신·정산 |
| 관리자 | 사내 운영자 | VanillaJS SPA(apps/admin) | 사내 IP + OTP, 관리자 전원 동등 |
| API 서버 | — | Spring Boot 3 · MyBatis · Flyway · Java 21 | 2대 무상태(L4 뒤), 공유 DB |
| DB | — | MariaDB (발주사 서버 10.3 기준) | 복식 원장(ledger)·로트(lot) 기반 |
다음 4종은 실제 외부기관 계약 전이라 개발용 스텁(대역)으로 동작합니다. 서버 기동 시 StubGuard 가 운영 환경(app.env=sandbox/live)에서 스텁이 남아 있으면 예외를 던져 기동을 차단합니다(무검증 오픈 방지).
| 항목 | 스텁 구현체 | 계약 후 실연동 대상 |
|---|---|---|
| 본인인증(실명·생년월일·전화) | StubIdentityVerifier | 본인확인기관(예: PASS/NICE 등) |
| 은행 계좌 실명조회 | StubBankVerifier | 실명조회 대행/펌뱅킹 |
| 1원 인증(입금자명 코드) | StubBankVerifier | 펌뱅킹 출금이체 |
| 출금·정산·반환 실제 이체 | WithdrawWorker(항상 성공 처리) | 펌뱅킹(FIRMBANK) 출금이체·대사 |
※ 위 스텁은 서버 내부 로직(대장·원장·상태전이)은 완성되어 있으며, 외부기관 호출부만 대역입니다. 입금통지 수신 웹훅(/webhooks/bank/deposit-notice)은 구현되어 있으나, 통지를 밀어주는 은행 SMS/펌뱅킹 게이트웨이는 외부(별도 수집 시스템) 영역입니다.
API 경로는 실행 중 서버의 OpenAPI 스펙에서 추출(코드와 100% 일치). 그룹별 엔드포인트 수 — 회원앱 64 · 매장앱 22 · 관리자 134 · PG 오픈API 8 · 인프라 1 · 웹훅 1 = 230.
| 기능 | 세부 | 대표 API 경로 | 상태 |
|---|---|---|---|
| 가입·인증 | 아이디 중복확인 / 가입자격(1인1활성계정·재가입대기) | GET /app/auth/login-id/availability, POST /app/auth/signup/eligibility | 구현완료 |
| 본인인증(신원 토큰 발급) / 사전생성 회원 최초 인증 | POST /app/auth/identity/verify, POST /app/me/verify-identity-complete | 스텁 | |
| 가입 완료(즉시 로그인) / 아이디·비밀번호 로그인 | POST /app/users, POST /app/auth/login | 구현완료 | |
| PIN 간편 로그인 / 패스키 로그인(시작·마침) | POST /app/auth/pin-login, POST /app/auth/passkey/login/start·finish | 구현완료 | |
| 계좌 등록 | 계좌 실명조회(본인 명의 확인) | POST /app/me/bank-accounts/verify-holder | 스텁 |
| 1원 보내기 → 코드 확인 → 계좌 등록(가입 3요건 완료) / 변경 이력 | POST /app/me/bank-accounts/one-won/send·confirm, GET /app/me/bank-accounts/history | 스텁 | |
| 카드 발행·관리 | 카드 발급(수량 정책 검사·첫 카드 대표) / 발급 가능 여부 | POST /app/me/cards, GET /app/me/cards/quota | 구현완료 |
| 내 카드 목록 / 대표 카드 지정 / 민감정보 열람(PIN·패스키) | GET /app/me/cards, POST /app/me/cards/{id}/primary·reveal | 구현완료 | |
| 충전 | 충전 식별자(입금자 코드) 발급·조회 | GET /app/me/deposit-identifier | 구현완료 |
| 입금통지 수신·자동매칭·충전 반영(멱등) | POST /webhooks/bank/deposit-notice | 구현완료 (통지 게이트웨이는 외부) | |
| 결제 | QR 확인(매장·금액 표시) / 결제 실행(PIN 인증표 필수·무상 우선) | POST /app/me/payments/qr/verify, POST /app/me/payments | 구현완료 |
| 결제 전액 취소(기한 내·본인 결제만) | POST /app/me/payments/{txnId}/cancel | 구현완료 | |
| 출금·환급 | 출금 신청(선차감·유상 포인트만·PIN 인증표) / 신청 화면 정보 | POST /app/me/withdrawals, GET /app/me/withdrawals/info | 구현완료 |
| 출금 실제 이체 실행(예정 시각 지난 HOLD 처리) | WithdrawWorker(배치) | 스텁 (펌뱅킹) | |
| 선물 | 바로 선물(전화/카드번호·QR·PIN 인증표) / 받는 사람 확인 | POST /app/me/gifts, POST /app/me/gifts/recipient·recipient/by-card | 구현완료 |
| 링크 선물 만들기(24h) / 받기 / 내 링크 목록 | POST /app/me/gifts/link·claim, GET /app/me/gifts/links | 구현완료 | |
| 링크 선물 회수(수령 전만 — 지갑 복원) | POST /app/me/gifts/links/{id}/cancel | 구현완료 | |
| 마이페이지 | 내 상태 / 본인정보 / 월 명세서 / 거래 내역 | GET /app/me, /app/me/profile, /app/me/statements, /app/me/transactions | 구현완료 |
| PIN 등록·변경·검증·상태 / 비밀번호 변경 / 패스키·기기 관리 / 거래 인증(패스키) | /app/me/pin(·/verify), /app/me/password, /app/me/passkeys/* | 구현완료 | |
| 프로필 사진 / 알림함(읽음) / 1:1 문의 / 회원 탈퇴 신청 | /app/me/avatar, /app/me/notifications/*, /app/me/inquiries, /app/me/closure | 구현완료 | |
| 콘텐츠 | 배너·공지·이벤트·FAQ·약관(시행본) / 앱 부팅 게이트 | /app/content/*, GET /app/gate | 구현완료 |
| 기능 | 세부 | 대표 API 경로 | 상태 |
|---|---|---|---|
| 입점·승인 | 입점 신청(심사중 접수) / 보완 완료 재제출 / 요구 서류 제출 | POST /store/apply·resubmit, POST /store/documents/{id}/file | 구현완료 |
| 매장 로그인 / 내 매장 정보(심사 상태·보완 사유) / 비밀번호 변경 | POST /store/auth/login·password, GET /store/me | 구현완료 | |
| QR 결제(3종) | QR 만들기(스티커 고정 / 금액지정 5분 1회용) / 목록 / 무효화(revoke) | POST /store/qrs, GET /store/qrs, POST /store/qrs/{id}/revoke | 구현완료 |
| PG 연동 | PG 연동 신청(매장코드·비밀키 1회 발급) / 현황 / 웹훅 주소 등록(서명키) | POST /store/pg/apply·webhook, GET /store/pg | 구현완료 |
| 화이트IP 신청(관리자 승인 후 open API 허용) | POST /store/pg/ips | 구현완료 | |
| 정산통장 | 정산통장 실명조회 → 1원 인증 → 승인대기 등록 / 현황 | POST /store/settle-account/verify-holder·one-won/send·confirm | 스텁 |
| 정산 출금 신청(선차감·멱등키 중복차단) / 신청 정보 | POST /store/settlements, GET /store/settlements/info | 구현완료 (이체는 펌뱅킹 스텁) | |
| 매출·정산 조회 | 매출 요약(오늘·이번달·정산 예정 잔액) / 거래 내역(결제·취소·정산 지급) | GET /store/summary, GET /store/transactions | 구현완료 |
| 영역 | 세부 기능 | 대표 API 경로 | 상태 |
|---|---|---|---|
| 회원 관리 | 목록·상세·등록(사전생성 PENDING)·정지/해제·비번초기화 / 인증수단(PIN 해제·삭제·패스키 삭제) / 계좌 삭제·이력 / 거래내역 | /admin/members, /admin/members/{id}/* | 구현완료 |
| 카드 관리 | 카드 목록(유상/무상 구분) / 전체번호·CVC 단건 열람(사유 필수·열람 기록) | /admin/cards, /admin/cards/{id}/reveal | 구현완료 |
| 매장 관리 | 목록·상세·등록 / 승인·반려·보완요청·정지/해제 / 서류 요구·업로드 / 비번초기화 | /admin/merchants, /admin/merchants/{id}/approve·reject·supplement·suspend | 구현완료 |
| PG 관리 | PG 신청 목록 / 결제요청(주문) 목록 / 연동 승인·반려·라이브 전환 / 화이트IP 승인·반려 | /admin/merchants/pg-applications·pg-orders, /admin/merchants/{id}/pg/approve·go-live | 구현완료 |
| 거래 관리 | 거래 목록(원장 조회 전용) / 미매칭 입금 수동매칭·반환 / 입금통장 등록·노출 / 선물 내역 | /admin/transactions, /admin/unmatched-deposits/{id}/match·return, /admin/deposit-accounts | 구현완료 (반환 이체는 펌뱅킹 스텁) |
| 정산 관리 | 월 정산서 목록 / 월 마감(재계산·멱등) / 정산통장 승인 대기·승인·반려 | /admin/settlements(·/close), /admin/merchants/settle-accounts/* | 구현완료 / 자동승인 예정 |
| 탈퇴 관리 | 탈퇴 신청 목록 / 일괄 승인(탈퇴·카드정지·포인트 소멸) / 일괄 반려 | /admin/closures, /admin/closures/approve·reject | 구현완료 |
| FDS·위험 | 경보 큐·처리 / 룰 8종 조회·수정 / 수동 탐지 실행 / 이용제한(Rate limit) 규칙 | /admin/fds/alerts·rules·scan, /admin/rate-limits | 구현완료 |
| 콘텐츠 | 공지·이벤트·배너·FAQ 관리 / 이벤트 이미지 / 약관·방침 버전 등록·시행 / 1:1 문의 답변 / 파일·이미지 대장 | /admin/content/*, /admin/policy-docs/*, /admin/inquiries, /admin/files | 구현완료 |
| 알림·푸시 | 푸시 발송(전체/개별·야간 광고 보류) / 발송 이력 / FCM 설정·키 업로드 / 이벤트별 알림 설정 | /admin/push/send·campaigns·settings, /admin/notification-settings | 구현완료 |
| 정책 | 수수료·한도·취소기간·포인트 유효기간·출금정산·카드수량·전역설정·은행 점검시간 (관리자 전원 동등) | /admin/policies/* | 구현완료 |
| 앱 게이트 | 점검 모드 / 강제업데이트 최소버전(배포 파이프라인 연동) / 스토어 URL | /admin/app-gate/maintenance·min-version·store-url | 구현완료 |
| 관리자 관리 | 관리자 계정 등록·수정·삭제·비번/OTP 초기화 / 허용 IP 규칙 / 감사 기록 / 로그인(2단계 OTP) | /admin/admins, /admin/allowed-ips, /admin/audits, /admin/auth/otp/* | 구현완료 |
| 대시보드 | 요약 숫자 / 운영 대시보드(오늘 흐름·처리 대기 큐·최근 24h 오류) | /admin/stats(·/ops) | 구현완료 |
HMAC 서명 검증 + 매장 승인 화이트IP 로 보호되는 외부 공개 API. 8종.
| 기능 | API 경로 | 상태 |
|---|---|---|
| 결제 주문 생성(QR·딥링크 반환) / 조회 / 취소·환불(전액) | POST /pg/payments, GET /pg/payments/{id}, POST /pg/payments/{id}/cancel | 구현완료 |
| 결제 내역 / 잔액·요약 / 정산 요청·내역 / 연동 시험(ping) | GET /pg/payments·balance·settlements, POST /pg/settlements·ping | 구현완료 |
앱 프로토타입(prototype.html)의 SCREENS 객체를 파싱한 결과 총 44화면(회원앱 33 · 매장앱 11)이며, 관리자는 별도 웹콘솔(SPA)로 30개 메뉴 + 상세 3 + 로그인으로 구성됩니다. 프로토타입에는 관리자 화면이 포함되지 않습니다(회원·매장 전용).
| 구분 | 화면명 | 용도 · 주요 요소 |
|---|---|---|
| 온보딩·인증 (9) | 웰컴 | 진입 — 회원가입/로그인 선택 |
| 로그인 | 아이디·비번 / PIN 간편 / 패스키 로그인 | |
| 가입① 본인인증 | 이름·생년월일·휴대폰·성별 입력 후 본인인증 | |
| 가입② 아이디 만들기 | 아이디·비밀번호·혜택알림 동의 | |
| 가입③ 계좌 등록 | 실명확인 → 1원인증 → 코드확인 3단계 | |
| KYC(사전생성) | 관리자 사전등록 계정의 최초 본인인증 | |
| PIN 등록/변경 | 6자리 PIN 입력(도트+키패드) | |
| 비밀번호 변경 | 로그인 비밀번호(PIN과 별도) 변경 | |
| 기기·패스키 관리 | 패스키 등록·등록 기기 목록·삭제 | |
| 메인 탭 (5, 하단네비) | 홈 | 카드 캐러셀·충전/출금/선물/결제 액션·최근 거래·이벤트 |
| 명세서 | 월 순변동·들어온 돈/나간 돈·거래 목록 | |
| 이벤트 | 이벤트 배너·목록 | |
| 이용내역 | 전체/충전/결제/출금/선물 필터·거래 목록 | |
| 마이페이지 | 총 보유금액·내 자산·보안/인증·고객센터 진입 | |
| 카드 액션 (9, 바텀시트) | 충전(입금폴링) | 충전 계좌·입금자 코드 안내·입금 확인 |
| 충전 완료 | 충전 금액·충전 후 잔액 | |
| 출금·환급 | 인증 계좌·출금 금액·예정 시각(유상만) | |
| 선물 보내기 | 전화번호/카드·QR/링크 · 금액·메시지 | |
| 보낸 선물(회수) | 미수령·수령완료 목록·회수 | |
| QR 결제(스캔) | 매장 QR 스캔 → 자동 다음 단계 | |
| 결제 인증(PIN) | 매장·금액 확인 후 PIN/패스키 인증 | |
| 결제 완료 | 매장·금액·결제 후 잔액 | |
| 카드 발급 | 디자인(8종)·색상 선택 후 발급 | |
| 마이페이지 하위 (5) | 내 카드 | 카드 목록·대표 카드 지정 |
| 연결계좌 | 인증 계좌(1개)·변경 이력 | |
| 계좌 변경(24h) | 본인 명의 계좌 변경(변경 후 24h 출금 제한) | |
| 본인정보 | 실명·생년월일·성별·전화·가입일(열람) | |
| 회원 탈퇴 | 포인트 소멸 안내·사유·동의·신청 | |
| 콘텐츠·고객센터 (5) | 공지사항 | 공지 목록 |
| FAQ | 자주 묻는 질문 | |
| 1:1 문의 | 문의·답변 목록·문의하기 | |
| 약관·개인정보 | 이용약관/개인정보처리방침(시행본) | |
| 알림함 | 충전·선물 등 알림 목록 |
| 구분 | 화면명 | 용도 · 주요 요소 |
|---|---|---|
| 온보딩 (3) | 매장 웰컴 | 입점 신청/로그인 선택 |
| 매장 로그인 | 아이디·비밀번호 | |
| 입점 신청 | 사업자번호·상호·대표자·개인/법인·계정 생성 | |
| 메인 탭 (5, 하단네비) | 매장 홈 | 오늘 매출·결제/취소/수수료·정산 예정 잔액·최근 결제 |
| 매출 | 오늘/이번달·건수·취소·수수료·실수령 예상 | |
| QR 생성 | 스티커용 고정 / 1회용 금액지정 | |
| 정산 | 정산 가능 잔액·계좌·신청·지급 내역 | |
| 매장 마이페이지 | 가입정보·계정관리·PG 연동·약관 | |
| 정산통장·PG·계정 (3) | 정산통장 인증 | 실명확인·1원인증(관리자 승인 후 사용) |
| PG 연동 관리 | 매장코드·연동 단계·웹훅·화이트IP 신청 | |
| 매장 비번 변경 | 현재/새 비밀번호 |
사이드바 그룹 기준(apps/admin/js/main.js). 관리자 등급 구분 없이 전원 동등 접근.
| 메뉴 그룹 | 화면(메뉴) |
|---|---|
| 현황 | 대시보드 |
| 고객 | 회원 관리 · 카드 관리 · 매장 관리 · PG 신청 · PG 결제요청 · 탈퇴 신청 |
| 거래 | 거래 관리 · 미매칭 입금 · 입금통장 · 선물 내역 · 정산 조회 · 정산통장 승인 |
| 위험 관리 | FDS 경보 · FDS 룰 · 이용제한 |
| 콘텐츠·고객지원 | 공지사항 · 이벤트 · 배너 · FAQ · 1:1 문의 · 파일·이미지 · 약관·방침 · 푸시 발송 |
| 운영 | 정책 관리 · 알림 설정 · 푸시 설정 · 앱 게이트 |
| 관리자 관리 | 관리자 계정 · 감사 기록 |
| 상세/기타 | 회원 상세 · 매장 상세 · 문의 상세 · 로그인(2단계 OTP) |
HmacAuthFilter) + 매장 승인 화이트IP.UserAuthFilter), 매장 세션(StoreAuthFilter), 관리자 = 사내 IP 화이트리스트(IpWhitelistFilter) + OTP 2단계(AdminAuthFilter), 웹훅 = INTERNAL_API_KEY 상수시간 비교.StubGuard 가 운영 환경에서 외부연동 스텁 잔존 시 기동 예외(fail-fast).(:p IS NULL OR col=:p) 금지(파라미터 유무별 SQL 분기).SKIP LOCKED(10.6+) 미사용, 상태열 원자 클레임 + 고아 스위퍼로 대체.ix_txn_counterparty, ix_merchants_status, ix_lots_type_remaining).@Scheduled)는 claim_token/원자 가드로 2대 동시 실행 안전, 고아 스위퍼로 중단 건 회수.GET /health 는 L4 경로.GET /app/gate 로 점검 모드·최소버전·스토어 URL 판단. 최소버전 설정은 배포 파이프라인이 POST /admin/app-gate/min-version 호출(A방식).① 본인인증(신원 토큰) → ② 아이디·비밀번호 생성(즉시 로그인) → ③ 본인 명의 계좌 등록(실명조회 → 1원 보내기 → 입금자명 코드 확인) = 가입 3요건 완료 → 카드 발급(첫 카드 대표).
입금자 코드 확인 → 안내 계좌로 무통장 입금 → 은행/게이트웨이가 입금통지 웹훅 전송 → 자동 매칭·충전 반영(멱등). 주인 못 찾으면 미매칭 입금 → 관리자 수동 매칭 또는 반환.
NestPay 산출물 · (주)페이네스트 · 작성일 2026-07-27 · 실제 코드/DB 기준 · 외부연동(펌뱅킹·본인인증·은행 실명조회)은 계약 전 스텁 상태임을 명시