키오스크 결제 시스템, 연동이 막힐 때

키오스크 결제 연동이 막히면 토스페이먼츠 문서 기준으로 키와 환경, 결제 단계, 앱 이동, 서버 설정 네 곳부터 확인합니다. 이 글은 토스페이먼츠 개발자센터의 결제 흐름 · 환경 설정 · 배포 체크리스트 · 웹뷰 문서에 적힌 확인 항목만 모았습니다.

2026년 11월 5일에 네 쪽을 직접 읽었습니다. 이 문서들은 웹 화면과 앱에서 결제창을 여는 방식이고, 실물 카드 단말기를 붙이는 방식이나 다른 결제대행사(PG, 카드 결제를 대신 처리해 주는 회사)는 다루지 않으므로 따로 확인해야 합니다.

1. 결제가 막히면 어느 단계에서 멈췄는지부터 봅니다

토스페이먼츠 문서는 온라인 결제를 요청 · 인증 · 승인 세 단계로 설명합니다. 막힌 곳이 인증 단계인지 승인 단계인지 가르는 것이 첫 확인입니다.

토스페이먼츠 개발자센터 「결제 흐름 이해하기」 화면 (2026년 11월 5일)

화면의 도식에는 인증이 실패하면 실패 URL로, 승인이 실패하면 에러 객체로 이어지는 갈림길이 그려져 있습니다. 어느 쪽으로 빠졌는지에 따라 볼 곳이 달라집니다.

2. 테스트 키인지 라이브 키인지 먼저 맞춥니다

토스페이먼츠는 라이브 환경과 비슷한 테스트 환경을 제공합니다. 테스트 환경에서는 결제가 승인되어도 실제 결제수단에서 돈이 출금되지 않아요.

배포 체크리스트는 라이브로 바꿀 때 「라이브 API 키인가요?」와 「시크릿 키가 외부에 노출되는 부분은 없나요?」를 묻습니다. 테스트에서 되던 연동이 라이브에서 막힌다면 키부터 다시 보라는 뜻으로 읽을 수 있습니다.

3. 에러를 일부러 만들어 대응을 시험합니다

환경 설정 문서는 테스트 환경에서도 에러를 재현하는 방법을 안내합니다. 결제 승인 API를 부를 때 TossPayments-Test-Code 헤더에 재현할 에러 코드를 넣는 방식입니다.

예시로 든 코드는 REJECT_CARD_PAYMENT이고, 응답의 message는 「한도초과 혹은 잔액부족으로 결제에 실패했습니다.」입니다. 문서는 Authorization 헤더에 반드시 테스트 시크릿 키를 쓰라고 적었고, 라이브 키를 쓰면 이 헤더가 무시된다고 했습니다.

4. 승인에서 막히면 저장해 둔 값과 돌아온 값을 비교합니다

결제 흐름 문서는 결제 요청 전에 주문번호(orderId)와 최종 결제 금액(amount)을 서버 세션이나 데이터베이스에 임시로 저장하라고 안내합니다. 인증이 끝나면 성공 URL로 돌아온 paymentKey, orderId, amount를 저장해 둔 값과 비교한 뒤 승인을 요청합니다.

문서에 따르면 성공 URL에는 paymentKey, orderId, amount가 항상 돌아오고, 저장해 둔 값과 비교하면 클라이언트에서 결제 금액을 조작해 승인하는 행위를 방지할 수 있다고 합니다.

5. 앱 안에서 웹 화면을 띄우면 앱 이동이 막힐 수 있습니다

Android 웹뷰는 카드사 · 은행 앱으로 넘어가는 설정이 없으면 막힐 수 있다고 문서가 안내합니다. 웹뷰(WebView)는 앱 안에 웹 화면을 넣는 기능입니다.

AndroidManifest.xml에 카드앱 · 은행앱 패키지를 등록하지 않으면 앱이 설치되어 있어도 스토어로 이동한다고 적혀 있습니다. WebViewClient의 shouldOverrideUrlLoading에 오버라이딩 로직을 추가하지 않으면 net::ERR_UNKNOWN_URL_SCHEME 에러가 발생한다고 합니다.