자주 묻는 질문

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

개발 환경

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

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

테스트 환경

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

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

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

웹훅

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

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

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

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

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

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

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

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

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

API 키

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

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

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

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

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

가입한 계정으로 로그인 한 뒤 개발자센터에서 상점의 테스트용 클라이언트 키를 사용하면 됩니다.

결제창 연동

Q. 신용·체크카드 결제창 연동이 잘 되었는지 어떻게 확인할 수 있나요?

신용·체크카드 결제창 연동을 마친 뒤 아래 항목들을 순서대로 확인해보세요.

순서실패 케이스해결 방법
1. 결제창 실행 및 약관 동의결제창이 실행되지 않을 때SDK 추가 및 초기화가 제대로 이루어졌는지 확인하세요. requestPayment의 필수 파라미터가 모두 포함되어 있고 각 파라미터의 데이터 타입이 올바른지 확인하세요.
2. 카드사 선택 화면으로 이동한 뒤 카드사 선택
3. 카드사 인증창으로 연결
4. 카드사 자체창·앱카드 실행 및 결제모바일 웹 환경에서 카드사 앱이 없다는 메시지가 돌아오고 더이상 진행되지 않을 때, 모바일 앱 환경에서 카드사 앱이 설치되어 있지 않아 자동으로 앱스토어나 플레이스토어로 이동할 때모바일 웹 환경이라면 반드시 앱을 먼저 깔아야 합니다. 모바일 앱에서 웹뷰를 사용한다면 앱 스킴 리스트와 관련 코드가 제대로 추가되어 있는지 확인하세요.
5. 다시 상점 페이지로 이동 후 결제 완료모바일 웹 환경에서 브라우저의 상점 페이지로 이동하지 않을 때, 모바일 앱인 경우 상점 앱으로 이동하지 않을 때requestPayment의 파라미터 appScheme이 제대로 설정되었는지 확인하세요.
6. 결제 결과에 따라 성공 혹은 실패 페이지로 이동페이지 이동이 되지 않을 때requestPayment의 파라미터 successUrlfailUrl이 제대로 들어갔는지 확인하세요. 결제 승인 API가 제대로 요청되었는지 확인하세요.

카드사 자체창·앱카드를 바로 여는 방법으로 연동했다면 위 과정 중 1, 2번인 약관 동의, 카드사 선택을 건너뛰고 파라미터로 넘긴 카드사 자체창이나 앱카드가 바로 열립니다. 이 때 만약 카드사 자체창이나 앱카드가 바로 실행되지 않는다면,

  • SDK 추가 및 초기화가 제대로 이루어졌는지 확인하세요.
  • requestPayment의 필수 파라미터가 모두 포함되어 있고 각 파라미터의 데이터 타입이 올바른지 확인하세요.
  • 카드사 자체창·앱카드를 바로 열 수 있도록 하는 파라미터인 flowMode 값이 DIRECT이고 cardCompany 값을 올바르게 넘겼는지 확인하세요.

자동 결제(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. 개발자센터의 'API 버전'은 어떤 기능인가요?

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

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

Q. 카드사 별 테스트는 어떻게 진행하나요?

8개의 주요 카드사(신한, 삼성, 현대, 롯데, KB국민, NH농협, 하나, 비씨)에서 카드사 심사를 마쳤는지 확인하세요. 만약 위 주요 카드사를 모두 보유하지 않았다면, 아래 두 가지 인증 방식에서 하나 이상의 카드사에 대한 결제 완료·결제 취소 테스트를 진행해주세요.

  • 안전결제(ISP): 비씨, KB국민
  • 안심클릭(MPI): 신한, 삼성, 현대, 롯데, NH농협, 하나

카드사 심사란?

카드사 심사는 카드사에서 소비자 보호를 위해 전자결제 심사를 신청한 온라인 쇼핑몰에 대해 진행하는 심사로 주요 8개 카드사가 각 사 정책에 따라 진행합니다.

좀 더 자세한 내용이 궁금하다면 토스페이먼츠 블로그의 전자결제 심사, 한 번에 통과하는 방법을 참고하세요.

내 상점의 카드사 심사에 대해 더 궁금한 점이 있다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

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