자주 묻는 질문

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

개발 환경

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

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

테스트 환경

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

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

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

콜백

Q. 가상계좌 테스트 중인데, 입금 콜백 요청이 도착하지 않아요.

먼저 콜백 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] 공인인증서 폐기됨(재발급 후 결제요망)"
}
  • HTTP 상태 코드는 항상 500으로 내려갑니다.
  • code: FAILED_INTERNAL_SYSTEM_PROCESSING
  • message: [구 모듈 에러코드] 구 모듈 에러메시지

기타

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

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

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

API v1.0을 기준으로 버전이 올라감에 따라 응답 내용이 달라집니다. 홈페이지 개발 정보 페이지에서 API 응답 버전을 변경한 뒤 요청을 보내보면서 변경되는 응답 필드를 직접 살펴보세요.

현재 문서에서 보여주는 모든 응답 예시는 최신 버전인 v1.3을 기준으로 합니다. 아래에서 버전 별로 달라지는 필드 정보를 확인해보고, 필요한 버전을 선택해 사용하세요.

v1.3

  • 추가된 필드
    • transactionKey: 거래 건에 대한 고유한 키 값
    • orderName: 결제에 대한 주문명
    • suppliedAmount: 공급가액
    • vat: 부가세
    • cultureExpense: 문화비 여부
    • taxAmount: cancels 객체 내부에 포함되는 과세금액

v1.2

응답 버전 1.2 에서는 응답 버전 정보와 결제 타입, 간편결제로 결제한 경우 간편결제 타입을 명시하는 easyPay 필드를 확인할 수 있습니다. 데이터가 중복되어 제거된 필드들도 살펴보세요.

  • 추가된 필드
    • version: 응답 버전 정보
    • type: 결제 타입 (NORMAL: 일반결제, BILLING: 자동결제(빌링), CONNECTPAY: 커넥트페이 결제)
    • easyPay: 간편결제로 결제한 경우 간편결제 타입(토스결제, 페이코, 삼성페이)
  • 제거된 필드
    • useDiscount: 즉시 할인 여부 (discount 로 대체)
    • discountAmount: 즉시 할인 금액 (discount 로 대체)
    • useCashReceipt: 현금영수증 여부 (cashReceipt 로 대체)

v1.1

응답 버전 1.1 에서는 계좌이체 정보를 담은 transfer 필드와 가상계좌 정보를 담은 객체 내부에 계좌 타입을 나타내는 accountType이 추가된 결제승인 응답을 확인할 수 있습니다. 계좌이체를 결제수단으로 사용하거나 가상계좌를 발급할 때 계좌 타입을 선택할 수 있는 가맹점에서는 응답 버전을 1.1로 설정하세요.

  • 추가된 필드
    • transfer: 계좌이체 승인 정보
    • accountType: virtualAccount 객체 내부에 포함되는 계좌 타입 (일반, 고정)
  • 더 궁금한 내용이 있나요?자주 묻는 질문
  • 코드 샘플을 참고하세요TossPayments GitHub
  • 기술지원이 필요한가요?디스코드 채팅|이메일 보내기