테스트 환경

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

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

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

토스페이먼츠와 계약하면 상점용 테스트 키, 라이브 키를 발급받습니다. 상점용 테스트 키는 상점에서 계약한 결제수단만 테스트할 수 있습니다. 계약하지 않은 결제수단은 테스트할 수 없습니다.

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

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

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

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

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

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

TossPayments-Test-Code: {TEST_CODE}

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

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' \

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

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

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

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

• 카드 번호

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

• 휴대폰 인증

  테스트 환경에서 카드 자동결제를 등록할 때는 휴대폰 본인 인증 과정을 거치지 않습니다. 본인인증창이 뜨면 인증번호로 000000을 입력하세요. 휴대폰 인증은 라이브 환경에서만 사용할 수 있습니다.

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

테스트 환경에서 모든 통신사의 휴대폰 결제를 지원합니다. 실제로 결제가 일어나지 않습니다.

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

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

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

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

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

테스트 환경에서 발급된 계좌로 직접 입금할 수 없지만, 개발자센터의 테스트 거래내역 페이지에서 가장 오른쪽 컬럼의 입금처리・취소를 선택해보세요. 실제 동작과 동일하게 테스트 할 수 있습니다.

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

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