📘 사용자 매뉴얼

2. 서비스 관리

🍎

쉽게 말하면, "어떤 사내 앱이 이 결제 서버를 쓸지" 를 등록·관리하는 화면입니다. 서비스를 등록해야 그 서비스용 API 키·토스 시크릿 키·요금제·구독이 생깁니다. 전체 흐름에서 가장 먼저 하는 일입니다(0. 개요의 1~5 준비 단계).

대상: SYSTEM_ADMIN 전용 화면입니다. 서비스 담당자 SERVICE_MANAGER에게는 이 메뉴가 보이지 않습니다.

함께 보기: 관리자 콘솔 사용하기 · 계정 관리 · 요금제 관리 · 서비스 알림 기능 · 화면별 기술 레퍼런스는 어드민 화면별 설명.

2.1 시작 전에 — 담당자 계정을 먼저

서비스 등록 화면은 담당자를 목록에서 선택하는 방식입니다. 그래서 담당자 계정(SERVICE_MANAGER)을 먼저 만들어야 서비스에 담당자를 지정할 수 있습니다. 계정 생성은 계정 관리를 참고하세요.

💡

참고: 담당자 후보 목록에는 삭제되지 않은 SERVICE_MANAGER 계정 전체가 이메일 순으로 나옵니다. SYSTEM_ADMIN 계정은 담당자로 지정할 수 없습니다.

2.2 서비스 목록

서비스 목록 화면 (검색·상태 필터·엑셀 내보내기)

왼쪽 메뉴에서 서비스를 누르면 등록된 서비스 목록이 열립니다.

  • 검색: 서비스명 또는 담당자(이메일) 일부로 검색
  • 상태 필터: 활성(ACTIVE) / 비활성(INACTIVE) / 전체
  • 정렬: 서비스명·상태 컬럼 머리글을 클릭해 정렬(기본은 등록일 최신순)
  • 컬럼: 이름(서비스명), 담당자, 허용 IP, 상태
  • 서비스명을 누르면 서비스 상세로 이동합니다.
  • 오른쪽 위 [서비스 등록] 버튼으로 새 서비스를 만듭니다.
  • 엑셀 내보내기: 현재 검색·필터가 적용된 목록을 엑셀(.xlsx)로 내려받습니다. 한 번에 내보낼 수 있는 최대 행 수에 제한이 있어, 그보다 많으면 검색·필터로 범위를 좁혀 받으세요.
💡

참고: 비활성(INACTIVE) 서비스는 API 키 인증이 막혀 외부 호출이 모두 거부됩니다(상세에서 활성/비활성을 토글, 2.10.1 참고).

2.3 서비스 등록

서비스 등록 폼

서비스 → 서비스 등록(/admin/services/new)에서 입력합니다. 필수 항목의 라벨에는 빨간 별표(*)가 표시되어 선택 항목과 구분됩니다.

항목 필수 설명
서비스명 필수 콘솔에 표시될 이름(중복 불가). 같은 이름이 이미 있으면 등록이 거부됩니다
담당자 계정 선택 미리 만든 SERVICE_MANAGER 계정을 복수 선택(체크박스). 비워 둬도 아래 대표 계정이 자동으로 담당자에 포함되므로 저장할 수 있습니다
대표 계정 필수 결제 실패·갱신 등 알림 메일 수신처. 체크 목록에서 빠져 있어도 자동으로 담당자에 포함되며 목록 맨 앞에 배치됩니다
허용 IP 선택 API를 호출할 서버의 공인 IP. 4칸 옥텟 입력(각 0~255, 숫자만) 행에 한 IP씩 적고 [IP 추가]로 행을 늘립니다. 비우면 IP 제한 없음(이 경우 호출은 HMAC 서명으로만 보호)
일반결제 취소 정책 — 단건(일반) 결제 취소 허용 여부 + 취소 수수료율(0~100%)
토스 시크릿 키 선택 그 서비스의 토스 시크릿 키. AES 암호화 저장, 저장 후 다시 표시되지 않음(쓰기 전용). 지금 비워두고 나중에 상세에서 설정/교체 가능(2.8 참고)
💡

참고: 허용 IP는 IPv4만 받습니다(IPv6·CIDR 불가). 같은 서버를 가리키는 로컬 주소(127.0.0.1)는 항상 허용되므로 입력해도 목록에 저장되지 않습니다.

중요: 결제가 동작하려면 그 서비스의 토스 시크릿 키가 등록돼 있어야 합니다(서비스마다 다름). 미등록 서비스는 결제·구독 첫 결제·자동연장이 TOSS_KEY_NOT_CONFIGURED(422)로 거부됩니다. 자세한 동작은 어드민 화면별 설명 참고. (전역 TOSS_SECRET_KEY 환경변수는 제거됨)

2.4 키 발급·전달 (등록 직후, 1회성 · 중요)

키 발급/복사 화면

등록을 누르면 키 발급 화면으로 이동합니다.

  • API 키와 HMAC 시크릿이 화면에 단 한 번만 표시됩니다(키는 암호화 저장되므로 평문을 볼 수 있는 유일한 기회).
  • 두 값을 복사해 안전한 채널(사내 비밀 저장소 등)로 서비스 담당 개발자에게 전달하세요.
  • 화면을 벗어나면 평문 키를 다시 볼 수 없습니다.
⚠️

주의: 평문 키가 담긴 화면은 브라우저 캐시에 남지 않도록 처리되며, 키 조회는 감사 로그에 기록됩니다.

함께 보기: API 키·HMAC 시크릿의 용도(요청 서명)는 서비스 연동 API를 참고하세요. 토스 시크릿 키는 서버가 토스에 결제 요청할 때 쓰는 별도 값이며, 외부 서비스의 client key와는 다릅니다(client key는 서비스 프론트가 자체 사용).

2.4.1 키 다시 복사하기 (키 복사 모달)

이미 발급된 서비스라도, 상세 화면에서 키 복사 모달을 열면 보관된 평문 API 키·HMAC 시크릿을 다시 확인·복사할 수 있습니다(키는 암호화 저장돼 있으므로 복호화해 표시). 이 조회 역시 감사 로그에 남습니다.

⚠️

주의: 키 복사는 평문 노출 동작이므로 꼭 필요한 경우에만 사용하고, 유출이 의심되면 키 재발급(2.4.2)으로 즉시 무효화하세요.

2.4.2 키 재발급(회전)

분실·유출 시, 상세에서 키 재발급(회전)을 실행합니다.

  • 새 API 키·HMAC 시크릿이 즉시 발급되고 이전 키는 그 즉시 무효화됩니다.
  • 발급 직후 같은 1회성 키 화면이 다시 표시되므로, 새 값을 복사해 외부 서비스가 새 키로 다시 설정하도록 전달해야 합니다(재설정 전까지 해당 서비스의 API 호출은 인증 실패).

2.5 서비스 상세 — 개요

서비스 상세 화면

서비스명을 누르면 상세 화면이 열립니다. 상단에는 서비스 정보와 설정 영역이, 하단에는 데이터 탭이 있습니다.

  • 기본 정보: 맨 위 한 줄에 서비스명 · 서비스구독명과 "등록 후 변경 불가" 배지가 표시됩니다. 두 이름은 수정할 수 없습니다 — 서비스명은 손익 모니터링의 집계 단위, 서비스구독명은 전체 고유 식별자라 등록 후 바꾸면 모니터링 쪽 과거 집계가 갈라지기 때문입니다. 이름을 바꿔야 하면 새 서비스를 등록해 이전하세요.
  • 설정 영역(2.6~2.13): 허용 IP, 취소 정책, 알림 URL, 토스 시크릿 키, 상태 토글, 키 재발급, 담당자 관리, 삭제, 에러 테스트 모드, 모니터링 전용 키
  • 데이터 탭(2.11): 요금제 · 구독 · 단건 결제 · 등록 카드 · 이벤트
💡

참고: 설정을 저장하면 "저장되었습니다" 같은 완료 안내가 표시됩니다. 입력값 오류(예: 잘못된 IP, 범위를 벗어난 수수료율)는 화면 상단에 오류 메시지로 안내됩니다.

2.6 허용 IP 수정

상세에서 허용 IP 목록을 통째로 교체합니다.

  • IP 한 개당 한 행씩, 옥텟 입력칸 4개(IP 주소를 점으로 나눈 네 개의 숫자 칸, 각 0~255)에 나눠 입력합니다. [IP 추가] 버튼으로 행을 늘리고, 행 옆 [삭제]로 지웁니다.
  • 비우면 IP 제한이 없어집니다(모든 IP 허용 — 이 경우 호출은 HMAC 서명으로만 보호).
  • 잘못된 IP 형식이면 저장이 거부되고 오류 메시지가 표시됩니다.

2.7 일반결제(단건) 취소 정책

단건(ONE_OFF) 결제의 취소 허용 여부와 취소 수수료율을 설정합니다.

항목 설명
취소 허용 체크하면 단건 결제 취소를 허용, 해제하면 취소 불가
취소 수수료율 0~100% 사이 정수. 취소 시 차감되는 수수료 비율 — 입력 시 범위 밖 값(음수·100 초과·소수)은 자동 보정되고, 저장 시에도 다시 검증됩니다
💡

참고: 이 정책은 단건(일반) 결제에만 적용됩니다. 구독 결제의 취소·환불은 별도 규칙을 따릅니다(결제·환불 관리).

2.8 서비스별 토스 시크릿 키 설정

상세에서 그 서비스의 토스 시크릿 키를 설정/교체/삭제합니다. 이 키는 그 서비스가 토스페이먼츠로 결제(빌링)를 호출할 때 사용하는 인증 키로, 토스 개발자센터에서 발급한 시크릿 키(test_sk_…(테스트) / live_sk_…(운영))를 넣습니다.

  • 한 줄 UI입니다: 라벨 · 등록여부 배지 · 입력칸 · [저장] · (설정됨일 때) [삭제] · 상세설명.
  • 이미 설정됨이면 빨간 배지로 강조되고, 입력칸에 마스킹 점(••••••) 으로 실제 값이 저장된 것처럼 표시됩니다(보안상 실제 키·길이는 노출하지 않습니다). 미설정이면 입력칸에 "시크릿키 입력해주세요" 안내가 보입니다.
  • 쓰기 전용입니다 — 저장한 평문 키는 화면·로그·감사 어디에도 다시 표시되지 않고, 상세에는 "이미 설정됨/미설정" 상태만 보입니다.
  • 입력란을 빈 값으로 저장하면 변경 없이 기존 키가 유지됩니다(실수로 키가 지워지지 않음). 키를 지우려면 [삭제] 버튼을 사용하세요.
  • [삭제] 는 이미 설정된 경우에만 보이며(상세설명과 한 줄에 붙어 표시), 확인 후 키를 제거합니다. 삭제하면 그 서비스의 카드 등록·구독 첫 결제·자동연장·단건결제가 모두 거부됩니다(미설정 상태로 되돌아감).
  • 키는 AES 암호화되어 저장됩니다.
  • 설정·교체·삭제는 각각 감사 로그에 기록되지만(설정/교체/삭제 구분), 시크릿 값 자체는 절대 기록되지 않습니다.
⚠️

중요: 토스 시크릿 키가 없으면 그 서비스의 결제·구독 첫 결제·자동연장이 모두 거부됩니다(2.3의 중요 안내 참고).

2.9 알림 수신 URL — 저장·테스트 전송

서비스 상세 화면의 설정 영역에서, 이 서비스가 받을 아웃고잉 웹훅(결제 서버가 상태 변화를 서비스 서버로 자동 전송해 주는 알림) 수신 URL을 등록합니다. 구독·결제·카드 상태가 바뀔 때(예: 결제 성공/실패, 구독 생성·갱신·취소, 카드 등록·변경) 결제 서버가 이 URL로 JSON 알림을 POST합니다. 외부 서비스는 이 알림을 받아 자기 DB를 갱신합니다.

서비스 상세 — 알림 수신 URL 등록·테스트 전송
서비스 상세의 '알림 수신 URL' 입력란과 [저장]·[테스트 전송] 버튼

2.9.1 등록 방법

  1. 서비스 상세 화면에서 알림 수신 URL 입력란에 서비스가 알림을 받을 주소를 입력합니다.
  2. [저장] 을 누르면 적용됩니다.
항목 규칙
URL 형식 반드시 http:// 또는 https:// 로 시작해야 합니다(그 외 형식은 저장 거부).
사용할 수 없는 주소 서버 자신(127.0.0.1·localhost) 과 169.254.x.x(클라우드 내부 관리용 주소) 등은 저장이 거부됩니다("내부 주소로는 알림을 보낼 수 없습니다"). 알림 수신처가 될 수 없는 주소이며, 결제 서버가 인프라 내부를 향해 요청을 보내는 통로가 되지 않도록 막습니다.
사내 주소 10.x.x.x·192.168.x.x·172.16~31.x.x, host.docker.internal 같은 사내망 주소는 정상적으로 사용할 수 있습니다.
비우고 저장 알림을 끕니다(미발송 상태).
변경 시점 저장 즉시 적용됩니다. 변경 내역은 감사 로그에 남습니다.

2.9.2 테스트 전송

[테스트 전송] 버튼을 누르면 저장된 URL로 테스트 알림을 즉시 보내고, 수신 측 응답(성공/실패)을 화면에서 바로 확인할 수 있습니다. 연동 초기 점검에 사용하세요.

테스트 전송 결과 상세 — 수신 측 응답·상태 코드
테스트 전송 결과 상세 — 성공/실패 여부와 수신 측 응답(상태 코드·사유)
⚠️

주의: URL이 미등록이거나 수신에 실패하면 실패 사유가 안내됩니다. 결제 서버와 수신 서버가 서로 다른 도커/네트워크에 있으면 localhost·컨테이너명으로는 닿지 않을 수 있으니, 결제 서버에서 실제로 도달 가능한 주소(예: http://host.docker.internal:8001/notify)를 등록하세요.

참고: 테스트 전송 결과는 성공/실패만 안내하고 상세 오류(연결 거부·타임아웃·HTTP 상태 코드)는 화면에 표시하지 않습니다. 이 버튼으로 사내망의 어느 주소가 살아 있는지 훑어볼 수 있게 되는 것을 막기 위함입니다. 정확한 원인은 서버 로그(payment.service_notify)에서 확인하세요.

함께 보기: 어떤 이벤트가 어떤 payload로 가는지, 재시도·서명 검증 등 자세한 동작은 서비스 알림 기능을 참고하세요.

2.10 상태 변경 · 담당자 관리 · 삭제

2.10.1 상태 변경 (활성/비활성)

서비스 상태를 ACTIVE ↔ INACTIVE로 토글합니다.

  • INACTIVE가 되면 그 서비스의 API 키 인증이 막혀 외부 호출이 모두 거부됩니다.
  • 구독 이력이 있어 삭제할 수 없는 서비스는, 삭제 대신 비활성화로 운영을 중단합니다.

2.10.2 담당자 관리

동작 설명
담당자 추가 드롭다운에서 아직 담당자가 아닌 SERVICE_MANAGER 계정을 골라 추가
대표 담당자 변경 담당자 중 한 명을 대표로 지정 → 그 계정 이메일이 알림 메일 수신처가 됨. 이 서비스의 담당자가 아닌 계정은 대표로 지정 불가
담당자 해제 담당자에서 제외. 단, 대표 담당자는 해제할 수 없습니다(먼저 다른 사람으로 대표를 바꾼 뒤 해제)
💡

참고: 담당자 추가/해제, 대표 변경은 모두 이 서비스의 이벤트(감사) 탭에 기록됩니다(2.11 참고).

2.10.3 서비스 삭제

상세에서 서비스를 삭제합니다.

  • 구독 이력이 1건이라도 있으면 삭제가 거부됩니다(먼저 구독을 정리하거나, 운영 중단이 목적이면 비활성화 사용).
  • 삭제 시 그 서비스의 요금제도 함께 삭제되고, 그 서비스에 연결된 담당자 User 계정도 함께 삭제(CASCADE)됩니다(서비스 없는 담당자 계정은 무의미하므로 의도된 동작).
⚠️

주의: 삭제는 되돌릴 수 없습니다. 단순 운영 중단이 목적이면 비활성화(2.10.1)를 권장합니다.

2.11 서비스 상세 — 데이터 탭

상세 하단에는 이 서비스에 속한 데이터를 보여주는 탭이 있습니다. 각 탭은 검색·필터·페이지를 서로 독립적으로 유지하며, 요금제·구독·단건 결제 탭에는 각각 [엑셀] 버튼이 있어 현재 조건 그대로 탭별 데이터를 내려받을 수 있습니다.

탭 내용
요금제 이 서비스의 요금제 목록(첫 결제 금액·정기 금액 등 표시). 관리는 요금제 관리
구독 이 서비스의 구독 목록. 상태 필터·검색은 구독 목록과 동일. 상세는 구독 관리
단건 결제 이 서비스의 일반(ONE_OFF) 결제 내역. 자세한 내용은 결제·환불 관리
등록 카드 이 서비스에 결제수단(카드)을 등록한 사용자별 목록(사용자 ID로 검색). 카드번호 마스킹·발급사·customerKey·등록/변경 시각 표시. 자세한 내용은 카드 관리
이벤트 이 서비스 관련 감사 로그(등록·상태변경·키 재발급·키 복사·IP 갱신·취소 정책·대표 지정·담당자 추가/해제·토스 키 설정·카드 이벤트 등). 시각·동작·요약·행위자를 표시
💡

참고: 이벤트 탭에는 시크릿 값(토스 키·평문 API 키 등)은 절대 표시되지 않고, "설정함/교체함" 같은 동작 요약만 남습니다. 전체 감사 로그는 감사 로그에서 확인하세요.

중요: 토스 시크릿 키 설정/변경, 키 재발급, IP 갱신 등 이 화면의 주요 동작은 모두 감사 로그에 남습니다(시크릿 값 자체는 기록하지 않음). → 감사 로그

2.12 에러 테스트 모드 (QA) — 서비스별 강제 에러

서비스 상세의 "에러 테스트 모드 (QA)" 카드에서 켜면, 이 서비스의 모든 외부 API 호출이 강제로 에러를 반환합니다(연동 서비스의 에러 처리 로직 검증용 — 요청 qa/서비스별_에러재현).

  • 재현할 에러는 API 요청 헤더 x-test-error-code로 지정하며, 응답 error에 test_mode: true 표식이 포함됩니다
  • 운영(prod) 환경에서는 켜도 무시됩니다 (실 트래픽 보호)
  • 켜져 있는 동안 카드에 빨간 ON 배지가 표시되고, 전환 이력은 감사 로그(service.error_test_toggled)에 남습니다
  • QA가 끝나면 반드시 꺼 주세요 — 켜 둔 동안 그 서비스의 실제 기능이 전부 멈춘 것과 같습니다

자세한 사용법(에러 코드 목록·응답 형식)은 21. 에러 테스트의 21.8을 참고하세요.

2.13 모니터링 전용 키 — 손익 모니터링 서버용 읽기 전용 키

사내 모니터링 서버가 서비스별 일일 수익(매출·환불·순매출)을 받아 가려면, 결제서버를 호출할 키가 필요합니다. 그 키는 일반 서비스 키와 권한이 반대입니다.

  1. 모니터링용 서비스를 하나 등록합니다(예: 서비스구독명 monitor). 요금제·구독은 만들지 않습니다.
  2. 서비스 상세의 "모니터링 전용 키" 카드에서 체크박스를 켜고 저장합니다. 카드에 파란 ON 배지가 표시됩니다.
  3. 허용 IP에 모니터링 서버 IP를 등록합니다(요청 서명이 쿼리 파라미터를 보호하지 않아 IP가 실질적인 2차 방어선입니다). 운영(prod/stg)에서는 IP 없이 켤 수 없고, IP가 비어 있으면 같은 서버(루프백)에서만 호출됩니다.
  4. 발급된 API 키·HMAC 시크릿을 모니터링 담당자에게 전달합니다. 전달용 지침은 22. 모니터링 연동 가이드입니다.

켜면 이 키는 GET /api/v1/metrics/sync만 호출할 수 있고, 카드·구독·결제 등 일반 API는 403으로 거부됩니다(키가 유출돼도 결제를 일으킬 수 없게 하는 분리). 반대로 일반 서비스 키로는 모니터링 피드를 호출할 수 없습니다.

  • 전환 이력은 감사 로그(service.metrics_scope_toggled, 화면 라벨 "모니터링 전용 키 전환")에 남습니다
  • 고객 이메일 원문 포함 체크박스(metrics_pii_scope): 건별 피드(/metrics/payments·/metrics/subscription-list)에 고객 이메일 원문을 넣을지 정합니다. 기본은 꺼짐 — 이메일 대신 서비스별 해시(user_ref)만 내려가 손익·고객별 통계에 충분합니다. 꼭 필요할 때만 켜고, 스코프를 끄면 함께 꺼집니다. 건별 피드 호출은 감사 로그 "모니터링 건별 피드 조회"에 남습니다
  • 실제 결제를 처리하는 서비스에 켜면 그 서비스의 API 호출이 전부 막힙니다. 모니터링용으로 등록한 서비스에만 켜세요
  • 피드가 내려주는 값(일별 매출·환불·순매출)은 정산 화면과 같은 규칙으로 집계되므로 두 숫자는 일치해야 정상입니다. API 명세는 13.10