API & SDK

링크 복사보안 체크리스트

결제 연동을 마치고 라이브 오픈하기 전에 상점이 직접 확인하는 5가지 보안 점검 항목이에요. 항목별로 통과 기준과 자세한 내용을 볼 수 있는 링크를 함께 제공해요.

1·2·4번 항목은 오픈 전 필수예요. 미흡한 상태로 오픈하면 사고가 났을 때 피해가 직접 발생해요. 3·5번은 오픈 직후 한 달 안에 마무리하는 것을 권장해요.

링크 복사체크리스트

링크 복사1. 시크릿 키를 서버에만 보관하고 있어요

시크릿 키는 결제를 승인·취소·조회할 수 있는 자격증명이에요. 키가 브라우저·앱에 들어가면 누구나 쉽게 확인할 수 있어요.

통과 기준

  • 프론트엔드 코드(JS 번들, HTML)에 시크릿 키가 없다
  • 모바일 앱 바이너리·설정에 시크릿 키가 없다
  • URL 쿼리스트링에 시크릿 키를 넣어 호출하지 않는다
  • 소스 코드에 시크릿 키를 하드코딩하지 않았다
  • 로그에 Authorization 헤더가 통째로 출력되지 않는다

시크릿 키는 코드·설정 파일과 분리된 전용 저장소(AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, HashiCorp Vault 등)에 두고 실행 시점에 불러오는 방식을 권장해요. 저장소를 사용할 수 없다면 환경변수로 주입하고 해당 파일을 .gitignore에 추가하세요.

확인 방법 — 배포된 JS 번들을 내려받아 키 패턴(live_sk_, live_gsk_)으로 검색해 보세요. 저장소는 git log -p | grep으로 히스토리까지 확인하세요.

자세한 내용: 시크릿 키 관리

링크 복사2. 테스트 키와 라이브 키를 분리해 쓰고 있어요

테스트 환경에서 라이브 키를 쓰면 라이브 키의 노출 위험이 그만큼 커져요. 개발 PC, CI 로그, 스테이징 서버까지 전부 유출 경로가 돼요.

통과 기준

  • 개발·스테이징 환경은 테스트 키(test_)만 사용한다
  • 라이브 키는 운영 서버에만 주입된다
  • 환경 전환이 설정값으로 이뤄지고, 코드 수정 없이 바뀐다
  • 클라이언트 키와 시크릿 키를 같은 세트로 쓰고 있다

세트가 아닌 키를 섞어 쓰면 INVALID_API_KEY(400) 에러가 발생해요.

자세한 내용: 클라이언트 키와 시크릿 키

링크 복사3. API 키 접근 정책(IP 제한)을 등록했어요

키가 유출되더라도 등록하지 않은 IP에서는 호출할 수 없어요. 유출 피해가 실제 결제·취소로 번지는 것을 막는 마지막 방어선이에요.

통과 기준

  • 라이브 시크릿 키에 접근 정책이 연결돼 있다
  • 등록한 IP가 서버의 공인 IP(NAT IP) 다. 사설 IP가 아니다
  • 연동 솔루션을 사용한다면 솔루션 업체 서버 IP가 포함돼 있다
  • 테스트 환경에서 먼저 검증한 뒤 라이브에 적용했다

확인 방법 — 서버에서 curl https://api.ipify.org로 실제 아웃바운드 IP를 확인하고 등록값과 대조하세요.

자세한 내용: API 키 접근 정책

링크 복사4. 웹훅 서명을 검증하고, 콜백을 https로 받아요

웹훅은 외부에서 상점 서버로 들어오는 요청이에요. 검증 없이 처리하면 위조된 결제 완료 통보로 상품이 나갈 수 있어요.

통과 기준

  • 웹훅 수신 URL이 https다 (http도 허용하지만 https를 권장해요)
  • 방화벽에서 토스페이먼츠 인바운드 IP와 웹훅 포트를 허용했다
  • 웹훅을 받으면 10초 안에 200을 응답한다 (처리는 비동기로). 응답이 없으면 최대 7회 재전송돼요
  • 서명이 제공되는 이벤트는 서명을 검증한 뒤에만 처리한다
  • 서명 검증에 실패하면 요청을 거부한다 (로그만 남기고 처리하면 안 돼요)
  • tosspayments-webhook-transmission-id로 중복 처리를 막고 있다
  • 웹훅 본문의 금액·주문번호를 그대로 사용하지 않고, 결제 조회 API로 교차 확인한다. 이때 orderId·totalAmount와 함께 mId도 같이 대조한다

마지막 항목이 실질적으로 가장 중요해요. 서명이 제공되지 않는 이벤트도 있으니 결제 조회 API 교차 확인이 기본 방어선이에요.

자세한 내용: 웹훅 이벤트

링크 복사5. 연동 솔루션에 맡긴 범위를 파악하고 있어요

호스팅사·연동 솔루션·외주사를 통해 연동했다면, 시크릿 키가 상점이 통제하지 못하는 서버에 저장돼 있을 수 있어요. 어디에 무엇이 있는지 모르면 사고가 나도 대응할 수 없어요.

통과 기준 — 아래에 답할 수 있어야 해요.

  • 상점의 시크릿 키를 보관하고 있는 외부 주체가 누구인지 안다
  • 그 주체가 키를 어떻게 보관하는지 확인했다
  • 결제 API를 실제로 호출하는 서버가 상점 서버인지 호스팅사·연동 솔루션 서버인지 업체 서버인지 안다
  • 계약 종료 시 키를 재발급해 회수하는 절차가 있다
  • 업체 서버 IP가 접근 정책에 등록돼 있다 (3번 항목과 연결)

계약이 끝난 업체가 키를 알고 있는 상태로 남아 있는 경우가 실제로 있어요. 계약 종료는 키 회수 사유예요.

자세한 내용: 호스팅사·연동 솔루션을 이용할 때

링크 복사점검 결과 정리

항목통과미흡조치 예정일
1. 시크릿 키 서버 보관
2. 테스트·라이브 키 분리
3. API 키 접근 정책 등록
4. 웹훅 서명 검증·https
5. 연동 솔루션 위탁 범위 확인

링크 복사오픈 후에도 주기적으로 확인해요

주기점검 항목
분기 1회5. 위탁 범위 변동 확인
서버 증설·이전 시3. 접근 정책 IP 갱신
상시API 로그 모니터링

링크 복사관련 문서