[프론트 플러그인] 플러그인 설치 시 타사 POS 시리얼 가맹점 등록 실패 — 결제 결과를 플러그인이 받을 수 있나요?

[plusalpha]

어떤 제품을 사용하나요?

• 제품: 프론트 플러그인
• SDK 또는 API 버전: Toss Front SDK v0 (https://cdn.tossplace.com/toss-front-sdk/v0/index.js)
• 환경: 개발 (개발 배포한 플러그인을 실단말에 설치)

무엇이 궁금한가요?

포인트 적립 플러그인을 개발하고 있습니다. 매장 구성은 아래와 같습니다.

• 결제는 타사 POS가 일으킵니다. 타사 POS와 토스 프론트를 시리얼로 연결해, 프론트를 카드 단말기(CAT)로 쓰는 구성입니다.
• 플러그인은 결제를 요청하지 않습니다(sdk.payment.requestPayment 미사용). 파트너 시스템 연동 가이드의 "결제 단말기 모드"(외부 시스템이 요청하면 플러그인이 결제를 실행)와는 반대 방향입니다.
• 플러그인이 하려는 일은 결제가 끝난 뒤 결제 금액·승인번호·거래일시를 받는 것입니다. 이 값과 고객 QR(또는 휴대폰번호)로 자사 포인트 서버에 적립을 요청하고 결과 화면을 보여주려고 합니다.

그런데 플러그인을 설치한 단말에서는 타사 POS의 가맹점 등록이 되지 않습니다. 플러그인만 지우면 같은 구성에서 등록이 정상적으로 완료됩니다(아래 오류 항목 참고). 플러그인 설치가 원인으로 보여, 이 구성이 가능한지부터 여쭙니다.

1. 플러그인을 설치한 프론트에서 "타사 POS 연결 모드"를 함께 쓸 수 있나요?
   플러그인을 지우면 등록이 되므로, 플러그인 설치·실행이 이 모드와 원래 함께 쓸 수 없는 구조인지 궁금합니다. 함께 쓸 수 있다면 따로 필요한 설정(모드 전환, 권한, 개발자센터 설정 등)이 있는지도 알고 싶습니다.

2. 타사 POS 연결 모드에서 결제가 끝나면, 플러그인이 결제 결과를 받을 수 있는 공식 경로가 있나요?
   필요한 값은 금액·승인번호·거래일시이고, 가능하면 승인/취소 구분과 결제수단도 받고 싶습니다. Payment API는 플러그인이 직접 요청한 결제를 기준으로 하고 있어서, 타사 POS가 일으킨 결제를 조회하거나 구독하는 방법을 찾지 못했습니다.

3. 공식 경로가 없다면, Serial API로 POS와 단말 사이의 전문을 관찰하는 방식이 허용되나요?

   • sdk.serial.open({ intercept: false })로 열면 결제 흐름에 끼어들지 않고 전문을 읽기만 할 수 있나요?
   • intercept: true로 열 경우, 받은 전문을 원래대로 넘기는 정식 방법은 sdk.van.write인가요, sdk.serial.handle인가요?
   • 플러그인이 시리얼 포트를 열면 단말 자체의 POS 연결과 충돌하나요? 이번 가맹점 등록 실패와 관련이 있는지도 궁금합니다.

4. 결제가 끝난 뒤 플러그인 화면으로 돌아올 수 있나요?
   결제 화면이 떠 있는 동안에도 플러그인 JS가 계속 실행되는지, 결제가 끝난 뒤 플러그인이 적립 화면을 띄울 수 있는지 궁금합니다.

위 방법이 모두 어렵다면, 타사 POS와 연동하는 매장에서 결제 금액을 기준으로 적립을 구현할 때 권장하시는 방식을 안내해 주시면 감사하겠습니다.

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

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

문의 주신 기존 POS 연동과 결제 결과 수신 방법을 안내 드립니다.

1. 타사 POS 연결 방법
말씀하신 ‘가맹점 등록’이 프론트 온보딩 과정의 ‘타사 POS’ 연결 조합 선택을 의미하신다면, 플러그인 연동 시 해당 선택지가 표시되지 않는 것이 맞습니다.

이 경우 온보딩에서 ‘타사 POS’를 선택하는 대신, 플러그인에 시리얼 통신 코드를 추가하여 POS/VAN의 요청을 처리하도록 구성해 주세요.
공개 멀티패드 예제처럼 시리얼 포트를 열고, 수신한 데이터를 van.write로 전달하는 방식입니다. POS/VAN의 통신 속도와 사용 중인 SDK 버전에 맞춰 적용한 뒤 연결 동작을 확인 부탁 드립니다.

Serial API 안내 · 멀티패드 연동 예제
기존 POS 연결과 플러그인 사용에 대한 이전 답변도 참고해 주세요.

2. 외부 POS 결제 결과 수신
외부 POS가 진행한 모든 결제를 자동으로 조회·구독하는 공식 Front SDK API는 제공되지 않습니다. Payment API의 getPayment는 플러그인 결제의 paymentKey로 결과를 조회하는 기능입니다.

포인트 적립에 필요한 금액·승인번호·거래일시·승인/취소 구분·결제수단은 승인 결과를 보유한 POS 또는 VAN 연동 시스템에서 자사 서버로 전달하고, 플러그인이 해당 서버와 연동하는 구성을 우선 검토해 주세요.
Payment API 안내

3. Serial API 사용
intercept: false는 기존 결제 전문을 복제해 읽기만 하는 전용 모니터링 옵션이 아닙니다. 이 설정만으로 기존 결제에 영향을 주지 않으면서 전문 전체를 관찰할 수 있다고 보기는 어렵습니다.

공개 멀티패드 예제는 intercept: true로 열고, serial.listen으로 받은 데이터를 van.write에 전달합니다. 해당 구성에서는 van.write를 사용하시고, serial.handle을 동일한 처리 경로로 간주해 대체하지 말아 주세요.
van.write 완료는 전문 전달 완료이며, 결제 승인 완료를 의미하지 않습니다.
통신 속도나 수신·전달 구성에 따라 기존 연동에 영향을 줄 수 있으므로, 1번의 예제와 설정을 기준으로 확인해 주세요.

4. 결제 이후 적립 화면
결제 화면 종료 후 플러그인 화면에서 적립 결과를 표시하는 구성을 검토할 수 있습니다. 다만 화면 복귀와 결제 성공은 별개이므로, POS 또는 자사 서버에서 확인한 승인 결과를 기준으로 적립해 주세요.

결제 화면 표시 중 JavaScript·타이머가 항상 중단 없이 실행된다고 전제하지 말고, 화면 복귀 후 거래 상태를 다시 확인할 수 있도록 구성해 주세요.