API & SDK/시작하기/API 키
목차

API 키는 클라이언트를 식별하는 역할을 해요. 토스페이먼츠는 API 키로 시스템에 접근하는 클라이언트의 인증 정보를 확인하고 올바른 응답을 내려줘요.

API 키 확인하기

회원가입 후 로그인하면 개발자센터에서 내 API 키를 볼 수 있어요. PG 계약, 사업자번호 없이 이메일 주소만으로 토스페이먼츠에 회원가입할 수 있어요.

개발자센터 API 키 페이지

토스페이먼츠에 로그인한 상태로 개발자센터 문서를 보면, 문서에 있는 코드 예제의 키 값이 내 개발자용 테스트 키로 바뀌어요. 회원가입・로그인 없이 문서 테스트 키로 연동할 수 있지만 테스트 결제내역은 확인할 수 없어요.

API 키 종류 이해하기

키 종류

토스페이먼츠 API 키는 결제위젯 연동 키, API 개별 연동 키가 있어요. 각 연동 키에는 테스트 클라이언트・시크릿 키 세트, 라이브 클라이언트・시크릿 키 세트가 있어요.

만약 결제위젯을 연동한다면 결제위젯 연동 키의 테스트 클라이언트 키와 테스트 시크릿 키로 테스트 연동을 하고, 나중에 라이브 키로 실제 결제를 내요.

자동결제를 연동한다면 API 개별 연동 키의 테스트 클라이언트 키와 테스트 시크릿 키로 테스트 연동을 하고, 나중에 라이브 키로 실제 결제를 내요.

연동 키

일반 결제, 키인 결제, 브랜드페이, 해외 간편결제 서비스를 사용할 때는 결제위젯 연동 키만 사용하면 돼요.

자동결제(빌링), 지급대행 등 다른 결제 서비스를 사용하면, 각 결제 서비스와 연결된 상점아이디(MID)와 API 개별 연동 키 세트가 따로 발급돼요. 사용하는 결제 제품과 연결된 연동 키를 사용하세요.

결제위젯 연동 키API 개별 연동 키
설명결제위젯으로 연동할 때 사용해요. 하나의 키로 여러 결제 서비스를 쉽게 추가하고, 사용할 수 있어요.결제위젯 연동이 아닌 SDK・API로 개별 연동하거나 운영 서비스를 연동할 때 사용해요. 상점아이디(MID)별로 다른 키를 사용해요.
용도일반 결제, 브랜드페이, 해외결제 서비스를 결제위젯으로 연동할 때 사용하세요.자동결제(빌링), 지급대행 등 기타 부가 서비스를 연동할 때 사용하세요.
상점아이디(MID)N개의 MID에 1개의 결제위젯 연동 키가 발급돼요. 연동하는 서비스와 상관없이 동일한 키를 사용할 수 있어서 편리해요.1개의 상점아이디(MID)에 1개의 API 개별 연동 키가 발급돼요. 연동하는 서비스와 연결된 MID의 키를 사용하는지 확인하세요.
클라이언트 키결제위젯 SDK를 초기화할 때 필요해요.결제창 SDK, 브랜드페이 SDK를 초기화할 때 필요해요.
시크릿 키- 코어 API: 결제 승인, 결제 취소, 결제 조회, 거래 조회, 정산 조회, 수동 정산 조회
- 브랜드페이 API: 결제 승인
- 코어 API: 모든 API
- 브랜드페이 API: 모든 API

클라이언트 키와 시크릿 키

토스페이먼츠 SDK 및 API는 각각 클라이언트 키, 시크릿 키로 클라이언트를 식별해요.

  • 클라이언트 키는 브라우저에서 토스페이먼츠 SDK를 연동할 때 사용해요. 결제위젯 클라이언트 키는 중간에 gck가 있고, API 개별 연동 키는 중간에 ck가 있어요.
  • 시크릿 키는 토스페이먼츠 API를 호출할 때 사용해요. 결제위젯 시크릿 키는 중간에 gsk가 있고, API 개별 연동 키는 중간에 sk가 있어요. 시크릿 키를 사용하는 방법은 인증 가이드에서 확인하세요.

클라이언트 키와 시크릿 키는 항상 ‘세트’로 묶여 있고, 한 세트로 써야 돼요. 세트가 아닌 키를 사용하거나 테스트 또는 라이브 키를 섞어 사용하면 INVALID_API_KEY 오류가 발생해요.

시크릿 키는 노출되면 안 됩니다. GitHub, 클라이언트 코드 등 외부에서 볼 수 있는 곳에 추가하지 마세요.

테스트 및 라이브 키

테스트 키로 연동하면 실제 결제 정보(카드 번호, 휴대폰 번호 등)를 사용해도 결제 승인은 가상으로 이루어지기 때문에 결제 승인에 성공해도 내 결제수단에서 빠져나가는 금액은 없어요. 테스트 환경과 라이브 환경의 차이는 테스트 환경 주의점에서 확인하세요.

토스페이먼츠와 PG 계약하기 전에는 개발 연동 테스트 상점 키로 연동하세요. 라이브 키는 계약이 완료되면 발급돼요. 계약 문의는 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 해주세요.

키 종류설명결제 여부발급 방법결제내역형식
개발 연동 테스트 상점모든 결제수단을 테스트할 수 있습니다. 결제 승인은 가상으로 이루어져요.X회원가입개발자센터 테스트 결제내역test_로 시작하는 문자열
상점용 테스트 키라이브 환경과 똑같이 계약한 결제수단만 테스트할 수 있습니다.X계약개발자센터 테스트 결제내역test_로 시작하는 문자열
상점용 라이브 키실제 서비스에 사용하세요. 결제 승인이 실제로 이루어져요.O계약상점관리자live_로 시작하는 문자열

상점용 테스트 키 및 라이브 키는 상점아이디(MID)로 계약한 결제수단만 연동할 수 있습니다. 예를 들어, 카드 결제만 계약했는데 가상계좌 결제를 요청하면 에러가 납니다.

API 키 에러

상태 코드에러 코드에러 메시지해결 방법
400INVALID_CLIENT_KEY잘못된 클라이언트 연동 정보 입니다.클라이언트 키 값을 다시 확인해주세요.
400INVALID_API_KEY잘못된 시크릿 키 연동 정보 입니다.클라이언트 키와 매칭된 시크릿 키를 사용하고 있는지 확인하세요.
401UNAUTHORIZED_KEY인증되지 않은 시크릿 키 혹은 클라이언트 키 입니다.클라이언트 키와 매칭된 시크릿 키를 사용하고 있는지 확인하세요. 시크릿 키 인코딩을 다시 확인하세요.
401INCORRECT_BASIC_AUTH_FORMAT잘못된 요청입니다. : 를 포함해 인코딩해주세요.시크릿 키 인코딩을 다시 확인하세요.
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기