프론트 플러그인 WebSocket 서버의 WSS 및 클라이언트 인증 지원 문의

[bleakwinter]

안녕하세요. 자체 POS 프로그램과 토스 프론트 플러그인을 매장 내부망에서 WebSocket으로 연동하려 합니다.
현재 구성은 다음과 같습니다.

• 서버: 토스 프론트 플러그인의 sdk.websocket.start()
• 클라이언트: 자체 POS 프로그램
• 연결: ws://프론트IP:포트/
• 용도: 결제·취소 요청 및 결과 송수신
  운영 환경에서 통신 암호화와 허용된 POS만의 접근을 구현하고자 합니다. 프론트 WebSocket API 문서에서는 관련 설정을 찾지 못해 문의드립니다.

1. sdk.websocket.start()로 생성하는 서버가 WSS(TLS)를 지원하나요?
2. 지원한다면 인증서·개인키 설정 방법과 로컬 IP 접속 시 인증서 검증 방식을 안내받을 수 있을까요?
3. WebSocket 핸드셰이크 단계에서 인증 헤더 등을 검증하여 미인증 클라이언트의 연결 자체를 거절할 수 있나요?
4. 위 기능을 지원하지 않는다면, 자체 POS와 프론트 간 암호화 및 클라이언트 인증에 권장하는 연동 방식이 있을까요? 연결 후 인증 메시지를 검증하고 실패 시 disconnect()하는 방식을 사용해야 하는지도 궁금합니다.

추가로 프론트 플러그인의 localStorage 사용 가능 여부 및 Storage API 관련 문의가 있습니다.

1. 운영 환경의 프론트 플러그인에서 window.localStorage를 직접 사용해도 되나요? 검수나 기술 지원 측면에서 제약이 있는지 궁금합니다.
2. 직접 사용하는 것이 가능하더라도 토스 Storage API 사용을 권장하나요? 두 방식의 차이와 권장 기준을 알고 싶습니다.
3. Storage API는 내부적으로 WebView의 localStorage를 사용하는지, 단말기의 네이티브 저장소 등 별도 저장소를 사용하는지 궁금합니다.
4. 두 방식은 다음 상황에서 데이터 유지 범위가 어떻게 다른가요?
   • 플러그인 새로고침 및 프론트 앱 재시작
   • 단말기 재부팅
   • 플러그인 버전 업데이트
   • 로그아웃·재온보딩
   • 플러그인 삭제·재설치
5. Storage API의 데이터는 플러그인·매장·단말기 중 어떤 기준으로 격리되나요? 같은 단말기에서 매장이나 계정이 변경되면 기존 데이터에 접근할 수 있나요?
6. 저장 용량 제한과 쓰기 완료 보장은 어떻게 되나요? 저장 API가 성공한 직후 앱이 종료되거나 전원이 꺼져도 데이터가 유지되는지, 단일 값 쓰기의 원자성을 보장하는지 궁금합니다.
7. 주문·결제 복구에 필요한 상태를 보관하는 용도로 적합한지, 그리고 저장하면 안 되는 정보나 별도 보안 지침이 있는지도 안내 부탁드립니다.
   현재 localStorage 기반 구현을 유지해도 되는지, 운영 안정성을 위해 Storage API로 전환해야 하는지 판단하고자 합니다.

감사합니다.

[토스플레이스-개발자센터]

안녕하세요. 토스플레이스 개발자센터입니다.

WebSocket 서버의 보안 기능과 로컬 저장소의 사용 범위를 나누어 안내 드립니다.

1. WSS 및 연결 단계의 인증
sdk.websocket.start()로 여는 서버는 WS 방식이며, TLS 인증서·개인키 설정이나 핸드셰이크 단계의 인증 헤더 검증 기능은 제공하지 않습니다.
따라서 해당 서버에 WSS를 설정하거나, SDK의 연결 콜백에서 핸드셰이크 이전에 연결을 거절하는 방식으로 구성할 수는 없습니다.
연결 후 인증 메시지를 확인하고 실패 시 disconnect()로 종료할 수는 있습니다. 이 경우 인증이 끝나기 전에는 결제·취소 명령을 처리하지 않도록 해야 하며, 연결 후 인증만으로 통신이 암호화되는 것은 아닙니다.

2. 암호화가 필요한 경우의 구성
자체 WSS 서버에 POS와 프론트 플러그인이 각각 접속하고, 해당 서버에서 인증과 요청 전달을 처리하는 구성을 검토해 주세요.
프론트 플러그인은 브라우저 표준 WebSocket으로 접속하며, 접속 대상에 맞는 유효한 인증서와 ACL 설정이 필요합니다. 인증서 검증을 해제하는 방식으로 구성하지 말아 주세요.
파트너 시스템 연동 가이드와 WebSocket API를 참고해 주세요. 프론트를 WS 서버로 사용하는 기존 구성은 이전 포럼 답변에서도 안내했지만, 해당 구성이 WSS를 제공한다는 의미는 아닙니다.

3. localStorage와 Storage API
Storage API는 WebView의 localStorage가 아니라 단말기의 별도 네이티브 저장소를 사용합니다.
localStorage 사용 자체를 일괄 금지하는 것은 아니지만, 사용만으로 검수가 승인되거나 데이터 보존이 보장되는 것은 아닙니다. SDK의 키·값 저장 기능이 필요하다면 Storage API를 사용하되, 전환만으로 주문·결제 복구의 안정성이 보장된다고 보시면 안 됩니다.

4. 데이터 유지와 격리
Storage API의 저장된 값은 일반적인 플러그인 새로고침, 앱 재시작 및 단말기 재부팅 후에도 보관하는 구조입니다. 다만 재온보딩 과정에서는 초기화됩니다.
업데이트·로그아웃·삭제·재설치의 모든 경우에 두 저장소의 데이터가 유지된다고 전제하지 말고, 값이 없는 경우 서버에서 복원할 수 있도록 구성해 주세요.
Storage API를 앱·매장·계정별 자동 격리가 보장되는 저장소로 사용하지 마세요. 매장이나 계정이 바뀌었을 때 이전 상태를 그대로 적용하지 않도록 구분과 초기화 처리가 필요합니다.

5. 저장 용량·쓰기 보장·결제 복구
공통으로 보장하는 저장 용량이나, 저장 성공 직후 전원 차단까지 포함한 쓰기 보존·원자성을 제공하는 거래 저장소로 안내 드리기는 어렵습니다. 주문·결제의 기준 데이터는 서버에 저장하고, 로컬 저장소는 비민감 설정이나 복구 보조 상태용으로 사용해 주세요.
인증 토큰·API 키·민감한 결제정보를 보관하는 용도로 사용하지 마세요. Storage API는 암호화 저장소가 아닙니다.
승인 응답이 유실됐다면 동일 단말에서 같은 paymentKey로 getPayment를 호출해 결과를 복구할 수 있습니다. 해당 기능은 최근 성공 승인 결과의 로컬 캐시 조회이므로 영구적인 결제 원장이나 다른 단말의 조회 수단을 대신하지는 않습니다.

Storage API · 프론트 FAQ · 승인 결과 복구 안내