API 키

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

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

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

   

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

   

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

   

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

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

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

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

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

시크릿 키·보안 키는 개발자센터 API 키 페이지에서 직접 재발급할 수 있어요. 아래 상황에서 재발급하세요.

• 시크릿 키가 외부에 노출됐거나 노출이 의심될 때
• 정기 교체 정책에 따라 키를 바꿔야 할 때
• 결제 연동을 맡겼던 외주사·연동 솔루션과의 계약이 끝나 키를 회수해야 할 때
• 담당 개발자가 퇴사·이동해서 키를 알고 있는 사람이 바뀌었을 때

시크릿 키는 상점의 결제를 승인·취소·조회할 수 있는 자격증명이에요. 유출되면 실제 금전 손실로 이어질 수 있으니 의심 단계에서 교체하는 편이 안전해요.

1. 개발자센터에 로그인하고 상점을 선택하세요.
2. API 키 메뉴로 이동하세요. 화면 상단 탭에서 테스트/라이브 환경을 확인하세요. 환경별로 따로 재발급해야 해요.
3. 교체할 키의 재발급을 누르세요.
4. 신규 키가 발급되고, 기존 키는 만료 예정으로 표시돼요.
5. 신규 키를 서버 설정·시크릿 저장소에 반영하고 배포하세요.
6. 배포 후 결제·조회 API가 정상 응답하는지 확인하세요.
7. 기존 키로 들어오는 호출이 없는 것을 확인한 뒤 즉시 폐기하세요.

재발급하면 신규 키와 기존 키가 최대 2개까지 동시에 유효해요. 이 기간에 무중단으로 갈아 끼우면 돼요.

7일이 지나면 기존 키로 보낸 요청은 실패해요. 만료 전에 반드시 키 교체를 완료해 주세요.

재발급을 1회로 제한한 이유는 키가 3개 이상 발급되는 상황을 막기 위해서예요. 잘못 발급했더라도 기존 키가 만료될 때까지는 다시 재발급할 수 없으니, 재발급 버튼을 누르기 전에 교체 준비가 끝났는지 확인하세요.

교체 후 문제가 생겼을 때 대응 방법은 중첩 기간 이내인지 여부에 따라 달라져요.

• 중첩 기간(7일) 이내라면 기존 키가 아직 유효해요. 서버에서 설정을 기존 키로 되돌리고 재배포하면 즉시 복구돼요. 이때 신규 키는 그대로 두세요. 개발자센터에서 삭제할 수 있는 것은 만료 대기 중인 기존 키이고, 재발급은 기존 키가 만료될 때까지 1회로 제한되므로 신규 발급된 키를 삭제할 수는 없어요.
• 중첩 기간이 지났다면 기존 키는 이미 만료돼 되돌릴 수 없어요. 신규 키로 정상 동작하도록 고치는 것 외에 방법이 없어요.

그래서 만료 하루 전까지는 롤백 가능 상태를 유지하고, 그 사이에 결제·취소·조회·정산 경로를 모두 검증하는 것을 권장해요.

권장 교체 타임라인

호스팅사·연동 솔루션·외주 개발사를 통해 결제를 연동했다면, 시크릿 키가 내 서버가 아닌 곳에 저장돼 있을 수 있어요.

• 재발급 전에 반드시 해당 업체에 교체 일정을 알려주세요. 업체 측 반영이 7일 안에 끝나지 않으면 중첩 기간이 지나 결제가 멈춰요.
• 업체가 여러 상점의 키를 함께 관리하는 구조라면 반영에 시간이 더 걸려요. 최소 영업일 3일 전 통보를 권장해요.
• 계약이 종료된 업체가 있다면, 그 업체가 키를 알고 있던 시점 기준으로 교체하세요. 계약 종료는 키 회수 사유예요.
• 업체에 키를 전달할 때 메신저·이메일로 평문 전송하지 마세요. 개발자센터의 사용자 추가 기능으로 권한을 주고 직접 조회하도록 하는 편이 안전해요. 작업이 끝나면 권한을 회수하세요.

키가 실제로 유출돼 중첩 기간을 기다릴 수 없다면, 재발급 후 만료 대기 중인 기존 키를 직접 삭제할 수 있어요. 삭제할 때 결제 중단에 동의하는 체크가 필요해요. 기존 키를 쓰는 경로가 남아 있으면 그 즉시 실패하기 때문이에요.

즉시 폐기를 선택해야 하는 경우는 아래처럼 키가 외부에 공개된 것이 확인된 때예요. 이때는 결제 실패를 감수하더라도 폐기가 우선이에요.

• 공개 저장소에 커밋된 것을 확인했을 때
• 클라이언트 번들·앱에 포함된 것을 확인했을 때
• 로그·메신저·이메일로 유출된 것을 확인했을 때
• 토스페이먼츠로부터 키 유출 안내를 받았을 때