토스페이먼츠가 처음이라면 연동 준비를 위한 아래 가이드를 순서대로 따라해보세요.
- 준비하기: 토스페이먼츠 연동을 위한 API 키, 테스트 환경 이해, 방화벽 설정 등 연동 전에 꼭 참고해야 하는 정보를 알려드려요.
- 첫 API 호출하기: 발급받은 API 키로 첫 번째 API를 호출하고 API 요청・응답에 대해 이해해요.
- 결제 내역 확인하기: 호출한 API의 테스트 결제 내역을 개발자센터에서 확인해요.
개발자용 테스트상점과 문서에서 사용하는 키는 아래와 같아요. 테스트용 키는 앞에 test_
가 붙어 있어요.
- 클라이언트 키:
ck_
로 시작하는 클라이언트 키는 SDK 연동에 사용합니다.
test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq
- 시크릿 키:
sk_
로 시작하는 시크릿 키는 토스페이먼츠 API를 호출할 때 인증에 사용합니다. 시크릿 키는 외부에 절대 노출되면 안 됩니다.
test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R
회원가입 후 로그인하면 개발자센터에서 내 API 키를 볼 수 있어요. PG 계약, 사업자번호 발급 상태와 상관 없이 이메일 주소만으로 토스페이먼츠에 회원가입을 할 수 있어요.
내 개발정보에 진입하면 왼쪽 메뉴 상단에 계정과 API 키에 대한 정보가 있어요.
왼쪽 메뉴 상단에 내 상점 이름과 MID가 보인다면, 내 테스트 키나 라이브 키를 볼 수 있어요. 내 테스트 키나 라이브 키로 설정하면 내가 계약한 결제수단만 연동할 수 있어요. 예를 들어, 카드 결제만 계약했는데 가상계좌 결제를 시도하면 에러가 나요.
만약 위 이미지와 같이 왼쪽 메뉴 상단에 '개발자용 테스트상점'이 보이면 위에서 소개한 테스트 키와 같은 값이에요. '개발자용 테스트상점' 테스트 키로는 모든 결제수단을 연동해볼 수 있어요.
더 자세한 내용은 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' \
토스페이먼츠는 고객의 결제 정보와 개인 정보를 보호하기 위해 HTTPS 통신과 TLS 버전 1.2 이상만 지원해요.
서버에서 아래 토스페이먼츠 IP 주소를 허용해주세요. 더 자세한 내용은 방화벽 가이드에서 확인하세요.
IP 주소 | 방향 |
---|---|
13.124.18.147 | INBOUND |
13.124.108.35 | INBOUND |
3.36.173.151 | INBOUND |
3.38.81.32 | INBOUND |
토스페이먼츠 SDK가 지원하는 브라우저 환경이에요.
플랫폼 환경 | 브라우저 환경 |
---|---|
데스크탑 브라우저 | Chrome, Edge, Firefox, Safari, Whale |
모바일 웹 | Chrome, Safari, 삼성 인터넷 |
모바일 앱 | Android, iOS |