API 사용하기

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

인증을 위한 API 키 준비

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

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

테스트 키로 바로 시작하기

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

클라이언트 키

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

test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq

시크릿 키

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

test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R

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

API 키 발급받기

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

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

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

API 키 종류

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

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

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

에러 코드

HTTP 상태 코드	에러 코드	에러 메시지
`400`	`INVALID_CLIENT_KEY`	잘못된 클라이언트 연동 정보 입니다.
`400`	`INVALID_API_KEY`	잘못된 시크릿키 연동 정보 입니다.
`401`	`INCORRECT_BASIC_AUTH_FORMAT`	잘못된 요청입니다. `:` 를 포함해 인코딩해주세요.