자주 묻는 질문

개발 환경부터 구 모듈 사용까지 토스페이먼츠 연동 과정에서 가질 수 있는 궁금증을 모아 소개합니다.

개발 환경

Q. 토스페이먼츠 결제 모듈의 개발 환경은 어떻게 되나요?

토스페이먼츠 결제 모듈은 JavaScript SDK와 HTTP API로 구성되어 특별히 개발 환경의 제한이 없습니다. JavaScript SDK를 실행할 수 있는 웹페이지와 API를 호출할 수 있는 서버만 있다면 개발 언어에 무관하게 연동을 시작할 수 있습니다.

테스트 환경

Q. 테스트 환경에서 가상계좌에 실제로 입금이 가능한가요?

테스트 환경에서 발급된 가상계좌로는 입금 할 수 없습니다. 대신 입금을 한 것처럼 동작하는 입금・취소 이벤트를 제공합니다.

더 자세한 내용은 테스트 환경 페이지에서 확인해보세요.

웹훅

Q. 가상계좌 테스트 중인데, 웹훅 이벤트가 도착하지 않아요.

먼저 웹훅 URL을 정확하게 입력하셨는지 다시 한 번 확인해주세요.

가맹점에서 사용하고 있는 네트워크의 방화벽 정책에 따라 웹훅이 정상적으로 도착하지 않을 수 있습니다. 방화벽 설정에서 웹훅 URL에 지정된 포트번호에 대한 인바운드 트래픽을 허용해주세요. 자세한 내용은 API 사용하기 페이지에서 확인해보세요

토스페이먼츠 웹훅은 JSON 포맷을 사용합니다. 가맹점 서버에서 JSON 요청을 처리할 수 있는지 확인해주세요.

Q. 가상계좌가 만료된 경우에 대한 웹훅을 받을 수 있나요?

가상계좌가 만료된 경우에는 별도 웹훅을 드리고 있지 않습니다.

가상계좌 웹훅은 가상계좌에 고객이 입금했거나 은행이나 계좌 문제로 입금된 금액이 취소되는 경우, 입금 후 주문 취소로 인해 입금이 취소된 경우와 같이 결제 상태가 변경된 경우에만 요청됩니다.

만료 시간은 가상계좌가 발급되는 시점에 정해지고, 이후에는 수정할 수 없습니다.

가상계좌 만료 이후에 주문을 취소하려면 가상계좌를 발급할 때 설정한 만료시간을 저장해 두었다가 그 시간까지 입금이 되지 않으면 자동으로 주문 취소를 할 수 있도록 작업을 추가하면 됩니다.

API 키

Q. 내 상점의 테스트 키와 개발 테스트의 테스트 키는 어떻게 다른가요?

결제 테스트 기록을 조회할 수 있는지 여부에 차이가 있습니다.

개발 테스트 키로는 결제 테스트 까지만 가능하고, 기록을 볼 수는 없습니다. 로그인 후 내 상점의 테스트 키로 결제 테스트 한 기록은 내 상점 현황 대시보드에서 확인할 수 있습니다.

Q. 내 상점의 테스트 키로 연동하려면 어떻게 해야 하나요?

먼저 토스페이먼츠 홈페이지에 가입해야 합니다.

가입한 계정으로 로그인 한 뒤 토스페이먼츠 홈페이지 > 내 상점 > 개발 정보에서 상점의 테스트용 클라이언트 키를 사용하면 됩니다.

자동 결제(Billing)

Q. 발급된 빌링키를 더이상 사용하지 않으려고 합니다. 어떻게 하면 되나요?

발급된 빌링키를 만료시키는 API는 제공되지 않습니다. 발급된 빌링키가 더이상 필요하지 않으면 가맹점 DB 등에서 삭제하고 더이상 사용하지 않으면 됩니다.

혹시 누군가가 빌링키 정보를 알고 있더라도 그에 맞는 customerKey가 없다면 결제가 불가능합니다. 빌링키를 사용한 결제는 빌링키를 발급할 때 같이 전달된 customerKey와 매핑이 되어있기 때문에, 결제 요청을 할 때 빌링키와 customerKey가 같이 전달되어야 결제가 진행됩니다.

구모듈

Q. 구 모듈을 사용하고 있는데, 새로운 모듈을 사용할 수 있나요?

사업자등록번호와 구 상점관리자에 등록된 이메일 주소를 입력하면 새로운 홈페이지 계정으로 연결해드리는 기능을 제공하고 있습니다. 토스페이먼츠 홈페이지에 로그인 한 뒤 기존 상점 불러오기를 이용해주세요.

Q. 구 모듈 에러 코드는 어떻게 표시 되나요?

에러 코드 페이지에서 소개되지 않은 구 모듈 에러 코드는 구 모듈 에러코드 페이지에서 확인할 수 있습니다.

구 모듈 에러 코드는 에러 객체message 값으로 전송됩니다.

예를 들어 다음과 같은 형태입니다.

{
"code": "FAILED_INTERNAL_SYSTEM_PROCESSING",
"message": "[0314] 공인인증서 폐기됨(재발급 후 결제요망)"
}
JSON
  • HTTP 상태 코드는 항상 500으로 내려갑니다.
  • code: FAILED_INTERNAL_SYSTEM_PROCESSING
  • message: [구 모듈 에러 코드] 구 모듈 에러메시지

기타

Q. 브랜드페이 연동에 필요한 리소스를 불러오기 위한 방화벽 설정이 있나요?

브랜드페이를 연동할 때 필요한 리소스를 불러올 수 있도록 방화벽 허용 목록(whitelist)에 아래 리소스 주소들을 추가해주세요.

  • https://api.tosspayments.com
  • https://event.tosspayments.com
  • https://static.toss.im
  • https://pages.tosspayments.com
  • polyfills-fe.toss.im
  • assets-fe.toss.im

Q. Android 11(API 수준 30) 이상인 앱에서 패키지 공개 상태 관리 대응은 어떻게 하나요?

권장하는 방식으로 구현했다면 별도의 대응은 필요하지 않습니다.

구현상 위와 같은 방식을 사용하기 어렵다면 아래와 같이 AndroidManifest.xml에 패키지 명을 추가해야 합니다.

<manifest package="com.example.game">
<queries>
<package android:name="com.example.store" />
<package android:name="com.example.services" />
</queries>
...
</manifest>

예외적으로 모든 앱을 찾거나(query) 실행해야 하는 경우가 있다면 아래와 같이 QUERY_ALL_PACKAGES 권한을 사용해서 모든 패키지를 허용할 수 있습니다.

<manifest>
<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" />
</manifest>

더 궁금한 점이 있다면 토스페이먼츠 기술지원팀 이메일이나 디스코드로 문의해주세요.

Q. 매출 전표(영수증)나 현금영수증은 어디서 확인할 수 있나요?

결제 승인, 취소 및 조회 API 응답으로 매출 전표나 현금영수증에 대한 페이지 주소를 제공합니다. 카드 매출 전표는 card > receiptUrl을, 현금영수증은 cashReceipt > receiptUrl 필드를 참고하세요.

Q. 개발 정보 페이지의 '응답 버전'은 어떤 기능인가요?

버전 1.0을 기준으로 버전이 올라감에 따라 응답 내용이 달라집니다. 릴리즈 노트에서 버전 별로 달라지는 필드 정보를 확인해보고, 필요한 버전을 선택해 사용하세요. 홈페이지 개발 정보 페이지에서 API 응답 버전을 직접 변경할 수 있습니다.

현재 결제 연동 문서에서 보여주는 모든 응답 예시는 범용적으로 사용할 수 있는 최신 버전인 v1.4를 기준으로 작성되어 있습니다.

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