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 | UNAUTHORIZED_KEY | 인증되지 않은 시크릿 키 혹은 클라이언트 키입니다. |
인증(Authorization)
토스페이먼츠 API에는 다음과 같은 HTTP 헤더가 포함되어야 합니다.
Authorization: Basic dGVzdF9za19PeUwwcVo0RzFWT0xvYkI2S3d2cm9XYjJNUVlnOg==
위 예시에서 Basic은 인증 방식을 뜻합니다.
Basic 뒤에 오는 문자열은 시크릿 키와 콜론(:)을 합친 값 {SECRET_KEY}:을 base64로 인코딩한 값입니다. 인코딩 할 때 시크릿 키 뒤에 콜론을 빠트리지 않도록 주의하세요.
Basic 인증 방식이란
Authorization: Basic base64({USERNAME}:{PASSWORD})
Basic 인증 방식은 HTTP의 기본 인증 방식 중 하나로, 클라이언트에서 base64로 인코딩된 사용자명/비밀번호 쌍을 자격 증명(credentials) 값으로 사용합니다. 사용자명과 비밀번호는 콜론으로 구분해서 {USERNAME}:{PASSWORD}로 넣어줍니다.
토스페이먼츠 API는 사용자명에 시크릿 키를 넣어 사용하고, 비밀번호는 사용하지 않습니다. 따라서 아래와 같이 발급받은 시크릿 키에 콜론을 합친 {SECRET_KEY}:을 base64로 인코딩한 값을 넣어주면 됩니다.
Base64로 인코딩한 정보는 쉽게 디코딩이 가능합니다. 반드시 HTTPS/TLS와 함께 사용해주세요.
HTTP 프로토콜
HTTPS만 사용합니다
토스페이먼츠 API는 HTTPS로 호출해야 합니다.
HTTPS는 HTTP의 보안(Secured)버전입니다. HTTP로 주고 받는 데이터는 암호화되지 않은 평문(plaintext)이기 때문에 개인 정보가 유출될 수 있습니다. 따라서 고객의 결제 정보와 개인 정보를 보호하는 보안을 강화한 프로토콜인 HTTPS를 사용해야 합니다.
TLS 버전 1.2 이상을 지원합니다
TLS(전송 계층 보안)는 안전한 통신 프로토콜입니다. 토스페이먼츠 API는 TLS 버전 1.2 이상만 지원합니다.
TLS 1.2 미만의 SSL/TLS 버전은 보안이 취약하여 지원하지 않습니다. 상점 서버의 HTTP 클라이언트 환경이 TLS 1.2 이상을 지원하는지 확인해주세요.
응답 처리
토스페이먼츠 API의 성공 여부는 HTTP 상태 코드로 전달합니다. 모든 API 응답, 요청 본문(body)은 JSON 포맷입니다. 따라서 응답 헤더에는 다음과 같이 Content-Type이 포함됩니다.
Content-Type: application/json
응답 HTTP 코드 목록
| HTTP 상태 코드 | 설명 |
|---|---|
200 - OK | 요청이 성공적으로 처리되었습니다. |
400 - Bad Request | 요청을 처리할 수 없습니다. 필수 파라미터를 보내지 않았거나, 파라미터 포맷이 잘못되면 이 응답이 돌아올 수 있습니다. |
403 - Forbidden | 시크릿 키 없이 요청하거나 사용한 시크릿 키가 잘못되었습니다. |
404 - Not Found | 요청한 리소스가 존재하지 않습니다. |
500 - Server Error | 토스페이먼츠 서버에서 에러가 발생했습니다. |
에러 객체
요청이 정상적으로 처리되지 않으면 응답으로 HTTP 상태 코드와 함께 아래와 같은 에러 객체가 돌아옵니다.
{
"code": "NOT_FOUND_PAYMENT",
"message": "존재하지 않는 결제 입니다."
}
code: 에러 타입을 보여주는 에러 코드입니다.message: 에러 메시지입니다. 에러 발생 이유를 알려줍니다.
방화벽 설정
방화벽은 외부의 신뢰할 수 없는 네트워크가 내부 네트워크에 접근하지 못하도록 하는 보안 시스템입니다.
특정 포트나 IP에서 들어오는 요청을 필터링하거나, 사용자 인증 요청, 프록시, 주소변환기능(NAT) 등의 방법이 있습니다.
포트 번호를 허용하세요
1. API 요청을 위한 443 포트
상점 서버에서 토스페이먼츠 서버에 요청을 보내려면 HTTPS로 접근할 수 있는 443 포트가 허용되어 있어야 합니다.
2. 가상계좌 웹훅 URL 포트
가상계좌에 입금이 확인되거나 취소가 발생하면 토스페이먼츠 서버에서 상점 서버로 결제 처리에 필요한 데이터를 전송합니다. 방화벽 설정에서 가상계좌 웹훅 URL에 지정된 포트 번호로 인바운드 트래픽(Inbound Traffic)을 허용해주세요.
IP 접근 제어 목록에 추가해주세요
상점 서버에서 IP 접근 제어 목록(ACL, Access Control List)로 트래픽을 분류해 허용하거나 거부하면, 토스페이먼츠의 IP 주소를 허용해주세요.
다음 IP에 접근할 수 있도록 허용해주면 정상적으로 인바운드 요청이 전송됩니다.
- 13.124.18.147
- 13.124.108.35
- 3.36.173.151
- 3.38.81.32