목차

토스페이먼츠가 처음이라면 연동 준비를 위한 아래 가이드를 순서대로 따라해보세요.

  1. 준비하기: 토스페이먼츠 연동을 위한 API 키, 테스트 환경 이해, 방화벽 설정 등 연동 전에 꼭 참고해야 하는 정보를 알려드려요.
  2. 첫 API 호출하기: 발급받은 API 키로 첫 번째 API를 호출하고 API 요청・응답에 대해 이해해요.
  3. 결제 내역 확인하기: 호출한 API의 테스트 결제 내역을 개발자센터에서 확인해요.

API 키 이해하기

개발자용 테스트상점과 문서에서 사용하는 키는 아래와 같아요. 테스트용 키는 앞에 test_가 붙어 있어요.

  • 클라이언트 키: ck_로 시작하는 클라이언트 키는 SDK 연동에 사용합니다.
test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq
  • 시크릿 키: sk_로 시작하는 시크릿 키는 토스페이먼츠 API를 호출할 때 인증에 사용합니다. 시크릿 키는 외부에 절대 노출되면 안 됩니다.
test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R

내 API 키 확인하기

회원가입 후 로그인하면 개발자센터에서 내 API 키를 볼 수 있어요. PG 계약, 사업자번호 발급 상태와 상관 없이 이메일 주소만으로 토스페이먼츠에 회원가입을 할 수 있어요.

내 개발정보에 진입하면 왼쪽 메뉴 상단에 계정과 API 키에 대한 정보가 있어요.

왼쪽 메뉴 상단에 내 상점 이름과 MID가 보인다면, 내 테스트 키나 라이브 키를 볼 수 있어요. 내 테스트 키나 라이브 키로 설정하면 내가 계약한 결제수단만 연동할 수 있어요. 예를 들어, 카드 결제만 계약했는데 가상계좌 결제를 시도하면 에러가 나요.

토스페이먼츠 개발자센터 API 키

만약 위 이미지와 같이 왼쪽 메뉴 상단에 '개발자용 테스트상점'이 보이면 위에서 소개한 테스트 키와 같은 값이에요. '개발자용 테스트상점' 테스트 키로는 모든 결제수단을 연동해볼 수 있어요.

더 자세한 내용은 API 키 가이드에서 확인하세요.

토스페이먼츠에 로그인한 상태로 개발자센터 문서를 보면, 문서에 있는 코드 예제의 키 값이 내 테스트 키로 바뀌어요. 회원가입・로그인을 하지 않고 빠르게 테스트 연동을 하고 싶다면 문서에 있는 테스트 키를 사용해도 돼요. 다만 테스트 결제 내역은 내 키로만 확인할 수 있어요.

내 API 버전 정보 확인하기

내 API 키 아래에 API 버전을 확인하고 변경할 수 있는 기능이 있어요. 버전에 따라 요청 파라미터, 응답 내용이 변경될 수 있습니다. 릴리즈 노트에서 각 버전에서 변경된 필드 정보를 확인해 보고, 필요한 버전을 선택해 사용하세요.

API 문서 상단 왼쪽에서 API 버전을 선택할 수 있어요. 문서에서 보여주는 모든 응답 예시는 가장 최신 버전을 기준으로 작성되어 있습니다. 더 자세한 내용은 API 버전 정책을 참고하세요.

테스트 환경

테스트 키로 연동할 때 실제 결제 정보(카드 번호, 휴대폰 번호 등)를 사용해도 결제 승인은 가상으로 이루어져요. 따라서 테스트 환경에서는 결제 승인에 성공해도 내 결제수단에서 빠져나가는 금액은 없어요.

테스트 환경 주의점

테스트 환경이 라이브 환경과 달라서 주의해야 할 점이에요.

분류주의점
카드실제로 유효한 카드 번호로 테스트해도 결제가 되지 않습니다.
간편결제토스페이, 네이버페이는 모든 테스트 키로 연동할 수 있습니다. 카카오페이는 계약 후 발급받는 내 테스트 키로 연동할 수 있습니다. 페이코 등 기타 간편결제는 라이브 키로 테스트하세요.
* 네이버페이에 계좌를 등록하는 화면에서 로그인 화면이 나오면 테스트 계정(ID: admin /PW : vkdlsostuf!@# (파이낸셜123))을 사용하세요.
가상계좌계좌번호 앞에 'X'가 붙습니다. 테스트 환경에서 발급된 계좌로 직접 입금할 수 없지만, 개발자센터의 테스트 결제내역 메뉴에서 입금처리를 할 수 있습니다.
영수증영수증 URL은 생성되지만 실제 데이터는 제공되지 않습니다.
자동결제(빌링)카드 번호의 앞 여섯 자리(BIN 번호)만 유효해도 자동결제가 등록됩니다. 라이브 환경에서는 전체 카드 번호가 유효해야 등록됩니다.
휴대폰 본인 인증번호로 000000을 입력하세요. 휴대폰 인증은 라이브 환경에서만 사용할 수 있습니다.
계좌이체계좌번호, 비밀번호, 계좌 소유주 이름, 보안카드와 OTP 정보를 가상의 값으로 넣어 테스트할 수 있습니다. 다만 사용자의 공동 인증서는 실제로 인증이 되어야 합니다.
게임 문화 상품권가상의 게임 문화 상품권 PIN 번호를 입력할 수 있습니다. 사용 가능한 금액은 항상 10,000원으로 표시됩니다.
정산정산 조회 API의 응답으로 돌아오는 정산 기록은 라이브 환경에서만 조회할 수 있습니다. 테스트 환경에서는 정산 배치(Batch, 일괄처리) 프로그램이 실행되지 않아 정산 기록이 없는 것으로 조회됩니다.
지급대행- 테스트 환경에서 서브몰을 등록하면 account.holderName 필드는 김토페로 고정됩니다.
- 지급대행 요청 API는 실제 정산 금액이 지급되기 때문에 라이브 환경에서만 작동해요.

테스트 환경에서 에러 재현하기

테스트 환경에서 에러를 재현하고 싶다면 토스페이먼츠 API 테스트 헤더를 사용하세요.

TossPayments-Test-Code: {TEST_CODE}
  • {TEST_CODE} 자리에 재현하고 싶은 에러 코드를 넣고 API를 실행하세요.
  • test_ 로 시작하는 테스트 API 키를 사용해주세요. 라이브 환경에서는 테스트 코드 헤더가 무시됩니다.

예를 들어, 카드 번호 결제 API에 잘못된 유효기간을 넣었을 때 돌아오는 응답을 보고 싶다면 아래와 같이 INVALID_CARD_EXPIRATION를 테스트 헤더에 추가하세요.

curl --request POST \
--url https://api.tosspayments.com/v1/payments/key-in \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--header 'TossPayments-Test-Code: INVALID_CARD_EXPIRATION' \

테스트 코드 헤더는 토스페이먼츠 코어 API에서만 사용할 수 있습니다. 브랜드페이 API는 지원하지 않습니다.

방화벽 설정하기

토스페이먼츠는 고객의 결제 정보와 개인 정보를 보호하기 위해 HTTPS 통신과 TLS 버전 1.2 이상만 지원해요.

서버에서 아래 토스페이먼츠 IP 주소를 허용해주세요. 더 자세한 내용은 방화벽 가이드에서 확인하세요.

IP 주소방향
13.124.18.147INBOUND
13.124.108.35INBOUND
3.36.173.151INBOUND
3.38.81.32INBOUND

지원 브라우저

토스페이먼츠 SDK가 지원하는 브라우저 환경이에요.

플랫폼 환경브라우저 환경
데스크탑 브라우저Chrome, Edge, Firefox, Safari, Whale
모바일 웹Chrome, Safari, 삼성 인터넷
모바일 앱Android, iOS

다음: API 호출하기
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기