인터페이스 정의서 (오류코드·외부연계)

문서 목적 — 본 문서는 NestPay API 서버(apps/api)가 대내외에 제공·소비하는 인터페이스의 규약을 정의한다. 크게 두 부분으로 구성한다.

• A. API 규약·오류코드 — 모든 응답의 공통 포맷, HTTP 상태코드 매핑, 오류 생성 규칙과 대표 메시지, 무상태 인증 토큰 체계, API 그룹과 문서 노출 위치, 이용제한(429) 동작
• B. 외부기관 연계 정의서 — 은행 펌뱅킹·본인인증·실명조회·1원인증·입금통지 웹훅·FCM 푸시·PG 오픈API 등 연동 지점 전수와 현재 구현/계약 상태, 실연동 전환 지점

상태 범례: 구현 코드 구현 완료 · 스텁 외부기관 계약 전 개발용 대역 · 부분 일부 구현·일부 연동 대기

응답 예시

// 성공
{ "success": true,  "data": { "cardId": 12, "balance": 30000 }, "error": null, "meta": null }

// 목록(meta 포함)
{ "success": true,  "data": [ ... ], "error": null, "meta": { "total": 137, "page": 1, "limit": 20 } }

// 실패
{ "success": false, "data": null, "error": "PIN 이 올바르지 않습니다.", "meta": null }

보안 문지기(필터) 단계의 401 처리 — 별도 경로

인증 문지기(HmacAuthFilter·UserAuthFilter·StoreAuthFilter·AdminAuthFilter·IpWhitelistFilter)는 컨트롤러 앞단에서 동작하므로 위 예외 처리기를 거치지 않는다. 대신 FilterResponses.reject(...)가 동일한 공통 포맷({success:false, error:"..."})으로 401을 직접 반환한다. 즉 인증 실패의 응답 모양은 필터 단계든 컨트롤러 단계든 일치한다.

토큰 구조

토큰 = base64url(payload) . hex( HMAC-SHA256(서버비밀키, base64url(payload)) )
payload = type | subjectId | expiresEpoch | extra

· 내용을 한 글자라도 고치면 도장(HMAC)이 안 맞아 즉시 무효
· 서버에 저장하지 않으므로 2대 어느 서버에서도 동일 검증(무상태)
· 검증 시 도장 대조는 MessageDigest.isEqual 로 타이밍 공격 방지
· 비밀키는 운영에서 환경변수 ADMIN_TOKEN_SECRET 로 주입(기본값 사용 시 부팅 차단 — B-3)

전달 방식: 세션 토큰(A/M/U)은 Authorization: Bearer <토큰> 헤더. PIN 거래표(P)·본인인증표(I)·1원인증표(W) 등은 각 API 요청 본문 필드로 전달.

pinPass(P) — 1회용 거래 인증 (설계 1.7)

간편 PIN(숫자 6자리, Argon2id 해시, 5회 오류 시 30분 잠금)을 맞히면 3분짜리 거래 인증표(P 토큰)를 발급한다. 결제·출금·선물·취소·카드열람 API는 이 표가 있어야만 실행되며(비밀번호 로그인만으로는 불가), 표의 도장(서명)은 NonceMapper.consume으로 단 한 번만 소진된다.

• 가로챈 표의 재사용(replay) → "이미 사용된 인증입니다." (401)
• 소진된 표의 서명값을 거래 멱등키로 승계 → 같은 인증 1건 = 거래 1건(이중결제·이중출금 원천 차단, A-2의 409와 이중 방어)

① 은행 펌뱅킹 실이체 (출금·정산) 스텁

목적 — 회원 출금과 매장 정산 시 등록 계좌로 실제 자금을 이체한다.

인터페이스 — 출금 워커(WithdrawWorker, 1분 주기)가 예정 시각이 지난 HOLD 건을 잡아 AppWithdrawService.executeOne에서 이체를 실행. 매장 정산(StoreSettleService·PG /pg/settlements)도 동일한 출금 실행 경로를 재사용한다.

현재 상태 — 펌뱅킹 계약 전이므로 이체는 스텁: HOLD→PENDING 클레임 후 항상 성공으로 처리하고 CONFIRMED로 확정. 은행 점검시간에는 BankMaintenanceGuard.ensureOpen이 신청을 차단.

전환 지점 — AppWithdrawService.executeOne 내 "펌뱅킹 이체 연동 지점" 주석 위치에서 실제 이체를 호출하고, 실패/UNKNOWN 처리와 리컨실러를 연결(8.5 실패 복원: 역분개 + 원 로트·만료일 승계는 이미 구현).

② 본인인증(인증사) 스텁

목적 — 회원 가입·재인증 시 실명·생년월일·전화·성별과 CI/DI(연계·중복가입 확인정보)를 인증사로부터 확보. "1인 1활성계정" 규칙의 기준값.

인터페이스 — IdentityVerifier.verify(name, birthDate, phone, gender) → IdentityResult(name, birthDate, phone, gender, ci, di). 성공 시 결과를 봉인한 본인인증표(I 토큰)를 발급해 가입에 사용.

현재 상태 — StubIdentityVerifier가 동작: 같은 입력은 항상 같은 CI/DI(실서비스 성질 모사), 이름이 "실패"로 시작하면 인증 실패(400) 반환. 임의 명의로 통과 가능하므로 운영 부적합.

전환 지점 — 인증사(PASS/NICE 등) SDK·API를 호출하는 클래스로 IdentityVerifier를 구현·교체(스텁 삭제). 호출 측 코드는 무변경(인터페이스 유지). NICE는 external_api_logs.provider에 예약됨.

③ 은행 계좌 실명조회 & ④ 1원(소액) 인증 스텁

목적 — 회원·매장이 등록하려는 계좌의 예금주명이 본인(인증 실명)과 일치하는지 확인(실명조회)하고, 통장에 찍히는 4자리 코드로 계좌 소유를 확인(1원인증)한다. 계좌 등록 3요건의 핵심.

인터페이스 — BankVerifier.verifyHolder(bankCode, accountNo, expectedName) → HolderResult(match, holderName) · BankVerifier.sendOneWon(bankCode, accountNo) → 4자리 코드. 1원인증은 W 토큰(verifyToken)에 계좌·코드 지문을 묶어 확인(코드 원문 미저장).

현재 상태 — StubBankVerifier: 계좌번호가 9로 끝나면 불일치("김타인") 반환(불일치 흐름 시험), 그 외 일치. 1원인증은 실입금 없이 코드만 생성(dev 모드에서만 debugCode로 응답에 노출, 운영에선 미노출).

전환 지점 — 펌뱅킹/오픈뱅킹 계약 확정 시 실연동 클래스로 BankVerifier를 교체(스텁과 맞교환). 호출 측 무변경.

⑤ 입금 통지 수신 웹훅 부분

목적 — 은행/PG(가상계좌·펌뱅킹) 또는 SMS 파서가 입금 사실을 서버에 통지 → 적립/미매칭 처리.

인터페이스 — POST /webhooks/bank/deposit-notice. 헤더 X-Internal-Key(환경변수 INTERNAL_API_KEY와 시간차 없는 비교로 검증). 본문: source(PGVACCT|FIRMBANK|SMS), amount, depositorName, identifierValue, bankTranRef, rawText(증거).

현재 상태 — 수신 문·내부 열쇠 인증·중복 재수신 안전(멱등)·워커 처리(DepositNoticeWorker, 10초 주기, 2대 중복 처리 방지)까지 구현 완료. 다만 은행/PG의 실제 서명 규격이 아니라 내부 키 방식이므로, 계약 확정 시 해당 규격으로 인증부만 교체 필요.

전환 지점 — BankWebhookController의 내부 키 검사(주석 "★펌뱅킹/PG 계약 확정 시 그쪽 규격(서명 방식)으로 교체")를 실제 서명 검증으로 교체.

⑥ FCM 폰 화면 푸시 부분

목적 — 알림함(inbox) 저장에 더해 실제 단말 화면 푸시 발송.

인터페이스(설정형) — 관리자가 AdminPushService를 통해 Firebase projectId 입력 + 서비스 계정 키(JSON) 업로드 + on/off 저장(설정값 PUSH_FCM_PROJECT_ID·PUSH_FCM_KEY_FILE_ID). 켜려면 키 파일 선행 필수. 단말 토큰은 push_tokens 테이블에 보관.

현재 상태 — 설정 UI·키 보관·알림함 적재·캠페인 발송 파이프라인(야간 광고 차단, 키셋 청크, 재시도 안전)은 구현. 단말로의 FCM 실발송은 미연동(푸시 키 발급 후 연동 예정).

전환 지점 — PushDispatchService.dispatch의 "FCM 실발송 연동 지점"(push_tokens 조회 후 발송) 및 OutboxWorker의 payload 소비부. payload는 이미 그대로 사용 가능하도록 구성.

⑦ PG 오픈API (매장 연동) 구현

목적 — 매장 쇼핑몰 서버가 결제 생성·조회·취소·정산요청을 호출하는 외부 공개 API.

인터페이스 — /pg/**. HmacAuthFilter가 헤더 4종(X-Client-Id, X-Api-Key, X-Timestamp, X-Signature)을 검증. 서명 = HMAC-SHA256(비밀키, "METHOD\n경로\n시각\n본문") hex 소문자. 시각 오차 300초 초과 시 거부(재사용 공격 방지). 주요 엔드포인트: POST /pg/ping(연결시험), POST /pg/payments, GET /pg/payments/{id}, POST /pg/payments/{id}/cancel, GET /pg/balance, POST /pg/settlements.

현재 상태 — 구현 완료. 비밀키는 DB에 해시만 저장(원문 미보관)하며 키 교체 유예 중에는 직전 키도 인정. 서명 통과 후 매장별 승인 화이트IP(PgCredentialMapper.selectApprovedCidrs) 검사까지 통과해야 호출 성립(V7 확정 요구).

비고 — 인증 실패는 모두 401 + 공통 포맷(A-2 필터 경로). 미승인 IP·화이트IP 미등록도 거부.

⑧ 매장 웹훅 발송(아웃바운드) 구현

목적 — 결제·정산 등 이벤트를 매장 서버로 통지(콜백).

인터페이스 — WebhookSender(20초 주기)가 발송함(webhook_deliveries)을 훑어 매장 target_url로 POST. 헤더 X-Nestpay-Event, 서명 X-Nestpay-Signature = HMAC-SHA256(매장 webhook_secret, 본문). 매장은 이 서명으로 진위 확인.

현재 상태 — 구현 완료. 2xx면 DELIVERED, 실패 시 지수 백오프 재시도(최대 10회, 최대 60분 간격), 소진 시 EXHAUSTED + 오류 장부 기록. 2대 서버 동시 실행 시 UUID 집기 표식으로 중복 발송 방지. 웹훅 시크릿은 암호화 저장(복호화해 서명).

⑨ 국세청(NTS) 사업자 진위 미구현

목적/상태 — 매장 사업자등록 진위 확인용으로 external_api_logs.provider에 NTS(국세청)가 예약되어 있으나, 현재 코드에 호출 구현은 없음(스키마 예약 단계). 필요 시 아웃바운드 연동으로 추가.

운영 전환 체크리스트(요약) — ① 은행/본인인증/실명·1원 스텁을 실연동 구현으로 교체 → ② 운영 환경변수(위 5종 + NESTPAY_ENV=sandbox|live)를 강한 값으로 주입 → ③ SWAGGER_ENABLED=false → ④ 입금통지 웹훅 인증을 은행/PG 규격 서명으로 교체 → ⑤ FCM 실발송 연동. ①②③ 미완료 시 서버가 기동 자체를 거부한다.