토스페이먼츠 API를 사용할 때 필요한 인증 키를 알아봅니다.
토스페이먼츠 API에 요청을 보낼 때는 인증이 반드시 포함되어야 합니다. 토스페이먼츠 홈페이지에 가입한 뒤 해당 계정으로 발급된 고유한 API 키를 사용해서 인증합니다.
계정이 없더라도 아래 테스트 키를 사용해서 테스트 할 수 있습니다.
다른 준비 없이 문서에서 제공하는 아래 테스트 키를 사용해서 테스트 요청을 보낼 수 있습니다.
클라이언트 키는 브라우저에서 결제창을 연동할 때 사용합니다.
test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq
시크릿 키는 토스페이먼츠 API를 호출할 때 사용되는 키입니다. 브라우저에 노출되면 안됩니다.
test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R
토스페이먼츠 개발자센터나 홈페이지에 로그인하면 로그인 한 계정의 개발 테스트 키로 문서의 키 값이 변경됩니다.
먼저 토스페이먼츠에 가입해야 합니다. 가입한 계정으로 개발자센터에 로그인 하면 다른 절차 없이 테스트 상점의 API 키를 사용해서 테스트 연동을 시작할 수 있습니다.
내 상점의 API 키를 발급받아 사용하려면 계약으로 상점아이디(MID)를 발급 받아야 합니다. 상점아이디를 발급받았다면 개발 정보 페이지에서 내 상점의 개발 연동 페이지에서 상점용 API 키를 확인할 수 있습니다.
개발 중이라면 테스트 API 키를, 실제로 고객의 결제를 받고 싶다면 라이브 API 키를 사용하세요. 테스트 API 키를 사용하면 실제로 결제가 되지 않는 테스트 요청이기 때문에 개발 과정에서 편리하게 결제 연동 테스트를 할 수 있습니다. 테스트 키는 test_
로 시작합니다.
접근 방법 | 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 | 잘못된 요청입니다. : 를 포함해 인코딩해주세요. |