Version 1
SDK v1은 더 이상 업데이트되지 않습니다. 토스페이먼츠 SDK v2 연동을 추천합니다.
토스페이먼츠가 처음이라면 아래 가이드를 참고해서 연동을 준비하세요.
테스트 키로 연동할 때 실제 결제 정보(카드 번호, 휴대폰 번호 등)를 사용해도 결제 승인은 가상으로 이루어져요. 따라서 테스트 환경에서는 결제 승인에 성공해도 내 결제수단에서 빠져나가는 금액은 없어요.
테스트 환경이 라이브 환경과 달라서 주의해야 할 점이에요.
- 유효한 카드 번호로 테스트해도 실제로 결제가 되지 않습니다.
- 테스트용 해외 카드 번호는 해외결제 가이드에서 확인하세요.
- 토스페이, 네이버페이, 애플페이, 삼성페이, SSG페이, 엘페이, 핀페이는 개발 연동 체험 상점 및 MID 테스트 키로 연동할 수 있습니다.
- 카카오페이는 계약 이후에 MID로 발급받는 상점용 테스트 키로만 연동할 수 있습니다.
- 애플페이는 iPhone 및 Mac Safari 에서만 노출돼요.
- 페이코는 테스트 키로 연동할 수 없어요. 라이브 키로 테스트하세요.
- 테스트 환경에서는 가상계좌번호 앞에 'X'가 붙습니다.
- 테스트 환경에서 발급된 계좌로 직접 입금할 수 없지만 테스트 결제내역 메뉴에서 입금처리를 할 수 있습니다.
- Payment 객체에 영수증 URL은 생성되지만 실제 데이터는 제공되지 않습니다.
- 영수증 샘플은 결제 결과 안내 가이드에서 확인하세요.
- 카드 번호의 앞 여섯 자리(BIN 번호)만 유효해도 자동 결제가 등록됩니다. 라이브 환경에서는 전체 카드 번호가 유효해야 등록됩니다.
- 휴대폰 본인 인증번호로
000000
을 입력하세요. 휴대폰 인증은 라이브 환경에서만 사용할 수 있습니다.
- 계좌번호, 비밀번호, 계좌 소유주 이름, 보안카드와 OTP 정보를 가상의 값으로 넣어 테스트할 수 있습니다. 다만 사용자의 공동 인증서는 실제로 인증이 되어야 합니다.
- 가상의 게임 문화 상품권 PIN 번호를 입력할 수 있습니다. 사용 가능한 금액은 항상 10,000원으로 표시됩니다.
- 정산 조회 API의 응답으로 돌아오는 정산 기록은 라이브 환경에서만 조회할 수 있습니다.
- 테스트 환경에서는 정산 기록이 없는 것으로 조회됩니다.
- 테스트 환경에서 잔액조회 API를 호출하면 응답으로
availableAmount
만 돌아옵니다. - 테스트 환경에서는 유효한 사업자번호로 법인사업자(
CORPORATE
) 셀러만 등록할 수 있어요. 셀러의 상태가KYC_REQUIRED
로 바뀔 수는 있지만 테스트 KYC 수행이 불가능하기 때문에APPROVED
상태로 바뀔 수는 없습니다. - 지급대행 요청 API를 라이브 환경에서 테스트하면 수수료가 부과됩니다.
- 테스트 환경에서 각 API는 분당 100 건의 요청 제한이 있습니다.
테스트 환경에서 에러를 재현하고 싶다면 토스페이먼츠 API 테스트 헤더를 사용하세요.
{TEST_CODE}
자리에 재현하고 싶은 에러 코드를 넣고 API를 실행하세요.test_
로 시작하는 테스트 API 키를 사용해주세요. 라이브 환경에서는 테스트 코드 헤더가 무시됩니다.
예를 들어, 카드 번호 결제 API에 잘못된 유효기간을 넣었을 때 돌아오는 응답을 보고 싶다면 아래와 같이 INVALID_CARD_EXPIRATION
를 테스트 헤더에 추가하세요.
-
개발자센터의 테스트 결제내역 메뉴로 이동하세요.
-
날짜 별, 결제수단 별로 결제내역을 조회할 수 있어요.
-
가상계좌 결제는 가장 오른쪽 컬럼에서 결제를 취소하거나 가상계좌 입금을 처리할 수 있어요.
- '취소' 를 선택하면 결제 취소 API를 호출하지 않고 테스트 결제를 취소할 수 있어요.
- '입금처리' 를 선택하면 가상계좌에 입금되는 액션을 테스트할 수 있어요.
라이브 환경의 결제내역은 상점관리자에서 확인할 수 있어요.
토스페이먼츠는 고객의 결제 정보와 개인 정보를 보호하기 위해 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 72 이상 - Edge 79 이상 - Firefox 64 이상 - Safari 13 이상 - Whale 1.6.81.8 이상 |
모바일 웹 | Chrome, Safari, 삼성 인터넷 |
모바일 앱 | Android, iOS |