테스트 환경

토스페이먼츠의 테스트 환경은 개발 과정에서 동일한 결제 경험을 하면서 실제 금액은 지불되지 않도록 지원하는 환경입니다.

이 페이지에서는 테스트 환경에서 개발할 때 유용하게 사용할 수 있는 기능, 그리고 라이브 환경과 다르게 동작하는 경우들을 알아봅니다.

테스트 환경에서 연동하기

테스트 키 준비

토스페이먼츠 계정이나 사업자등록번호가 아직 없어도 문서에서 제공하는 테스트 키를 사용해서 연동 개발을 바로 시작할 수 있습니다.

테스트 키를 사용해서 개발을 마친 뒤 계약을 통해 라이브 키를 발급 받을 수 있습니다. 라이브 키를 이용해서 실제로 결제가 되는 것을 확인해보세요.

테스트용 결제창

테스트 키를 사용해서 결제창을 연동하면 실제로 결제가 되지 않는 테스트용 결제창이 열립니다.

아래와 같이 '실제 결제가 되지 않는 테스트입니다.'라는 안내 문구가 보인다면 테스트용 결제창이니 안심하고 결제 테스트를 진행해도 됩니다.

이미지

가상 결제 승인

테스트 환경에서는 신용카드 정보나 휴대폰 번호와 같은 실제 정보를 이용해서 결제해도 결제 승인은 가상으로 이루어집니다. 따라서 결제 승인 요청에 대한 응답이 성공으로 돌아오더라도 내 결제 수단에서 빠져나가는 금액은 없습니다.

테스트 코드 헤더 사용하기

요청 헤더에 TossPayments-Test-Code 필드를 추가하면 특정 에러가 났을 때와 같이 예상된 시나리오를 직접 발생시켜 처리해 볼 수 있습니다.

TossPayments-Test-Code 헤더 필드는 테스트 환경에서만 사용할 수 있습니다. 테스트 키를 사용해주세요. 라이브 환경에서는 테스트 코드 헤더가 무시됩니다.

아래와 같이 요청 헤더에 테스트 코드 헤더 필드를 추가하고 테스트 할 에러 코드를 {TEST_CODE}에 추가해주세요. {TEST_CODE}에는 응답으로 나갈 수 있는 에러 코드 전체를 사용할 수 있습니다.

TossPayments-Test-Code: {TEST_CODE}

예를 들어 카드 정보 결제 API를 사용할 때 잘못된 카드 유효기간 정보를 넣은 경우를 테스트 하고 싶다면 아래와 같이 헤더를 추가해서 요청을 보내보세요.

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

요청 결과로 테스트 코드 INVALID_CARD_EXPIRATION에 해당하는 에러의 HTTP 상태 코드 400 Bad Request와 함께 에러 메시지가 돌아옵니다.

에러
{
"code": "INVALID_CARD_EXPIRATION",
"message": "카드 정보를 다시 확인해주세요.(유효기간)"
}
JSON

만약 유효하지 않은 테스트 코드로 요청을 보내면 HTTP 상태 코드 400 Bad Request와 함께 INVALID_TEST_CODE 에러가 내려갑니다.

라이브 환경과 다른 경우 알아보기

테스트 환경에서 API 사용, 인증 과정, 지원하는 결제 수단 등이 라이브 환경과 다른 경우를 알아봅니다.

결제 수단 등록 과정

  • 카드 번호

    테스트 환경에서 카드 자동 결제를 등록할 때는 카드 번호의 앞 여섯자리(BIN 번호)만 유효해도 자동 결제가 등록됩니다. 라이브 환경에서는 전체 카드 번호가 유효해야 등록이 가능합니다.

  • 휴대폰 인증

    테스트 환경에서 카드 자동 결제를 등록할 때는 휴대폰 본인 인증 과정을 거치지 않습니다. 휴대폰 인증은 라이브 환경에서만 사용할 수 있습니다.

계좌이체 정보 인증 생략

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

휴대폰 결제 테스트 미제공

테스트 환경의 휴대폰 결제는 본인 인증 서비스를 사용할 수 없어 결제 과정을 끝까지 진행할 수 없습니다. 휴대폰 본인 인증 서비스가 가능한 라이브 환경에서 전체 결제 과정을 진행해보세요.

가상의 상품권 PIN 번호 사용시 금액 정보 고정

게임 문화 상품권 결제 테스트에서 실제 PIN 번호가 아닌 가상의 값을 넣어 테스트 할 수 있습니다. 사용 가능한 금액으로는 항상 10,000원을 보여줍니다.

간편결제 결제 수단 제한

테스트 환경에서는 간편결제 수단으로 토스페이만 제공합니다. 기타 다른 간편결제(삼성페이, 페이코 등)은 라이브 환경에서 테스트 할 수 있습니다.

영수증 발행 제한

테스트 환경에서 이루어진 결제의 매출 전표(영수증)와 현금영수증은 발행되지 않습니다.

매출 전표는 Payment 객체 하위의 card > receiptUrl, 현금영수증은 cashReceipt > receiptUrl 필드에 링크가 생성되지만 실제로 확인할 수 있는 데이터는 제공되지 않습니다.

정산 기록 조회 제한

정산 조회 API의 응답으로 돌아오는 정산 기록은 라이브 환경에서만 조회할 수 있습니다. 테스트 환경에서는 정산 배치(Batch, 일괄처리) 프로그램이 실행되지 않아 정산 기록이 없는 것으로 조회됩니다.

가상계좌 입금・취소 액션 제공

테스트 환경에서 발급된 계좌 정보로 직접 입금할 수 없지만, 개발자센터의 테스트 거래내역 페이지에서 제공하는 입금・취소 이벤트를 실행하면 실제 동작과 동일하게 테스트 할 수 있습니다.

가장 오른쪽 액션 컬럼의 액션 > 입금처리/취소를 선택해보세요.

이미지

플랫폼·브라우저 환경 테스트하기

개발 연동 후 상점에서 지원할 플랫폼 및 브라우저 환경을 모두 테스트해야 합니다. 지원할 모든 환경에서 결제창이 잘 열리는지, 결제와 결제 취소가 정상적으로 이루어지는지 확인해주세요.

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

IE를 제외한 모든 브라우저에서 아래와 같은 형태의 카드 결제창이 실행됩니다. IE에서는 이전 버전의 카드 결제창이 실행됩니다.

카드 신규 결제창 예시 이미지

결제창이 실행되었다면 버튼이나 체크 박스 등 클릭할 수 있는 요소가 문제없이 클릭되는지 확인해보세요.

내용이 도움 되셨나요?
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기