API 사용하기

토스페이먼츠 API를 사용하기 위해 필요한 키 정보와 보안 및 인증 방식에 대해 자세히 알아봅니다.

인증을 위한 API 키 준비

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

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

테스트용 키로 바로 시작하기

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

클라이언트 키

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

test_ck_OEP59LybZ8Bdv6A1JxkV6GYo7pRe

시크릿 키

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

test_ak_ZORzdMaqN3wQd5k6ygr5AkYXQGwy

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

가맹점용 API 키 발급받기

가맹점용 API 키를 발급받아 사용하려면 먼저 토스페이먼츠 홈페이지에 가입해야 합니다.

가입한 계정으로 로그인 한 뒤 홈페이지 오른쪽 상단의 내 상점 > 개발 정보 페이지로 진입하면, 상점아이디(MID)에 따라 발급된 가맹점의 테스트 API 키와 라이브 API 키를 확인할 수 있습니다.

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

API 키 종류

접근API 키 종류설명실결제 여부대시보드 기록유의사항
내 상점 > 개발 정보라이브 키*실제 가맹점 어플리케이션에 사용합니다.실결제가 이루어집니다.
테스트 키테스트용으로 사용합니다.상점관리자에 결제기록이 남습니다.
내 상점 > 개발 테스트테스트 키테스트용으로 사용합니다.상점관리자에 결제기록이 남지 않습니다.
문서테스트 키테스트용으로 사용합니다.홈페이지에 로그인 했을 때와 아닐 때 값이 다르니 유의하세요. 로그인하면 내 상점 - 개발 테스트의 API 키와 동기화 됩니다. 상점관리자에 내역이 남지 않습니다.

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

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

오류 코드

HTTP 상태코드설명
400 - INVALID_CLIENT_KEY잘못된 클라이언트 연동 정보 입니다.
400 - INVALID_API_KEY잘못된 API 연동 정보 입니다.
403 - UNAUTHORIZED_KEY인증되지 않은 시크릿 키 혹은 클라이언트 키입니다.

인증(Authorization)

토스페이먼츠 API에 대한 모든 요청에는 다음과 같은 HTTP 헤더가 포함되어야 합니다.

Authorization: Basic dGVzdF9za19PeUwwcVo0RzFWT0xvYkI2S3d2cm9XYjJNUVlnOg==

문자열은 username:password 값을 base64로 인코딩한 값입니다. 토스페이먼츠 API는 username에 시크릿 키를 넣어 사용하고 password 는 사용하지 않습니다. 따라서 발급받은 시크릿 키에 콜론(:)을 합쳐 base64로 인코딩한 값을 사용합니다. Authorization 값에 포함된 Basic은 인증 방식을 뜻합니다.

Basic 인증 방식이란

Basic Authorization은 HTTP의 기본 인증 방식 중 하나입니다. 클라이언트에서 Basic 뒤에 공백과 base64로 인코딩 된 문자열이 포함된 Authorization 헤더를 추가해서 요청을 보냅니다.

Authorization: Basic {{base64(username:password)}}

Base64로 인코딩한 정보는 쉽게 디코딩이 가능합니다. 반드시 HTTPS/TLS와 함께 사용해주세요.

HTTP 프로토콜

HTTPS만 사용합니다

토스페이먼츠 API 엔드포인트에 대한 모든 요청은 HTTPS로 이루어져야 합니다.

HTTPS는 HTTP(HyperText Transfer Protocol)의 보안(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시크릿 키 없이 요청하거나 사용한 시크릿 키가 잘못된 경우입니다.
500 - Server Error토스페이먼츠의 서버에 에러가 발생한 경우입니다.
404 - Not Found요청한 리소스가 존재하지 않는 경우입니다.

오류 객체

요청에 오류가 발생하면 응답으로 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)을 통해 트래픽을 분류해 허용하거나 거부하는 경우, 토스페이먼츠의 NAT(네트워크 주소 변환, Network Address Translation) IP 주소를 허용해주세요.

다음 IP에 접근할 수 있도록 허용해주면 정상적으로 인바운드 요청이 전송됩니다.

  • 13.124.18.147
  • 13.124.108.35
  • 3.36.173.151
  • 3.38.81.32
  • 더 궁금한 내용이 있나요?자주 묻는 질문
  • 코드 샘플을 참고하세요TossPayments GitHub
  • 기술지원이 필요한가요?디스코드 채팅|이메일 보내기