1. 기본 규격
기준 주소(Base URL): https://npwp-api.nestpay.co.kr
← 지금 보고 있는 서버 기준으로 자동 표시됩니다 ·
운영은 npwp-api.nestpay.co.kr, 테스트는 npwp-tapi.nestpay.co.kr 입니다.
응답은 항상 같은 모양입니다
성공이든 실패든 아래 네 칸을 가진 꾸러미로 옵니다. 화면 코드는 success 만 보고
갈라지면 됩니다.
{
"success": true, // 성공 여부
"data": { ... }, // 성공일 때의 알맹이 (실패면 null)
"error": null, // 실패일 때의 한국어 안내문 (성공이면 null)
"meta": { "total": 120, "page": 1, "limit": 20 } // 목록일 때만
}
시각은 모두 한국시간(KST)
서버가 보내는 시각 글자에는 시간대 꼬리표가 붙지 않습니다(2026-08-11T06:29:01).
이미 한국시간이므로 다시 변환하지 마세요. 보는 사람 기기의 시간대로 해석하면 최대 9시간 어긋납니다.
돈은 원 단위 정수
금액은 소수점 없는 정수(원)입니다. 실수(float)로 다루면 반올림 오차가 생깁니다.
같은 요청이 두 번 가도 한 번만
결제·출금·선물은 앱이 따로 할 일이 없습니다. 서버가 알아서 한 번만 만듭니다.
어떻게 되나요? 이 요청들에는 PIN(또는 패스키) 확인으로 받은 pinPass 를 함께 보내는데,
이 인증표는 한 번 쓰면 끝입니다. 서버는 그 인증표를 거래의 중복 방지 열쇠로 삼고,
장부에 같은 열쇠가 두 번 들어가지 못하게 데이터베이스가 막습니다.
그래서 통신이 끊겨 같은 요청을 다시 보내도 거래는 하나만 생기고,
두 번째 요청에는 이미 사용된 인증입니다. 다시 인증해 주세요. 가 옵니다.
이 안내가 오면 돈이 두 번 나간 것이 아니라 이미 처리된 것이니,
거래 내역을 다시 읽어 결과를 확인하면 됩니다.
주의: Idempotency-Key 같은 헤더는 쓰지 않습니다.
붙여 보내도 서버는 읽지 않습니다(중복 방지는 위의 인증표로만 이루어집니다).
2. 인증
로그인하면 받은 출입증(토큰)을 이후 모든 요청의 머리말에 붙입니다.
Authorization: Bearer <토큰>
| 구분 | 설명 |
|---|
| 회원 | /app/me/** 는 회원 출입증이 필요합니다.
가입·로그인·본인인증·공지 조회 등은 출입증 없이 부릅니다. |
| 매장 | /store/** 는 매장 출입증이 필요합니다.
매장 가입 신청·로그인은 출입증 없이 부릅니다. |
| 돈 쓰는 요청 | 결제·출금·선물은 출입증만으로 안 됩니다.
PIN 확인으로 받은 pinPass(짧은 유효시간) 또는 패스키 확인을 함께 보내야 합니다. |
출입증이 만료되면 401 이 옵니다. 이때는 보관한 출입증을 지우고
로그인 화면으로 돌려보내세요. 계속 재시도하면 잠금이 걸릴 수 있습니다.
3. 오류 처리
error 칸에는 손님에게 그대로 보여 줄 수 있는 한국어 안내문이 들어 있습니다.
따로 문구를 만들지 말고 그대로 쓰세요 — 서버가 상황에 맞게 씁니다.
| 코드 | 뜻과 처리 |
|---|
| 400 | 보낸 값이 규격에 안 맞거나 조건이 안 됩니다(잔액 부족·한도 초과 등). 안내문을 그대로 표시. |
| 401 | 출입증 없음·만료. 로그인 화면으로. |
| 403 | 권한 없음 · 이용제한(관리자가 그 기능을 막아 둔 상태) · PIN 을 여러 번 틀려 잠긴 상태. 안내문을 그대로 표시하세요. |
| 404 | 없는 자료. 목록을 새로 읽으세요. |
| 429 | 짧은 시간에 너무 많이 불렀습니다(로그인·본인인증·결제·출금 등에 각각 횟수 제한이 있습니다). 잠시 뒤 다시 시도하도록 안내하세요. |
| 500 | 서버 오류. 서버에 기록이 남으므로 재현 시각을 알려 주세요. |
4·5. 엔드포인트 목록
이 목록은 자동으로 만들어집니다. 실행 중인 서버의 규격에서 그대로 읽어 넣으므로
코드와 어긋나지 않습니다. 요청·응답의 자세한 항목은 Swagger 에서 확인하세요
(/swagger-ui/index.html — 사내 IP 에서만 열립니다).
회원앱 API 71개
회원(손님)이 쓰는 앱이 부르는 API 입니다. 경로가 /app 로 시작합니다.
내 정보·지갑·거래내역 18
| 메소드 | 경로 | 설명 |
|---|
| GET | /app/me | 내 상태 — 이름·가입 3요건 완료 여부 |
| DELETE | /app/me/avatar | 프로필 사진 지우기 (기본 아이콘으로) |
| GET | /app/me/avatar | 내 프로필 사진 보기 (실물 이미지 — 본인 것만) |
| POST | /app/me/avatar | 프로필 사진 올리기 (이미지 · 5MB 이하) |
| GET | /app/me/bank-accounts | 연결계좌 — 내 인증 계좌 목록(은행·예금주·계좌 마스킹·인증 시각) |
| GET | /app/me/bank-accounts/history | 연결계좌 변경 이력 — 활성·해지 전부(마스킹) |
| POST | /app/me/bank-accounts/one-won/confirm | ③ 1원 코드 확인 → 계좌 등록(가입 3요건 완료) |
| POST | /app/me/bank-accounts/one-won/send | ③ 1원 보내기 — 확인표(verifyToken) 발급 (개발환경은 debugCode 포함) |
| POST | /app/me/bank-accounts/verify-holder | ② 계좌 실명조회 — 본인 명의인지 확인 |
| GET | /app/me/cash-receipts/by-txn/{txnId} | 내 결제의 현금영수증 확인 — 내 번호로 제대로 발행됐는지 보기 |
| GET | /app/me/closure | 탈퇴 화면 정보 — 보유 포인트(소멸 예정)·진행 중 신청 여부 |
| POST | /app/me/closure | 회원 탈퇴 신청 — 관리자 승인 후 최종 탈퇴(보유 포인트 소멸) |
| POST | /app/me/password | 비밀번호 변경 (현재 비밀번호 확인) |
| GET | /app/me/profile | 본인정보 — 실명·생년월일·성별·전화번호(마이페이지 설정) |
| GET | /app/me/seizure | 묶여 있는 금액 (사고 조사 중인 포인트 · 0이면 표시하지 않음) |
| GET | /app/me/statements | 내 월 명세서 (충전·결제·출금·선물·수수료 합계 — yyyymm, 비우면 이번 달) |
| GET | /app/me/transactions | 내 거래 내역 (충전·결제·출금·선물 — 받은 선물 포함, 유형 필터·페이징) |
| POST | /app/me/verify-identity-complete | 앱서 본인인증 완료 — 관리자 사전생성(PENDING) 회원이 최초 로그인 후 실제 신원 인증 |
가입·로그인·본인인증 9
| 메소드 | 경로 | 설명 |
|---|
| POST | /app/auth/identity/confirm | ①-3 인증번호 확인 — 본인인증표(identityToken) 발급 |
| POST | /app/auth/identity/resend | ①-2 인증문자 재발송 |
| POST | /app/auth/identity/result | ①-4 인증 결과 확인 — 결과가 늦게 도착할 때 앱이 다시 물어봅니다 |
| POST | /app/auth/identity/start | ①-1 본인인증 시작 — 인증문자 발송(trackId 발급) |
| POST | /app/auth/login | 아이디·비밀번호 로그인 (이력 기록) |
| GET | /app/auth/login-id/availability | 아이디 사용 가능 확인 (회원·매장·관리자 전체 중복 검사) |
| POST | /app/auth/pin-login | PIN 간편 로그인 (등록된 기기에서 PIN 만으로) |
| POST | /app/auth/signup/eligibility | ② 가입 자격 확인 (1인 1활성계정·재가입 대기) |
| POST | /app/users | ③ 가입 — 성공 시 즉시 로그인(다음 단계: 계좌 등록) |
공지·FAQ·배너 9
| 메소드 | 경로 | 설명 |
|---|
| GET | /app/content/banks | 은행 목록 (계좌 등록 화면의 선택 목록 · 로그인 불필요) |
| GET | /app/content/banners | 앱: 배너 목록 (게시·기간 내, 노출 순서) |
| GET | /app/content/banners/{id}/image | 앱: 배너 이미지 (공개 제공은 배너 이미지에 한정) |
| GET | /app/content/faqs | 앱: FAQ 전체 (게시분만) |
| GET | /app/content/notices | 앱: 공지·이벤트 목록 (게시분만 · audience 로 대상 앱 필터) |
| GET | /app/content/notices/{id} | 앱: 공지 한 건 (게시분만) |
| GET | /app/content/notices/{id}/image | 앱: 이벤트 이미지 (게시 중인 이벤트에 한정) |
| GET | /app/content/policies/required | 앱: 가입 시 반드시 동의해야 할 약관 목록 — 회원·매장 공용 |
| GET | /app/content/policies/{kind} | 앱: 시행 중 약관/방침 (kind=TERMS|PRIVACY) — 사용자·매장 공용 |
패스키 8
| 메소드 | 경로 | 설명 |
|---|
| POST | /app/auth/passkey/login/finish | 패스키 로그인 마침 — 서명 확인 → 회원 세션 발급 |
| POST | /app/auth/passkey/login/start | 패스키 로그인 시작 — 문제(챌린지) 발급 |
| GET | /app/me/passkeys | 내 패스키 목록 |
| POST | /app/me/passkeys/register/finish | 패스키 등록 마침 — 서명 확인 후 공개키 저장 |
| POST | /app/me/passkeys/register/start | 패스키 등록 시작 — 문제(챌린지) 발급 |
| POST | /app/me/passkeys/tx/finish | 패스키 거래 인증 마침 — 서명 확인 → 거래 인증표(pinPass) 발급 |
| POST | /app/me/passkeys/tx/start | 패스키 거래 인증 시작 — 문제(챌린지) 발급(로그인 필요) |
| POST | /app/me/passkeys/{id}/delete | 내 패스키 삭제 (PIN 인증 필요) |
카드 5
| 메소드 | 경로 | 설명 |
|---|
| GET | /app/me/cards | 내 카드 목록 (마스킹 번호·잔액 — 대표 카드 먼저) |
| POST | /app/me/cards | 카드 발급 (수량 정책 검사 · 첫 카드는 대표 카드) |
| GET | /app/me/cards/quota | 발급 가능 여부 (최대 장수·현재 장수·canIssue) — 앱 발급 버튼 노출 판단 |
| POST | /app/me/cards/{id}/primary | 대표 카드 지정 |
| POST | /app/me/cards/{id}/reveal | 카드 민감정보 열람 (전체 카드번호·CVC — PIN/패스키 인증 필요) |
선물하기 5
| 메소드 | 경로 | 설명 |
|---|
| POST | /app/me/gifts | 바로 선물 (전화번호 또는 카드번호·QR · 유상 포인트만 · PIN 인증 표 필수) |
| GET | /app/me/gifts/received | 받은 선물 내역 (바로 선물 — 보낸 사람 이름·금액·받은 시각·상태) |
| POST | /app/me/gifts/recipient | 받는 사람 확인 (전화번호 — 이름은 가려서 표시) |
| POST | /app/me/gifts/recipient/by-card | 받는 사람 확인 (카드번호·QR — 이름은 가려서 표시) |
| GET | /app/me/gifts/sent | 보낸 선물 내역 (바로 선물 — 받는 사람 이름·금액·보낸 시각·상태) |
충전 신청 4
| 메소드 | 경로 | 설명 |
|---|
| GET | /app/me/deposit-requests | 내 충전신청 목록(대기 우선) |
| POST | /app/me/deposit-requests | 충전신청 — 금액 선언 후 배정계좌·고유코드 발급 |
| GET | /app/me/deposit-requests/{id} | 내 충전신청 1건(입금 확인 폴링용) |
| POST | /app/me/deposit-requests/{id}/cancel | 내 대기 충전신청 취소 |
알림 3
| 메소드 | 경로 | 설명 |
|---|
| GET | /app/me/notifications | 내 알림함 (최근 30일 + 안 읽은 개수) |
| POST | /app/me/notifications/read-all | 알림 전체 읽음 |
| POST | /app/me/notifications/{id}/read | 알림 한 건 읽음 |
PIN 3
| 메소드 | 경로 | 설명 |
|---|
| GET | /app/me/pin | 내 PIN 상태 (등록·잠김 여부) |
| POST | /app/me/pin | PIN 등록/변경 (숫자 6자리 · 변경은 기존 PIN 확인) |
| POST | /app/me/pin/verify | PIN 검증 — 성공 시 거래 인증 표(pinPass, 3분) 발급 |
문의 2
| 메소드 | 경로 | 설명 |
|---|
| GET | /app/me/inquiries | 내 문의·답변 목록 |
| POST | /app/me/inquiries | 1:1 문의 남기기 |
QR 결제 2
| 메소드 | 경로 | 설명 |
|---|
| POST | /app/me/payments | QR 결제 실행 (PIN 인증 표 필수 — 무상 포인트 우선 사용) |
| POST | /app/me/payments/qr/verify | QR 확인 (매장 이름·금액 — 결제 전 화면 표시용) |
출금 2
| 메소드 | 경로 | 설명 |
|---|
| POST | /app/me/withdrawals | 출금 신청 (선차감 · 유상 포인트만 · PIN 인증 표 필수) |
| GET | /app/me/withdrawals/info | 출금 신청 화면 정보 (계좌·수수료·예정 시각·진행 중 출금) |
부팅 관문(점검·최소버전) 1
| 메소드 | 경로 | 설명 |
|---|
| GET | /app/gate | 앱 부팅 게이트 (점검 모드·강제 업데이트·필수 공지) |
매장앱 API 34개
사장님이 쓰는 매장앱이 부르는 API 입니다. 경로가 /store 로 시작합니다.
매장 정보·서류·PG 연동·정산 23
| 메소드 | 경로 | 설명 |
|---|
| GET | /store/cash-receipts | 현금영수증 발행 내역 |
| POST | /store/cash-receipts | 현금영수증 발행 — 완료된 결제 건에 대해 발행(한 결제당 한 장) |
| GET | /store/cash-receipts/by-txn/{txnId} | 결제 건의 현금영수증 발행 여부 — 결제 상세에서 버튼 상태를 정할 때 씁니다 |
| POST | /store/cash-receipts/{receiptId}/cancel | 현금영수증 취소 — 전체 금액만 취소됩니다(부분취소 없음) |
| GET | /store/documents | 요구된 서류 목록 |
| GET | /store/documents/{documentId}/file | 내가 제출한 서류 파일 내려받기 |
| POST | /store/documents/{documentId}/file | 서류 파일 제출(매장 주체로 기록) |
| GET | /store/integrity | 매출 무결성 — 우리 매장 지갑 잔액이 원장(받은 결제−취소−정산)과 맞는지 |
| GET | /store/me | 내 매장 정보(가입정보·심사 상태·보완 요청 사유 포함) |
| POST | /store/password | 매장 본인 비밀번호 변경 (현재 비밀번호 확인) |
| GET | /store/pg | PG 연동 현황(연동 정보·테스트 체크·화이트IP) |
| GET | /store/pg/api-logs | 내 PG 호출 기록 (보낸 값·받은 값·막힌 이유 — 연동 문제 스스로 확인) |
| POST | /store/pg/apply | PG 연동 신청 — 매장코드·비밀키 발급(비밀키는 1회만 표시) |
| POST | /store/pg/files | PG 첨부파일 업로드(에스크로 확인증·이행보증보험증권) → 파일번호 발급 |
| POST | /store/pg/ips | 화이트IP 신청(관리자 승인 후 open API 허용) |
| POST | /store/pg/webhook | 웹훅 콜백 주소 등록 — 결제 결과를 받을 주소 설정(서명키 1회 반환) |
| POST | /store/pg/webhook/signature-test | 웹훅 서명 검증 시험 — 일부러 틀린 서명을 보내 매장이 거절하는지 확인 |
| POST | /store/resubmit | 보완 완료 제출 (보완 대기 → 다시 심사중) |
| GET | /store/seizure | 묶여 있는 금액 (사고 조사 중인 정산금 · 0이면 표시하지 않음) |
| GET | /store/settle-account | 정산통장 현황(없음/승인대기/승인됨) |
| POST | /store/settle-account/one-won/confirm | 정산통장 ③ 코드 확인 → 승인대기 등록 |
| POST | /store/settle-account/one-won/send | 정산통장 ③ 1원 보내기 |
| POST | /store/settle-account/verify-holder | 정산통장 ② 계좌 실명조회 |
매장 가입·로그인 3
| 메소드 | 경로 | 설명 |
|---|
| POST | /store/apply | 매장 가입 신청 (심사중으로 접수 — 최종 승인은 관리자) |
| POST | /store/auth/login | 매장 로그인 — 출입증(토큰) 발급 |
| POST | /store/policy-agreements | 약관 동의 — 관리자 대리 등록 매장의 첫 로그인·약관 개정 시 |
QR 관리 3
| 메소드 | 경로 | 설명 |
|---|
| GET | /store/qrs | 내 QR 목록 (활성 QR 은 표시용 QR 글자 포함) |
| POST | /store/qrs | QR 만들기 (고정 또는 금액 지정 5분 1회용) |
| POST | /store/qrs/{id}/revoke | QR 끄기 (분실·교체 시 즉시 무효화) |
매출 요약 2
| 메소드 | 경로 | 설명 |
|---|
| GET | /store/summary | 매장 매출 요약 (오늘·이번 달 + 정산 예정 잔액) |
| GET | /store/transactions | 매장 거래 내역 (결제·취소·정산 지급, 유형 필터·페이징) |
정산 계좌 2
| 메소드 | 경로 | 설명 |
|---|
| POST | /store/settlements | 정산 출금 신청 (선차감 · 매장 지갑 무로트 · 멱등키로 중복 차단) |
| GET | /store/settlements/info | 정산 신청 정보 (잔액·계좌·예정 시각) |
결제 취소 1
| 메소드 | 경로 | 설명 |
|---|
| POST | /store/payments/{txnId}/cancel | 결제 전액 취소 (본 매장 결제만 · PG 주문 결제 제외 · 멱등) |