API & SDK/API 키
목차

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

API 키 확인하기

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

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

    API 키 확인하기 1

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

    API 키 확인하기2

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

    개발자센터 API 키 페이지

로그인한 상태로 개발자센터 문서를 보면, 코드 예제의 API 개별 연동 키 값이 내 개발 연동 체험 상점 키로 바뀌어요. 테스트 결제내역, 웹훅을 사용해보세요.

API 키 이해하기

테스트 키와 라이브 키

테스트 키와 라이브 키

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

클라이언트 키와 시크릿 키

클라이언트 키와 시크릿 키

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

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

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

연동 키의 차이점

그래서 어떤 키를 사용하면 되나요? 간단히 말하자면 결제위젯 SDK를 사용하면 결제위젯 연동 키를 사용하고, 결제창・브랜드페이 SDK를 사용하면 API 개별 연동 키를 사용하세요.

결제위젯 연동 키

클라이언트 키

결제위젯 SDK를 초기화할 때 사용하세요. 일반 결제, 브랜드페이, 해외결제 서비스를 함께 사용해도 클라이언트 키는 하나만 필요해요.

시크릿 키

결제위젯 클라이언트 키로 생성한 모든 결제를 승인, 취소, 조회하고 싶을 때 사용하세요. API 버전은 2022-11-16으로 고정되어 있고 바꿀 수 없어요.

  • 코어 API: 결제 승인, 결제 취소, paymentKey로 결제 조회, 거래 조회, 정산 조회, 수동 정산 조회
  • 브랜드페이 API: 결제 승인

사용 방법

결제위젯 연동 키는 토스페이먼츠 전자결제 신청 이후에만 확인할 수 있어요. 신청 전에는 문서에 있는 테스트 키로 결제위젯을 연동해보세요.

결제위젯 연동 키

API 개별 연동 키

클라이언트 키

결제창 SDK 또는 브랜드페이 SDK를 초기화할 때 사용하세요. 자동결제(빌링), 결제창, 브랜드페이 등 서비스마다 다른 상점아이디(MID)에 각각 API 개별 연동 키가 발급돼요.

각 서비스에 맞는 연동 키를 사용하세요. 예를 들어, 브랜드페이 MID로 발급된 클라이언트 키로 결제창 SDK를 초기화하면 오류가 납니다.

시크릿 키

API 개별 클라이언트 키로 생성한 결제를 승인, 취소, 조회하고 싶을 때 사용하세요. 결제 외에 현금영수증, 지급대행과 같은 부가서비스 API를 사용할 때도 사용하세요.

사용 방법

1. 연동하는 결제 서비스의 상점아이디(MID)를 선택하세요.

2. 사용하고 싶은 API 버전을 선택하세요. 각 버전에 대한 정보는 릴리즈 노트 > API 업데이트에서 확인하세요.

3. 클라이언트 키, 시크릿 키를 복사해서 사용하세요.

API 개별 연동 키

API 키 에러

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