목차

토스페이먼츠 API를 사용할 때 필요한 인증 키를 알아봅니다.

인증을 위한 API 키 준비

토스페이먼츠 API에 요청을 보낼 때는 인증이 반드시 포함되어야 합니다. 토스페이먼츠 홈페이지에 가입한 뒤 해당 계정으로 발급된 고유한 API 키를 사용해서 인증합니다.

계정이 없더라도 아래 테스트 키를 사용해서 테스트 할 수 있습니다.

테스트 키로 바로 시작하기

다른 준비 없이 문서에서 제공하는 아래 테스트 키를 사용해서 테스트 요청을 보낼 수 있습니다.

클라이언트 키

클라이언트 키는 브라우저에서 결제창을 연동할 때 사용합니다.

test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq

시크릿 키

시크릿 키는 토스페이먼츠 API를 호출할 때 사용되는 키입니다. 브라우저에 노출되면 안됩니다.

test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R

토스페이먼츠 개발자센터나 홈페이지에 로그인하면 로그인 한 계정의 개발 테스트 키로 문서의 키 값이 변경됩니다.

API 키 발급받기

먼저 토스페이먼츠에 가입해야 합니다. 가입한 계정으로 개발자센터에 로그인 하면 다른 절차 없이 테스트 상점의 API 키를 사용해서 테스트 연동을 시작할 수 있습니다.

내 상점의 API 키를 발급받아 사용하려면 계약으로 상점아이디(MID)를 발급 받아야 합니다. 상점아이디를 발급받았다면 개발 정보 페이지에서 내 상점의 개발 연동 페이지에서 상점용 API 키를 확인할 수 있습니다.

개발 중이라면 테스트 API 키를, 실제로 고객의 결제를 받고 싶다면 라이브 API 키를 사용하세요. 테스트 API 키를 사용하면 실제로 결제가 되지 않는 테스트 요청이기 때문에 개발 과정에서 편리하게 결제 연동 테스트를 할 수 있습니다. 테스트 키는 test_로 시작합니다.

API 키 종류

접근 방법API 키 종류설명실결제 여부대시보드 기록유의사항
내 상점 > API 키라이브 키*실제 상점 어플리케이션에 사용합니다.OO실결제가 이루어집니다.
테스트 키테스트용으로 사용합니다.XO상점관리자에 결제 기록이 남습니다.
개발 테스트(테스트 상점) > API 키테스트 키테스트용으로 사용합니다.XX상점관리자에 결제 기록이 남지 않습니다.
문서테스트 키테스트용으로 사용합니다.XX개발자센터나 홈페이지에 로그인 했는지 여부에 따라 값이 다르니 유의하세요. 로그인하면 개발자센터의 상점 API 키와 동기화 되며, 상점관리자에 거래 내역이 남지 않습니다.

라이브 모드의 API 시크릿 키는 노출되면 안되는 정보입니다. GitHub나 클라이언트 코드 등 외부에서 볼 수 있는 곳에 추가하지 마세요.

API 키가 없거나 잘못된 값이라면 아래와 같은 에러가 응답으로 돌아옵니다.

에러 코드

HTTP 상태 코드에러 코드에러 메시지
400INVALID_CLIENT_KEY잘못된 클라이언트 연동 정보 입니다.
400INVALID_API_KEY잘못된 시크릿키 연동 정보 입니다.
401INCORRECT_BASIC_AUTH_FORMAT잘못된 요청입니다. : 를 포함해 인코딩해주세요.
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기