API 키

토스페이먼츠 API 키는 클라이언트 및 서버 요청을 확인하고 인증하는 역할을 해요. 요청자의 인증 정보를 확인하고 토스페이먼츠는 요청에 따른 올바른 응답을 내려줘요.

1. 개발자센터에 회원가입하고 로그인하세요. 이메일 주소만으로 토스페이먼츠에 회원가입할 수 있어요.

2. 전자결제 신청을 완료했다면, 상점을 선택하세요. 신청 전이라면 개발 연동 체험 상점의 일부 테스트 키만 확인할 수 있어요.

   

3. 개발자센터의 API 키 메뉴를 들어가서 필요한 키를 확인하세요.

   

4. 다른 사람에게 API 키를 공유해야 된다면 화면 왼쪽 하단에 있는 '사용자 추가하기'를 눌러서 권한을 추가하세요.

   

테스트 키는 test로 시작해요. 테스트 환경에서는 실제 결제 정보(카드 번호, 휴대폰 번호 등)를 사용해도 결제 승인은 가상으로 이루어져요. 결제수단에서 금액이 차감되지 않아요.

클라이언트 키와 시크릿 키는 항상 ‘세트’로 묶여 있고, 한 세트로 써야 돼요. 세트가 아닌 키를 사용하거나 테스트 또는 라이브 키를 섞어 사용하면 INVALID_API_KEY 오류가 발생해요. 클라이언트 키는 브라우저에서 토스페이먼츠 SDK를 초기화할 때 사용해요. 내 상점의 계약 정보, 결제 설정을 불러와요. 결제 클라이언트 키는 중간에 gck가 있고, API 개별 연동 키는 중간에 ck가 있어요.

시크릿 키는 토스페이먼츠 API를 호출할 때 사용해요. ID와 비밀번호 대신 시크릿 키로 API 요청을 인증해요. 결제 시크릿 키는 중간에 gsk가 있고, API 개별 연동 키는 중간에 sk가 있어요.

• 시크릿 키를 사용하는 방법은 인증 가이드에서 확인하세요.
• 시크릿 키는 외부에 노출되면 안 돼요. GitHub, 클라이언트 코드 등 외부에 보이는 곳에 추가하지 마세요.

그래서 어떤 키를 사용하면 되나요? 간단히 말하자면 결제위젯 SDK를 사용하면 주문서형, 결제창형 연동 키를 사용하고, 결제창(구버전)・브랜드페이 SDK를 사용하면 API 개별 연동 키를 사용하세요.

API 키에 허용 IP를 지정해두면 시크릿 키가 유출되어도 등록하지 않은 IP에서는 API를 호출할 수 없어서 안전해요. 개발자센터의 API 키 접근 정책 메뉴에서 정책을 만들어 API 키에 연결하세요.

결제 취소, 지급대행 요청처럼 특정 서버에서만 호출하는 API를 안전하게 관리하고 싶다면 접근 정책을 등록해보세요.

1. 개발자센터의 API 키 접근 정책 메뉴를 열고 등록하기를 누르세요.

2. 아래 정보를 입력하세요.

   필드	설명
   정책 이름	최대 20자. 예: 배치 서버
   정책 설명	최대 100자. 예: 정산 배치 전용
   허용할 IP 주소	서버의 공인 IP. 여러 개는 쉼표(,)로 구분하고, CIDR 표기(198.51.100.0/24)도 지원해요
   연결할 키	정책을 적용할 API 키를 골라주세요

3. 등록을 누르면 정책이 바로 적용되고, 연결한 키는 등록한 IP에서만 호출할 수 있어요. 이미 운영 중인 서버라면 IP를 잘못 등록해서 호출이 막히지 않도록 주의해서 적용하세요.

   

키가 유출됐거나 교체가 필요할 때는 개발자센터 API 키 페이지에서 직접 시크릿 키와 보안 키를 재발급할 수 있어요. 재발급하면 신규 키가 발급되고 기존 키는 만료 예정으로 표시돼서 7일 안에 무중단으로 갈아 끼울 수 있어요. 최대 2개 키가 공존하고 만료 전까지 1회만 재발급할 수 있어요.

• 재발급 대상: 결제 시크릿 키, API 개별 연동 시크릿 키·보안 키
• 클라이언트 키는 외부에 노출돼도 되는 공개 식별값이라 재발급 대상이 아니에요.
• 기존 키를 즉시 폐기하고 싶다면 재발급 후 만료 대기 중인 기존 키를 직접 삭제할 수 있어요. 삭제 시 결제 중단에 동의하는 체크가 필요해요.