가이드/환경 설정하기
목차

Version 1

SDK v1은 더 이상 업데이트되지 않습니다. 토스페이먼츠 SDK v2 연동을 추천합니다.

토스페이먼츠가 처음이라면 아래 가이드를 참고해서 연동을 준비하세요.

테스트 환경

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

테스트 환경 주의점

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

카드
  • 유효한 카드 번호로 테스트해도 실제로 결제가 되지 않습니다.
  • 테스트용 해외 카드 번호는 해외결제 가이드에서 확인하세요.

간편결제
  • 토스페이, 네이버페이, 애플페이, 삼성페이, SSG페이, 엘페이, 핀페이는 개발 연동 체험 상점 및 MID 테스트 키로 연동할 수 있습니다.
  • 카카오페이는 계약 이후에 MID로 발급받는 상점용 테스트 키로만 연동할 수 있습니다.
  • 애플페이는 iPhone 및 Mac Safari 에서만 노출돼요.
  • 페이코는 테스트 키로 연동할 수 없어요. 라이브 키로 테스트하세요.

가상계좌
  • 테스트 환경에서는 가상계좌번호 앞에 'X'가 붙습니다.
  • 테스트 환경에서 발급된 계좌로 직접 입금할 수 없지만 테스트 결제내역 메뉴에서 입금처리를 할 수 있습니다.

영수증
  • Payment 객체에 영수증 URL은 생성되지만 실제 데이터는 제공되지 않습니다.
  • 영수증 샘플은 결제 결과 안내 가이드에서 확인하세요.

자동결제(빌링)
  • 카드 번호의 앞 여섯 자리()만 유효해도 자동 결제가 등록됩니다. 라이브 환경에서는 전체 카드 번호가 유효해야 등록됩니다.
  • 휴대폰 본인 인증번호로 000000을 입력하세요. 휴대폰 인증은 라이브 환경에서만 사용할 수 있습니다.

계좌이체
  • 계좌번호, 비밀번호, 계좌 소유주 이름, 보안카드와 OTP 정보를 가상의 값으로 넣어 테스트할 수 있습니다. 다만 사용자의 공동 인증서는 실제로 인증이 되어야 합니다.

게임 문화 상품권
  • 가상의 게임 문화 상품권 PIN 번호를 입력할 수 있습니다. 사용 가능한 금액은 항상 10,000원으로 표시됩니다.

정산
  • 정산 조회 API의 응답으로 돌아오는 정산 기록은 라이브 환경에서만 조회할 수 있습니다.
  • 테스트 환경에서는 정산 기록이 없는 것으로 조회됩니다.

지급대행
  • 테스트 환경에서 잔액조회 API를 호출하면 응답으로 availableAmount만 돌아옵니다.
  • 테스트 환경에서는 유효한 사업자번호로 법인사업자(CORPORATE) 셀러만 등록할 수 있어요. 셀러의 상태가 KYC_REQUIRED로 바뀔 수는 있지만 테스트 KYC 수행이 불가능하기 때문에 APPROVED 상태로 바뀔 수는 없습니다.
  • 지급대행 요청 API를 라이브 환경에서 테스트하면 수수료가 부과됩니다.

API 요청 제한
  • 테스트 환경에서 각 API는 분당 100 건의 요청 제한이 있습니다.

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

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

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

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

테스트 결제내역 확인하기

  1. 개발자센터의 테스트 결제내역 메뉴로 이동하세요.

  2. 날짜 별, 결제수단 별로 결제내역을 조회할 수 있어요.

  3. 는 가장 오른쪽 컬럼에서 결제를 취소하거나 가상계좌 입금을 처리할 수 있어요.

    • '취소' 를 선택하면 결제 취소 API를 호출하지 않고 테스트 결제를 취소할 수 있어요.
    • '입금처리' 를 선택하면 가상계좌에 입금되는 액션을 테스트할 수 있어요.

토스페이먼츠 테스트 결제내역

라이브 환경의 결제내역은 상점관리자에서 확인할 수 있어요.

방화벽 설정하기

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

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

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

지원 플랫폼·브라우저 환경

토스페이먼츠 SDK가 지원하는 플랫폼·브라우저 환경이에요. 토스페이먼츠 결제 서비스를 원활하게 이용하려면 최신 버전의 브라우저를 사용하는 것을 권장드려요. 최신 브라우저는 더 안전하고 안정적이기 때문에 결제 오류를 최소화할 수 있습니다.

플랫폼 환경브라우저 환경
데스크톱 브라우저- Chrome 72 이상
- Edge 79 이상
- Firefox 64 이상
- Safari 13 이상
- Whale 1.6.81.8 이상
모바일 웹Chrome, Safari, 삼성 인터넷
모바일 앱Android, iOS
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기