[POS 플러그인 · Open API] 플러그인 요청의 매장 검증 방법과 Open API 앱 함께 설치 가능 여부

[asdflkjh1029]

■ 제품 · 환경

• 제품: POS 플러그인 SDK, Open API
• SDK: @tossplace/pos-plugin-sdk 0.0.30 / TossPOS 1.2610.6 (Windows)
• 앱: Open API 앱 POS:T, POS 플러그인 POS:T(POS) (플러그인 ID post-t, 탭 화면)
• 배포: 개발 배포, 테스트 가맹점 merchantId 737236
• 확인 시각: 2026-11-05 19:54 KST

■ 한 것
플러그인에서 posPluginSdk.merchant.getMerchant()로 매장 ID를 받아, posPluginSdk.http.post로 저희 서버(ACL 등록)에 보냈습니다.

■ 결과

• getMerchant().id는 설치 웹훅과 Open API의 merchantId와 같았습니다.
• 서버에 도착한 요청에는 User-Agent(got) 외에 토스가 붙인 서명이나 매장 식별 헤더가 없었습니다.
• Open API 앱과 POS 플러그인은 각각 따로 설치되었습니다.

■ 문의

1. 플러그인이 보낸 요청이 특정 매장(merchantId)의 POS에서 온 것인지 파트너 서버가 검증할 방법이 있나요? (예: 토스 서명 토큰, 서명된 요청 헤더)
2. POS 플러그인과 Open API 앱을 서비스 코드 하나로 함께 설치할 수 있나요?
3. 설치할 때 파트너가 정한 값을 설치 웹훅(app.installation.created.v1)에 담아 받을 수 있나요?

감사합니다.

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

안녕하세요. 토스플레이스 개발자센터입니다. 문의하신 세 가지 항목에 대해 안내 드립니다.

1. 특정 매장의 POS가 보낸 요청인지 확인할 수 있나요?
   getMerchant().id는 매장을 구분하는 값이지, 요청이 해당 매장의 POS에서 왔음을 증명하는 값은 아닙니다. posPluginSdk.http.post()에는 토스가 매장을 보증하는 서명이나 토큰을 자동으로 붙이는 기능이 없습니다. 요청 인증이 필요하다면 솔루션사 로그인 등으로 매장 계정을 확인한 뒤, 자체 서버에서 발급한 인증 토큰을 요청 헤더에 담아 검증해 주세요. x-toss-signature는 토스가 보내는 웹훅을 검증하는 서명으로, 플러그인의 HTTP 요청에는 적용되지 않습니다. POS HTTP API · 웹훅 서명 검증

2. 서비스 코드 하나로 두 앱을 함께 설치할 수 있나요?
   아니요. POS 플러그인과 Open API 앱은 각각 연결해야 합니다. 개발 배포 중에는 테스트 매장에서 두 앱의 사용 여부를 각각 확인해 주세요. 운영 매장에서는 각 앱의 서비스 코드를 따로 입력합니다. POS 플러그인 설치 가이드 · Open API 앱의 운영 매장 연결을 안내한 기존 포럼 답변

3. 설치 웹훅에 파트너가 정한 값을 담을 수 있나요?
   아니요. app.installation.created.v1에는 파트너가 임의 값을 추가하는 필드가 없습니다. 자체 매장 코드와 연결하려면, 웹훅 서명을 검증한 뒤 수신한 merchantId와 자체 매장 코드를 솔루션사 서버에서 매핑해 주세요. 앱 설치 웹훅 항목 보기

[asdflkjh1029]

@토스플레이스-개발자센터
안녕하세요. 답변 감사합니다! 점주가 Open API merchantId를 직접 찾지 않고도 저희 서비스에서 매장을 연결할 수 있도록, 매장 조회 방법을 한 가지 더 문의드립니다.

토스 POS 로그인에 사용하는 10자리 매장고유번호로 해당 매장의 Open API merchantId를 조회할 수 있는 공식 API나 파트너용 기능이 있나요? 저희 Open API 앱이 이미 설치된 매장만 조회할 수 있어도 괜찮습니다.

지원하는 경로가 있다면 사용 조건과 관련 문서를 안내 부탁드립니다. 해당 번호로 조회할 수 없다면, 점주가 merchantId를 직접 입력하지 않고 매장을 식별할 수 있는 권장 절차가 있는지도 궁금합니다.

그리고 일반 운영 매장의 점주가 별도 플러그인 설치 없이, 토스 POS나 토스플레이스 매장 관리 화면에서 Open API merchantId를 직접 확인할 수 있나요?

감사합니다.

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

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

점주님이 merchantId를 직접 찾거나 입력하실 필요는 없습니다. 별도 POS 플러그인 없이, Open API 앱의 설치 웹훅으로 매장을 식별할 수 있습니다.

1. 점주 입력 없이 매장을 연결하는 방법
   Open API 앱에 설치 웹훅을 설정해 주세요. 점주님이 POS에서 서비스 코드로 앱을 연결하면 app.installation.created.v1 이벤트에 merchantId와 매장 정보가 함께 전달됩니다. 솔루션사 서버에서 웹훅 서명을 검증하고, 매장명·사업자번호를 대조한 뒤 해당 매장 계정에 merchantId를 저장해 주세요. 이미 설치된 매장은 기존에 수신한 해당 앱의 웹훅에서 merchantId를 확인하실 수 있습니다.

2. 10자리 매장고유번호로 조회할 수 있나요?
   아니요. POS 로그인용 매장고유번호와 Open API의 merchantId는 서로 다른 값입니다. 앱이 이미 설치된 매장이라도 10자리 번호로 merchantId를 조회하는 공개 API는 없습니다. 매장 정보 조회 API는 웹훅 등으로 확인한 merchantId를 입력해 매장 정보를 조회하는 기능입니다.

3. 운영 매장의 점주가 화면에서 직접 확인할 수 있나요?
   일반 운영 POS의 ‘매장 정보’에는 Open API용 merchantId가 별도 항목으로 표시되지 않으며, 점주용 매장 대시보드도 공식 조회 경로로 안내하고 있지 않습니다. 개발자센터의 ‘테스트 가맹점 상세’에서 ID를 확인하는 방법은 테스트 매장에만 해당합니다.

웹훅에서 받은 ID로 매장명과 사업자번호를 대조하는 방법은 이전 포럼 답변의 2번도 참고해 주세요.

[asdflkjh1029]

@토스플레이스-개발자센터 답변 감사합니다!