연동가이드 FAQ를 먼저 확인해 주세요
문의 전에 연동가이드 FAQ에서 관련 내용을 먼저 확인해 주세요. 개발·테스트·검수·배포와 제품별 주요 질문을 모아 두었어요.
FAQ에서 답을 찾지 못했다면 포럼에 문의를 남겨 주세요.
1. 연동 수단 고르기
Q. 프론트 플러그인과 토스 POS를 함께 쓸 수 있나요?
A. 동시 연결은 지원하지 않아요. 프론트 플러그인 모드는 외부 POS 또는 솔루션사 시스템과 토스 프론트를 연동하기 위한 모드예요.
토스 POS와 프론트를 함께 사용하신다면 프론트는 일반 연결 모드로 동작하고, 플러그인을 개발해 프론트 화면을 직접 구성하는 방식은 사용할 수 없어요. 이 구성에서 확장이 필요하면 POS 플러그인 SDK 또는 Open API를 검토해 주세요.
Q. 그럼 어떤 구성에 어떤 수단을 써야 하나요?
A. 쓰려는 구성에 따라 갈려요.
내 구성
쓸 수 있는 수단
토스 POS + 프론트
프론트는 일반 연결 모드. 확장은 POS 플러그인 SDK 또는 Open API
자체 POS·키오스크 + 프론트 (토스 POS 없음)
프론트 플러그인 SDK
외부 Windows POS에 결제만 추가
프론트 Windows DLL (제한적 지원, 사전 확인 필요)
서버에서 주문·결제 데이터만 조회
Open API
어떤 수단이 적합한지는 각 수단의 지원 범위를 연동 가이드에서 확인하신 후 판단해 주세요. 개발자센터에서는 수단별 지원 범위를 안내드리며, 서비스 요건에 맞는 구현 설계는 상담해 드리지 않아요.
Q. 외부 POS에서 토스 프론트를 결제 단말기로만 쓸 수 있나요?
A. 가능해요. 외부 시스템에서 주문 금액을 확정하고, 토스 프론트가 결제 승인과 취소를 수행하는 구조로 연동할 수 있어요. 결제 결과는 Payment API 응답으로 받아 솔루션사 서버에 저장해 주세요.
2. 서비스 이용료와 계약
Q. 이용료가 얼마인가요?
A. 제품별 이용료는 아래 가이드에서 확인해 주세요.
플러그인 서비스 이용료
Q. 과금은 언제부터 시작되나요?
A. 라이브 가맹점이 연결되는 시점부터예요. 개발 단계에서는 이용료가 발생하지 않아요. 테스트 가맹점 연결이나 개발 배포만으로는 과금되지 않아요.
Q. 자체 매장 전용 플러그인도 과금되나요?
A. 네. 솔루션사 여부와 관계없이 동일한 정책이 적용돼요. 자사 매장 내부 보고 목적으로 Open API를 연동하는 경우에도 같은 기준(연결 매장 10개 이하 무료)이 적용돼요.
Q. 결제 수단이나 계좌는 어디서 등록하나요?
지금은 등록하실 것이 없어요. 2026년 12월 31일까지는 이용료가 발생하지 않아서 결제 수단이나 계좌를 등록하는 절차를 운영하지 않고 있어요. 과금 시점이 정해지면 등록 방법을 미리 안내드릴게요.
3. 개발·테스트 중 플러그인이 단말기에 보이지 않을 때
Q. 개발 배포했는데 단말기에 반영되지 않아요.
A. 순서대로 확인해 주세요.
해당 단말기가 테스트 단말기로 등록되어 있는지 확인해 주세요. 개발 배포는 테스트 단말기(최대 5대)에만 적용돼요.
등록만으로는 적용되지 않아요. 등록한 뒤 로그아웃하고 테스트 가맹점 계정으로 재온보딩해야 적용돼요.
프론트는 설정 > 7055 > 토스 프론트 재시작, POS는 새로고침 또는 종료 후 재실행해 주세요.
Q. 테스트 단말기 등록 목록이 비어 있어요.
A. 등록은 프론트 단말기가 테스트 가맹점에 정상 로그인된 뒤에 가능해요. 최초 1회 순서는 아래와 같아요.
테스트 가맹점 정보(매장고유번호·사업자번호·휴대폰번호)로 프론트 온보딩
개발자센터 내 애플리케이션 > 단말기 등록에서 해당 단말기 등록
로그아웃 후 같은 정보로 재온보딩
목록이 계속 비어 있다면 온보딩 시 입력한 값이 개발자센터의 테스트 가맹점 상세에 표시된 값과 일치하는지 확인해 주세요.
::: tip 테스트 가맹점 관리의 ON은 다른 설정이에요
테스트 가맹점 관리에서 플러그인 사용 여부 ON은 가맹점과 플러그인을 연결하는 설정이에요. 단말기 등록 목록은 단말기와 테스트 가맹점의 로그인 상태를 기준으로 표시돼요. ON만으로 단말기가 목록에 나타나지는 않아요.
:::
Q. 설정 화면(7055)에 플러그인 메뉴가 보이지 않아요.
A. 설정 화면의 플러그인 메뉴는 해당 단말기에 플러그인이 정상적으로 로드된 경우에만 나타나요. 메뉴가 없다면 플러그인이 아직 적용되지 않은 상태이고, 그 메뉴에서 플러그인을 최초 설치할 수는 없어요. 로그아웃 후 테스트 가맹점 계정으로 재온보딩해 주세요.
Q. POS 탭에 플러그인이 안 보여요.
A. 토스 POS 1.22.9 버전 이상에서 탭 진입점이 GNB에서 LNB로 이동했어요. LNB에서 먼저 확인해 주세요. LNB에서도 보이지 않을 때 재온보딩이나 매니페스트 파일을 확인해 주세요.
4. 운영 매장에서 플러그인이 보이지 않을 때
Q. 대리점에 요청해서 ON 했는데 단말기에 나타나지 않아요.
A. 이 순서로 확인해 주세요. 1번이 가장 흔한 원인이에요.
해당 단말기가 테스트 단말기로 등록되어 있지 않은지 확인해 주세요. 테스트 단말기에는 라이브 버전이 적용되지 않아요. 등록되어 있다면 개발자센터에서 테스트 단말기 등록을 해제해 주세요.
VAN 대리점이 토스플레이스 파트너스에서 해당 매장 또는 단말기에 플러그인 앱을 활성화(ON)했는지 확인해 주세요.
프론트 앱을 재시작해 주세요. 설정 > 7055 > 토스 프론트 재시작
로그아웃 후 재온보딩해 주세요.
ACL 등록값을 확인해 주세요. https://, http://, wss://처럼 프로토콜까지 실제 호출 URL과 일치해야 해요.
Q. 라이브 배포 후에도 대기화면이 나오지 않아요.
A. 위 1번(테스트 단말기 등록 해제)과 3번(프론트 재시작)을 먼저 확인해 주세요. 라이브 검수 통과 후에도 VAN 대리점의 활성화가 완료되어야 매장에 노출돼요.
Q. 라이브로 전환한 매장을 다시 테스트로 되돌릴 수 있나요?
A. 가능해요. 테스트와 라이브는 양방향으로 전환할 수 있고 재온보딩으로 처리돼요.
VAN 대리점이 토스플레이스 파트너스에서 라이브 앱을 OFF (안정성을 위해 권장)
단말기 초기화 또는 로그아웃
테스트 매장으로 재온보딩
개발자센터에서 테스트 단말기 등록
5. merchantId 확인과 앱 연결
Q. 운영 매장의 merchantId는 어디서 확인하나요?
A. 앱 설치 웹훅 이벤트(app.installation.created.v1)를 수신해서 확인하는 것이 공식 방법이에요. 내 앱이 어떤 매장에 설치되었는지는 이 이벤트로 확인할 수 있어요.
이벤트 payload에 매장 ID와 사업자등록번호가 함께 들어 있어서, 사업자등록번호를 기준으로 내부 시스템과 매핑할 수 있어요. 매장명·주소·영업시간도 같이 전달돼요.
json
{ "type": "app.installation.created.v1", "merchantId": 42, "data": { "merchant": { "id": 42, "name": "플레이스 베이커리", "businessNumber": "0000000000" } }}
웹훅 수신 주소는 개발자센터 내 애플리케이션 > 웹훅에서 등록해 주세요. 앱을 연결하기 전에 미리 등록해 두시면 연결 시점에 바로 매장 ID를 받을 수 있어요.
Q. 매장 조회 API로 먼저 찾을 수는 없나요?
A. 매장 정보 조회 API는 merchantId를 이미 알고 있어야 호출할 수 있어요. 그리고 앱이 설치되지 않은 매장은 API를 호출할 수 없어요. 순서는 앱 연결 → 웹훅으로 매장 ID 확인 → 그 ID로 조회예요.
6. 라이브 검수
Q. 검수 전에 무엇을 준비해야 하나요?
A. 별도로 정해진 필수 제출 서류 양식은 없어요. 개발자센터에서 라이브 배포 트랙에 플러그인 ZIP을 업로드한 뒤 [검수 요청] 버튼을 누르면 접수돼요. 추가로 필요한 자료가 있으면 검수 중에 개별적으로 요청드려요.
접수 전에 아래 세 가지는 직접 확인해 주세요.
모든 기능이 테스트 환경에서 정상 동작하는지
프론트 플러그인이라면 모든 화면이 Template API로 구성되어 있는지
개인정보 처리와 보안 정책을 준수하는지
Q. 통과 기준이 무엇인가요?
A. 공통 4개 항목과, 프론트 플러그인에 추가되는 2개 항목을 확인해요.
항목
확인 내용
기능 검수
모든 기능이 명세대로 동작하는지
성능 검수
응답 속도와 안정성
보안 검수
개인정보·보안 문제
사용성 검수
사용자 경험이 적절한지
디자인 검수 (프론트 추가)
Template API 사용 여부와 UI/UX 가이드라인 준수
제품 기능 검수 (프론트 추가)
결제·하드웨어 연동 등 핵심 기능 동작
프론트 플러그인에서 가장 자주 걸리는 항목은 디자인 검수예요. HTML·CSS를 직접 작성하거나 Template 바깥에 임의 텍스트·레이아웃을 추가하면 통과하지 못해요.
Q. 검수는 얼마나 걸리나요?
A. 두 가지를 함께 보셔야 해요.
검수를 진행하는 날: 매주 월·목요일(근무일 기준)이에요. 접수하신 시점 이후 가장 가까운 검수일에 들어가요.
검수 소요 시간: 검수가 시작된 뒤 평균 1-2일이에요. 결과는 이메일로 알려드려요.
접수 요일에 따라 전체 대기 기간이 달라져요. 오픈 일정이 정해져 있다면 라이브 검수 전에 개발 배포 트랙으로 먼저 검증해 주세요. 검수 승인 후에 수정하면 재검수로 일정이 밀려요.
Q. 패키지를 바꾸지 않고 설정값만 바꿔도 다시 검수받아야 하나요?
A. 검수는 라이브 배포 트랙에 패키지를 새로 업로드하고 검수 요청을 누를 때 진행돼요. 패키지 파일이 바뀌지 않으면 재검수는 발생하지 않아요.
문구나 설정값이 어디에 있느냐에 따라 갈려요.
솔루션사 서버에서 런타임에 내려오는 값이라면 → 서버만 수정, 재검수 불필요
플러그인 파일 안에 직접 작성되어 있다면 → 파일이 바뀌므로 재업로드 + 재검수 필요
Q. 자사 매장 1곳에서만 쓰는 플러그인도 검수를 받아야 하나요?
A. 네, 절차는 같아요. 매장 수나 솔루션사 여부에 따른 예외는 없어요.
7. 새 매장에 배포할 때
Q. 라이브 검수를 한 번 통과하면 모든 매장에 적용되나요?
A. 아니요. 두 가지를 구분해서 보셔야 해요.
검수는 플러그인 버전 단위예요. 한 번 승인되면 그 버전은 다시 검수받지 않아요.
매장 활성화는 매장 단위예요. 새 매장마다 활성화가 필요해요.
프론트 플러그인은 매장마다 VAN 대리점이 토스플레이스 파트너스에서 플러그인을 활성화해야 해요. 검수를 통과했다고 해서 자동으로 모든 매장에 노출되지는 않아요.
Q. 연동 방식마다 다른가요?
A. 네, 다릅니다.
연동 방식
새 매장 설치 방법
VAN 대리점
프론트 플러그인
VAN 대리점이 토스플레이스 파트너스에서 매장에 활성화
필요
POS 플러그인
서비스 코드를 가맹점에 전달 → 가맹점이 토스 POS에서 직접 설치
불필요
Open API
서비스 코드를 가맹점에 전달 → 가맹점이 직접 연결
불필요
단, 프론트 플러그인과 Open API를 함께 쓰는 구성이라면 결국 VAN 대리점을 거쳐야 해요. 두 가지를 같이 쓰실 계획이라면 새 매장마다 VAN 대리점 활성화가 필요한 것으로 보고 일정을 잡아 주세요.
Q. 테스트 환경에서도 VAN 대리점이 필요한가요?
A. 아니요. 테스트 가맹점은 개발자센터에서 직접 ON/OFF할 수 있어요.
8. 403 · 4010 권한 오류
Q. 서버 호출에 403이 반환돼요. 응답이 JSON이 아니고 HTML이에요.
A. 응답 본문이 HTML이고 x-toss-event-id 헤더가 없다면, 요청이 애플리케이션 단계에 도달하지 못한 상태예요. 인증키 문제라면 JSON 오류 응답이 반환돼요.
먼저 User-Agent 헤더를 추가해서 재시도해 주세요. 기존 인증 헤더(x-access-key, x-secret-key)와 함께, 호출하는 서비스를 식별할 수 있는 값으로 지정해 주세요.
GET /api-public/openapi/v1/merchants/{merchantId}
x-access-key: ...
x-secret-key: ...
User-Agent: my-service/1.0
User-Agent가 없는 요청은 차단될 수 있고, 그 상태로 요청이 반복되면 해당 출구 IP가 차단 목록에 등록될 수 있어요. 재시도·헬스체크·배치 등 모든 호출 경로에 User-Agent가 들어가는지 확인해 주세요.
::: warning 해외 리전에서 호출하는 경우
응답의 CF-Ray 값 끝이 ICN이 아니라면 해외 엣지를 경유한 호출이에요. 재시도 후에도 403이 계속되면 호출 서버의 공개 출구 IP와 함께 문의해 주세요. 이 값이 있어야 차단 이력과 대조할 수 있어요. 클라우드 환경에서는 출구 IP가 여러 개일 수 있으니 전체를 알려주세요.
:::
Q. 403 또는 4010 오류가 계속돼요.
A. 아래 두 가지를 먼저 확인해 주세요.
요청 헤더의 x-access-key, x-secret-key 값
대상 매장에 앱이 설치되어 있는지 — 앱을 설치하지 않은 매장에는 API를 호출할 수 없어요
계속 오류가 발생하면 아래 정보와 함께 문의해 주세요.
응답 본문의 errorCode와 reason
응답 헤더의 x-toss-event-id
호출 시각(KST, 초 단위)과 도메인을 포함한 전체 호출 URL
호출 서버의 공개 출구 IP
Q. 테스트 환경에서는 되는데 운영에서만 실패해요.
A. 두 환경의 차이를 확인해 주세요.
운영 매장에 앱이 설치되어 있는지 (테스트 가맹점 설치와 별개예요)
호출 서버가 바뀌면서 출구 IP가 달라졌는지
운영 호출 경로에 User-Agent가 빠져 있지 않은지
