레퍼런스

보안

AutoTransPay 보안 문서입니다. 비밀값 보관, 데이터 격리, 위조 문자 대응, 웹훅 보안, 팀 권한, 감사 로그, 보관 기간과 취약점 제보 방법을 적었습니다.

AutoTransPay 는 가맹점의 결제 확정을 대신하는 시스템입니다. 잘못된 확정 하나가 곧 금전 사고이기 때문에, 비밀값 보관·데이터 격리·위조 대응을 설계 단계부터 다룹니다.

비밀값 보관

비밀값 접두사 저장 방식
API 키 atp_live_ · atp_test_ SHA-256 해시만 저장. 원문은 발급 직후 한 번만 표시
수집기 토큰 atpc_ SHA-256 해시만 저장
웹훅 서명 키 whsec_ 서명을 만들려면 원문이 필요하므로 AES-256-GCM 으로 암호화 저장
계좌번호 — AES-256-GCM 암호화 저장. 화면에는 마스킹 표시
  • 접두사로 종류를 바로 알아볼 수 있어, 로그나 스크린샷에 키가 섞였을 때 빠르게 찾아 폐기할 수 있습니다.
  • 키가 유출되었다고 의심되면 콘솔에서 즉시 폐기하세요. 폐기된 키는 바로 401 이 됩니다.
  • 암호화 키는 애플리케이션 환경 변수로만 존재하며 데이터베이스에 저장되지 않습니다.

데이터 격리

  • 조직 격리 — 모든 주문·입금·이벤트·키는 조직에 속하고, 모든 조회는 조직 조건을 붙여 실행됩니다.
  • 모드 격리 — 테스트(livemode=false)와 운영(livemode=true) 데이터는 같은 조직 안에서도 완전히 분리되어, 테스트 주문이 실제 입금과 매칭되는 일은 없습니다. 매칭 확정 함수가 모드 불일치를 한 번 더 거부합니다.
  • 계좌 격리 — 주문에 계좌를 지정하면 다른 계좌 입금은 후보에서 제외됩니다.
  • 서비스 격리 — 데이터는 전용 스키마에 있고 모든 테이블에 행 수준 보안(RLS)이 켜져 있습니다. 브라우저용 공개 권한(anon/authenticated)으로는 어떤 행도 읽을 수 없고, 모든 접근은 인증된 서버 API 를 거칩니다.
  • 동시성 — 매칭 확정은 주문·입금 행을 잠그고 상태를 검사하는 단일 트랜잭션입니다. 입금 수신과 주문 등록(역매칭)이 동시에 같은 주문을 잡아도 한쪽만 성공합니다.

위조 문자 대응

누군가 수집기 휴대폰에 은행을 사칭한 가짜 입금 문자를 보내는 공격을 막기 위해 여러 겹의 방어를 둡니다.

방어 동작
발신번호 허용목록 수집기에 등록한 은행 대표번호 외의 발신번호는 rejected 로 폐기. 허용목록이 없는 수집기의 입금은 자동확정하지 않음(sender_unverified) → 설정 방법
잔액 연속성 검사 계좌의 직전 잔액 ± 이번 금액 ≠ 문자의 잔액이면 balance_gap → 자동확정하지 않음. 의심 문자의 잔액으로는 기준을 바꾸지 않고, 사람이 확정한 입금으로 다시 맞춥니다
금액 조작 감지 입금자명에 "입금 50000" 같은 글자를 넣어 금액을 헷갈리게 만든 입금(multi_amount·name_suspicious)은 자동확정하지 않음
발신자 검사 개인 휴대폰 번호(sender_mobile)·해외(intl_sender)에서 온 입금 문자는 자동확정하지 않음
시각 검사 문자 속 거래 시각이 미래이거나 3일 넘게 지난 문자(time_skew)는 자동확정하지 않음
자동확정 금액 상한 auto_max_amount 를 넘는 입금은 항상 사람 확인(over_limit)
확신도 기준 형식이 어색한 문자(확신도 0.7 미만)는 자동확정하지 않음
계좌 마스킹 대조 문자에 찍힌 마스킹 계좌와 등록 계좌가 맞지 않으면 그 계좌의 입금으로 보지 않음
중복 제거 (금액, 거래 후 잔액, 시각) 등으로 같은 거래를 한 건으로 합쳐, 같은 문자를 반복 전송해도 입금이 늘지 않음. 잔액 없는 알림이 겹치면 실제 두 번째 입금일 수 있어 버리지 않고 "중복 의심"으로 사람 확인
주의

잔액이 찍히지 않는 알림(일부 앱 푸시)은 잔액 연속성 검사를 할 수 없습니다. 이런 계좌는 발신번호 허용목록과 자동확정 금액 상한을 반드시 함께 쓰세요.

웹훅 보안

  • 모든 웹훅은 엔드포인트별 서명 키로 HMAC-SHA256 서명되고, 타임스탬프가 포함되어 5분이 지난 요청은 거부할 수 있습니다 → 서명 검증.
  • 운영 웹훅 URL 은 HTTPS 만 허용합니다.
  • 가맹점이 409·410·422 로 거절한 매칭은 자동으로 되돌려 사람 확인으로 보냅니다.

팀 권한

역할 할 수 있는 일
소유자 모든 작업. 관리자까지 초대·변경 가능. 조직을 나가거나 강등되지 않음
관리자 설정 · 운영 키/웹훅 · 수집기 · 운영 입금 확정. 개발자·조회 역할까지 초대·변경
개발자 테스트 모드 연동 (테스트 키 · 웹훅 · 샌드박스)
조회 보기만
  • 초대 링크는 7일 동안 한 번만 쓸 수 있고, 초대한 이메일과 같은 확인된 이메일로 로그인해야 수락됩니다. 링크가 다른 사람에게 전달돼도 그 사람은 들어올 수 없습니다.
  • 자신보다 낮은 역할만 주고, 자신보다 낮은 역할의 멤버만 바꾸거나 내보낼 수 있습니다.
  • 텔레그램 1탭 확정 권한은 연결 코드를 발급한 관리자에게서 위임됩니다. 그 관리자가 팀에서 나가거나 관리자 아래로 바뀌면 그 코드로 등록된 승인자의 버튼도 즉시 막힙니다.

콘솔 부정 이용 방어

자동화 도구로 콘솔을 마구 호출하거나 남의 조직을 엿보는 계정은 자동으로 막습니다.

항목 한도
콘솔 요청 계정당 분당 300건, 같은 네트워크(IP)에서 여러 계정을 합쳐 분당 600건
변경 요청(조회 제외) 계정당 분당 120건
조직 만들기 계정당 하루 3개, 같은 네트워크에서 하루 5개. 일회용(임시) 메일 계정은 만들 수 없음
API 키 모드(운영·테스트)마다 활성 키 20개, 조직당 시간당 발급 20개
  • 10분 안에 다른 조직 접근이 40번 넘게 거부되거나 요청 한도를 60번 넘게 초과하면 그 계정의 콘솔 이용이 자동으로 막히고, 운영팀에 바로 알림이 갑니다.
  • 막힌 계정은 모든 콘솔 요청에 403 account_blocked 를 받습니다. 잘못 막혔다면 고객센터로 알려 주세요. 확인 뒤 바로 풀어 드립니다.
  • 한도를 넘은 요청은 429 rate_limited 로 거절되며, Retry-After 헤더가 다시 시도할 시점을 알려 줍니다.

감사 로그

수동 매칭·입금 무시 같은 상태 변경과 팀 변경(초대·수락·역할 변경·내보내기), 설정 변경은 누가(콘솔 사용자·API 키·텔레그램 사용자·MCP), 언제, 무엇을 했는지 감사 로그에 남습니다. 웹훅의 data.match.actor 에도 같은 주체가 기록됩니다.

데이터 보관 기간

데이터 보관 기간
입금 알림 원문 (수집기가 올린 문자·푸시 전문) 90일 후 파기
주문·입금·이벤트 기록 이용계약 기간 동안 보관, 조직 종료일부터 30일이 지난 뒤 파기 (법령상 보존 의무가 있으면 그 기간)
웹훅 전송 기록 90일
감사 로그 1년
공용 수신번호 — 인증번호 전달을 위해 저장한 인증번호 받은 뒤 최대 15분
공용 수신번호 — 어느 조직의 것인지 정할 수 없는 문자 (연결 전·연결 해제·수신 중지 계좌 포함) 14일. 허용하지 않은 발신번호의 문자는 본문 없이 발신번호·수신 시각·글자 수·중복 확인용 해시만
공용 수신번호 수신 기기에 남은 문자 사본 주 1회 이상 삭제

자세한 내용은 개인정보처리방침을 참고하세요. 공용 수신번호로 받은 문자의 보관은 공용 수신번호 이용 조건 제9조를 따릅니다(2026-10-14 시행).

취약점 제보

보안 취약점을 발견하셨다면 공개하기 전에 dudgns2947@gmail.com 으로 알려 주세요. 확인 즉시 답변드리겠습니다.