결제 운영
목차

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

테스트 키 준비

토스페이먼츠 개발자센터 API 키

개발자센터의 API 키 메뉴에서 테스트 클라이언트 키와 시크릿 키를 확인하세요.

  • 로그인했다면, 문서의 키 값도 내 테스트 키로 바뀌어요.
  • 로그인하지 않고 문서에 있는 테스트 키도 결제 연동에 사용할 수 있지만, 결제 내역을 확인할 수 없어요.

클라이언트 키는 SDK 연동에 사용됩니다.

test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq

시크릿 키는 토스페이먼츠 API Basic 인증에 사용됩니다. 시크릿 키는 외부에 절대 노출되면 안 됩니다.

test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R
  • 위 이미지와 같이 왼쪽 메뉴 상단에 '개발자용 테스트상점'이 보인다면, 테스트 키로 모든 결제수단을 연동할 수 있습니다. 문서에는 항상 '개발자용 테스트상점' 테스트 키가 보여요.

  • 왼쪽 메뉴 상단의 내 상점 이름과 MID가 보인다면, 테스트 및 라이브 키로 계약한 결제수단만 연동할 수 있습니다. 예를 들어, 카드 결제만 계약했는데 가상계좌 결제를 시도하면 에러가 나요.

  • 더 자세한 내용은 API 키 가이드에서 확인하세요.

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

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

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

결제수단 등록 과정

  • 카드 번호

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

  • 휴대폰 인증

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

계좌이체 정보 인증 생략

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

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

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

간편결제 결제수단 제한

토스페이, 네이버페이만 테스트 환경에서 연동할 수 있어요. 기타 다른 간편결제(삼성페이, 페이코 등)은 라이브 환경에서 테스트 할 수 있습니다.

영수증 발행 제한

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

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

정산 기록 조회 제한

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

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

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

이미지

테스트 코드 헤더 사용하기

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

TossPayments-Test-Code: {TEST_CODE}

예를 들어 카드 번호 결제 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' \

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

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

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

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

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

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

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

  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기