[프론트 플러그인] 가맹점 본인이 자체 개발 프로그램과 연동해 1개 매장에서 사용 가능한지 문의

[세탁플랜]

안녕하세요. 자체 개발 중인 Windows 프로그램과 토스 프론트를 연동하려는 가맹점입니다.
토스 POS는 사용하지 않고, 프론트를 결제 단말기로만 쓰려고 합니다.

연동 가이드(파트너 시스템 연동 가이드 - 클라이언트 모드, WebSocket API)를 참고해 아래 구조로 개발하려고 합니다.

• 프론트 플러그인: sdk.websocket.start()로 서버 오픈, 요청 수신 시 sdk.payment.requestPayment() 호출
• Windows 프로그램: 같은 매장 LAN에서 ws://프론트IP:포트 로 접속해 결제 요청 및 결과 수신

문의드립니다.

1. 솔루션사가 아닌 가맹점 본인이 개발자센터에 가입해, 자체 매장 1곳 전용으로 프론트 플러그인을 개발·라이브 배포할 수 있나요? 라이브 검수 및 VAN 대리점 활성화 절차가 동일하게 필요한지도 궁금합니다.
2. 같은 LAN의 Windows PC가 프론트의 WebSocket 서버에 직접 접속하는 구조가 가능한지, ACL 등 별도 설정이 필요한지 확인 부탁드립니다.
3. 현재 보유 중인 Open API 앱(주문 생성·상태 변경 권한)은 프론트 플러그인 모드 전환 후에도 그대로 매출 조회 용도로 사용할 수 있나요?

감사합니다.

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

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

1. 자체 매장용 개발·배포

가맹점에서 직접 개발한 프론트 플러그인도 개발자센터를 통해 배포할 수 있습니다. 자체 매장 1곳에서 사용하더라도 운영 적용에는 라이브 검수·배포와 VAN 대리점의 앱 활성화가 필요합니다. 개발 중에는 테스트 가맹점과 개발 배포를 이용해 주세요.

라이브 검수·배포 후 앱과 VAN 대리점의 권한 연결을 요청하고, 대리점에서 해당 매장의 앱을 활성화하는 순서입니다. 검수 및 배포 가이드를 참고해 주세요.

2. Windows 프로그램과 WebSocket 연결

말씀하신 구조는 파트너 시스템 연동 가이드의 클라이언트 모드에 해당합니다. 프론트에서 sdk.websocket.start로 서버를 열고, Windows 프로그램이 해당 주소·포트·경로로 접속해 요청을 전달하면 플러그인에서 결제 API를 호출하고 결과를 회신할 수 있습니다.

같은 LAN에서도 PC가 프론트의 해당 포트에 접근할 수 있는 네트워크 환경이 필요합니다. ACL은 플러그인에서 호출하는 외부 URL의 허용 목록이므로, PC가 프론트의 서버로 접속하는 방향과 구분해 주세요. 플러그인에서 별도 외부 API도 호출한다면 해당 URL을 ACL에 등록해야 합니다. WebSocket API 가이드를 참고해 주세요.

3. Open API 병행 사용

토스 POS 없이 프론트 플러그인과 Open API를 함께 사용할 수 있습니다. 기존 Open API 앱을 해당 매장에 적용해 결제 데이터를 조회하는 방식으로 구성해 주세요. 프론트 플러그인 앱과 Open API 앱은 각각 매장에 연결·활성화해야 합니다.

프론트 단독 매장의 Open API 앱도 VAN 대리점을 통해 적용합니다. Open API 설치 가이드를 참고해 주세요.

[세탁플랜]

답변 감사합니다. 추가로 확인 부탁드립니다.

현재 토스 터미널 + 토스 프론트를 케이블로 연결해 함께 사용하고 있습니다.

1. 프론트를 프론트 플러그인 모드로 전환하면, 터미널과 프론트 연결은 해제해야 하나요? 토스 POS 연결 안내처럼 터미널을 백업 단말기 겸 프린터로 계속 사용할 수 있을까요?
2. 프론트 플러그인에서 sdk.printer.printReceipt()를 호출하면 영수증이 어느 프린터로 출력되나요? 연결된 토스 터미널의 프린터로 출력할 수 있는지 궁금합니다.

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

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

1. 터미널 모델별 지원 여부

• 터미널1: 프론트 플러그인의 영수증 프린터로 사용하는 구성은 지원하지 않습니다.
• 터미널2: 프린터 모드(단독 모드)를 지원하므로 영수증 프린터로 사용할 수 있습니다. 별도의 프린터 설정과 출력 연결이 필요합니다.

터미널2는 프론트2와 CTC 케이블로 온보딩한 후 케이블을 분리해 단독으로 사용할 수 있습니다. 이 경우 인터넷 연결을 위해 터미널2에 LAN을 연결해야 합니다.

2. 영수증 출력 방식

sdk.printer.printReceipt는 프론트에 연결·설정된 프린터로 영수증을 출력하는 기능입니다. 터미널2가 프린터 모드를 지원하더라도, 기존 프론트 연결만으로 해당 API의 출력 대상으로 자동 설정되는 것은 아닙니다.

현재 사용 중인 장비가 터미널1인지 터미널2인지 확인 부탁 드립니다.

Printer API 가이드

[세탁플랜]

답변 감사합니다. 저희 매장 장비는 터미널1입니다.

추가로 확인 부탁드립니다.

1. 터미널1 + 프론트 구성에서 프론트를 프론트 플러그인 모드로 전환한 뒤에도, 터미널1에서 금액을 직접 입력해 카드 결제하는 것이 지금처럼 가능한가요? 플러그인에 문제가 생겼을 때 백업으로 쓰려고 합니다.
2. 불가능하다면 터미널2로 교체해야 하나요? 그 경우 지금 쓰는 프론트를 그대로 쓸 수 있는지, 프론트2로도 바꿔야 하는지 궁금합니다.
3. 저희는 테스트 가맹점으로 실제 운영 매장을 불러와 쓰고 있습니다. 프론트 플러그인 사용 여부를 ON으로 바꾸고 테스트 단말기로 매장 프론트를 등록하면 영업 중인 프론트가 즉시 플러그인 모드로 바뀌나요? OFF로 돌리고 재시작하면 원래 화면으로 복구되는지도 궁금합니다.

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

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

1. 터미널1의 백업 결제 사용

터미널1에서 금액을 직접 입력하고, 터미널1 자체 카드 리더기로 결제하는 것은 가능합니다.

앞서 안내한 미지원 사항은 프론트 플러그인의 영수증을 터미널1로 출력하는 기능이며, 터미널1 자체 카드 결제를 뜻한 것은 아닙니다.

다만 플러그인 모드의 프론트를 기존처럼 터미널1의 카드 리더기로 함께 사용하는 구성은 지원하지 않습니다. 백업 결제는 프론트와 결제 연동을 분리한 터미널1에서 진행하며, 터미널1의 정상적인 결제 설정과 인터넷 연결이 필요합니다.

2. 장비 교체 필요 여부

백업 카드 결제 목적만이라면 터미널2·프론트2로 교체할 필요는 없습니다. 기존 터미널1의 자체 결제를 이용하시면 됩니다.

프론트 플러그인의 영수증 출력까지 필요하다면 별도로 지원되는 프린터 구성을 검토해 주세요.

3. 테스트 설정 적용과 기존 화면 복구

사용 여부 ON과 테스트 단말 등록만으로 현재 화면이 즉시 플러그인 모드로 전환되지는 않습니다. 설정 후 프론트를 다시 온보딩하면 개발 배포된 플러그인이 적용됩니다.

반대로 일반 터미널 연결 모드로 돌아갈 때도 OFF 후 재시작만으로 복구하는 방식은 아닙니다. 플러그인 사용을 해제한 뒤 프론트에서 로그아웃 또는 초기화를 진행하고, 기존 터미널 연결 방식으로 다시 온보딩해야 합니다.

영업 중인 프론트를 테스트 단말기로 등록하면 해당 장비가 개발 코드 적용 대상이 됩니다. 운영에 영향을 주지 않도록 별도의 테스트 단말기 사용을 권장합니다.

테스트 단말기 등록 가이드 · 재온보딩 안내