결제완료 이벤트 수신문의

[고산주니]

어떤 제품을 사용하나요?

• 제품: POS 플러그인
• SDK 또는 API 버전: @tossplace/pos-plugin-sdk 0.0.17
• 환경: 운영

무었이 궁금한가요?

문의 드립니다.

결제완료 구독:
payment.on("paid")
order.on("complete")
order.on("update")
order.on("add")

확인된 동작은 다음과 같습니다.

1. 플러그인에서 결제하기를 누릅니다.
2. draftOrder.startPayment()를 호출하고 POS 결제 화면으로 이동합니다.
3. 고객이 결제를 완료합니다.
4. 플러그인 화면으로 돌아오면 기존 플러그인 인스턴스가 유지되지 않고 새로운 인스턴스로 실행되는 것으로 확인됩니다.
5. 결제 중 발생한 payment.paid, order.complete 등의 이벤트는 새 인스턴스에 전달되지 않습니다.

이때 이벤트를 안정적으로 전달받을 수 있는 방법이 있을까요?
매장 포스기기에 따라 다음 인스턴스 올라 왔을때 이벤트 처리가 가능한 포스가 있는 반면,
유실되는 포스는 계속 유실되고있습니다.

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

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

문의하신 흐름에서는 결제 이벤트 수신을 탭 화면이 아닌 별도의 웹 워커 플러그인으로 분리하는 방식을 권장합니다.

1. 결제 이벤트는 웹 워커에서 수신해 주세요.

탭 화면은 다른 화면으로 이동하면서 실행·구독 상태가 해제될 수 있어, 다시 진입한 화면에서 결제 중 발생한 이벤트를 받는 것을 전제로 구성하면 안 됩니다.

탭 화면에서는 주문 구성과 결제 화면 이동을 처리하고, 백그라운드에서 실행되는 웹 워커 플러그인에서 payment.on('paid')를 구독해 주세요. 탭 화면 내부에서 생성하는 일반 Worker가 아니라, 별도로 등록·배포하는 웹 워커 플러그인을 의미합니다. 웹 워커 개발 가이드

2. 화면 복귀 시에는 저장된 결제 결과를 조회해 주세요.

워커가 받은 paymentId·orderId와 처리 결과를 솔루션사 서버에 저장하고, 탭 화면이 다시 열릴 때 해당 결과를 조회해 반영하는 방식입니다. 탭 앱과 워커 앱의 Storage는 공유되지 않으므로 서버를 통해 연결해 주세요.

POS 종료·통신 단절까지 대비하려면 주문·결제 조회를 통한 누락 보완과 결제 ID 기준 중복 처리 방지도 함께 적용해 주세요.

3. 결제 발생과 주문 완료를 구분해 주세요.

payment.on('paid')는 결제 건마다 발생하므로 분할결제 시 여러 번 호출될 수 있습니다. 주문 전체의 결제 완료는 주문을 조회하여 paymentPrice.paymentUnpaidValue가 0인지 확인해 주세요.

order.on('complete')는 주문 상태의 완료 이벤트로, 결제 이벤트와 구분됩니다. 결제 이벤트 가이드

POS별로 수신 결과가 다른 부분은 현재 정보만으로 원인을 확정하기 어렵습니다. 비교 확인을 위해 정상·미수신 POS의 버전, 단말기 시리얼번호, 앱 ID와 발생 시각을 개발자센터 메일로 전달 부탁 드립니다.

[고산주니]

예, 알려주신 방식으로 고민해보겠습니다. 자세한 설명 감사드립니다. ^^

추가로, 문의드립니다.
추후에는 설치 매장당 과금이 되는 것으로 알고 있습니다.

이와 관련해서 두 가지 문의드립니다.

한 매장에 POS 플러그인과 워커 플러그인이 모두 설치되어 있는 경우, 각각 별도로 과금되는 방식인가요?

저희 시스템 이용을 중단하는 매장의 경우, 현재는 제가 해당 매장에 설치된 플러그인을 직접 삭제할 수 없는 것으로 알고 있습니다. 추후 과금 방식으로 전환되면 이런 매장은 어떻게 관리하거나 과금 대상에서 제외할 수 있을까요?

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

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

현재 플러그인 이용에 대한 과금은 2026년까지 면제됩니다. 따라서 올해는 POS 탭 화면 플러그인과 웹 워커 플러그인을 함께 사용하시더라도 별도 이용료가 발생하지 않습니다.

다만 2027년 과금 정책은 아직 확정된 내용이 없습니다. 문의하신 앱별 과금 여부와 서비스 이용을 중단한 매장의 과금 대상 제외 기준도 현재 확정해 안내 드리기 어려운 점 양해 부탁 드립니다.