토스플레이스 개발자 포럼 (Beta)

안녕하세요. 토스플레이스 개발자센터입니다. 문의 주신 테스트 매장 등록 한도와 직영 매장의 Open API 앱 연결 방법에 대해 안내 드립니다. 1. 테스트 매장 등록 한도 테스트 매장은 최대 5개까지 등록할 수 있으며, 등록 한도 확대는 불가합니다. 실제 운영 매장은 테스트 매장 등록과 별개로 Open API 앱을 설치하여 연결해 주세요. 2. Open API 앱 검수 및 권한 Open API는 별도의 앱 검수 절차가 없으며, 검수용 파일이나 자료를 제출하실 필요도 없습니다. 주문 생성 등 별도 권한이 필요한 기능을 사용할 때만 해당 권한을 신청하시면 됩니다. 문의 주신 주문·결제 조회 목적이라면 주문 생성 권한을 신청하실 필요는 없습니다. 3. 직영 매장 연결 방법 자사 매장에서만 사용하는 경우에도 기존 매출관리(maechul-jangchung) 앱을 각 운영 매장에 연결할 수 있습니다. 개발자센터의 해당 Open API 앱에서 서비스 코드를 확인해 주세요. 각 매장의 토스 POS > 설정 > 기타설정 > 서비스 연동 > 서비스 코드로 연결에서 서비스 코드를 입력해 주세요. 설치 후에는 각 매장의 merchantId로 주문·결제 데이터를 조회해 주세요. 토스 POS 없이 프론트만 사용하는 매장은 담당 VAN 대리점을 통해 Open API 앱 적용을 요청해 주세요. 자세한 절차는 Open API 서비스 설치 가이드를 참고해 주세요. 여러 매장에서 동일한 Open API 앱을 사용하는 방법은 기존 관련 답변의 3번 항목도 함께 참고해 주세요. 감사합니다.

안녕하세요. 토스플레이스 개발자센터입니다. 문의 주신 카드 결제 테스트와 취소·결과 조회 방법을 안내 드립니다. 1. 카드 결제 테스트 환경 카드사 가맹 없이 승인할 수 있는 별도의 테스트 TID·테스트카드는 제공해 드리기 어렵습니다. 카드 결제·취소 테스트를 위해서는 이용 중인 VAN 대리점을 통해 카드사 가맹정보를 정식으로 등록해야 합니다. 2. 운영 배포 전 테스트 가맹정보 등록 전에는 현금영수증 미발급 현금 결제로 화면 흐름과 결과 처리를 확인하실 수 있습니다. 다만 실제 카드 승인·취소 검증을 대신하지는 않습니다. 가맹정보 등록 후 본인 카드로 승인하고, 테스트가 끝나면 즉시 취소해 주세요. 결제 테스트 가이드 3. 취소 요청값 원결제의 paymentKey, response.card.timestamp와 response.card.approvalNumber를 사용하시면 됩니다. timestamp는 숫자 그대로 전달하고, paymentMethod와 금액 항목도 원거래에 맞춰 전달해 주세요. installment는 원결제의 할부 개월을 사용하고, tid를 지정하는 경우에도 원결제 TID를 사용합니다. 현금영수증 미발급 현금 결제에는 취소할 현금영수증 승인 거래가 없습니다. 결제 취소 API 4. 재시작 후 결과 조회 sdk.payment.getPayment({ paymentKey })로 같은 단말에 저장된 승인 결과를 조회하는 방식이 맞습니다. VAN에 최종 거래 상태를 다시 조회하는 기능은 아니며, 취소 결과는 getPaymentCancel로 별도 조회합니다. getBackupPaymentKey는 SDK가 백업한 결제 식별자를 읽는 보조 기능입니다. 현재 사용하시는 v0 SDK에는 getPaymentByKey가 없으므로, 예제의 해당 호출은 getPayment({ paymentKey })로 변경해 주세요. 결과 조회 API 프론트 직접 승인에 필요한 매장·TID·VAN 설정은 앞서 안내한 답변도 함께 참고 부탁 드립니다.

안녕하세요. 토스플레이스 개발자센터입니다. 개발 버전 상단의 IP·포트 표시는 프론트 앱에서 표시하는 개발용 배지입니다. 현재 이 표시만 숨기는 설정이나 SDK API는 제공되지 않습니다. 플러그인의 HTML·CSS를 수정해 제거하는 영역도 아닌 점 참고 부탁 드립니다.

POS 플러그인 SDK의 업데이트 내역을 안내드려요. 0.0.30 UI [신규] openModal 추가 텍스트·숫자·비밀번호·라디오·체크박스·약관 동의 입력 요소와 이미지·텍스트·순서 텍스트·Q&A·구분선 안내 요소로 모달을 구성해요. onSubmit에서 에러가 발생하면 Alert이 표시되고 모달이 유지돼요. [변경] openInputModal deprecated 전체 변경 이력은 POS 플러그인 SDK 릴리즈 노트에서 확인할 수 있어요.

POS 플러그인 SDK의 업데이트 내역을 안내드려요. 0.0.29 Navigation [신규] navigate('plugin-setting-tab', packageName) 추가 플러그인 설정 탭으로 이동해요. [변경] navigate('plugin-tab') deprecated 배달 [변경] DeliveryConnectionStatusErrorCode에 USER_DISCONNECTED 추가 전체 변경 이력은 POS 플러그인 SDK 릴리즈 노트에서 확인할 수 있어요.

안녕하세요. 토스플레이스 개발자센터입니다. 문의 주신 POS 기기 구분과 주문번호 설정에 대해 안내 드립니다. 1. 결제한 POS 기기 구분 현재 Open API와 웹훅에서는 결제한 POS를 식별하는 기기 ID·시리얼 번호를 제공하지 않습니다. 주문의 source는 POS·키오스크 등 주문 경로를 구분하는 값으로, 같은 매장의 개별 POS를 구분하는 값은 아닙니다. 주문 데이터 안내 2. 기기별 주문번호 설정 각 POS의 메뉴 → 설정 → 주방 주문서 → 주문 시작번호에서 시작 숫자를 설정할 수 있으며, 매일 자정에 설정한 번호로 다시 시작합니다. 이 설정은 숫자 입력 방식으로, 기기별 임의 문자 접두어를 지정하는 기능은 제공하지 않습니다. 설정 안내 다만 주문번호는 결제 기기의 고유 식별값이 아니므로, 번호만으로 실제 결제한 POS를 확정적으로 구분하기는 어렵습니다. 기기 식별정보 제공 범위는 기존 포럼 답변의 2번 항목도 함께 참고 부탁 드립니다. 추가로 요청 주신 결제 POS 기기 식별정보 제공에 대해서는 내부적으로 검토해보겠습니다.

안녕하세요. 토스플레이스 개발자센터입니다. 문의 주신 프론트 플러그인 결제 후 영수증 출력 방법을 안내 드립니다. 1. 카드 매출전표 출력 플러그인 결제 시 전자영수증은 지원하지 않습니다. 프론트에 프린터가 연결되어 있으면 결제 완료 후 기본 영수증 1장이 자동 출력됩니다. 추가 출력이나 재출력이 필요한 경우에는 Printer API의 printReceipt를 이용해 별도로 구현해 주세요. 2. printReceipt 호출값 결제 응답 전체가 아니라, 결제에 사용한 paymentKey와 출력 수량 count를 전달합니다. 1장 출력 시 paymentKey와 count: 1을 전달하시면 됩니다. 주문 정보 orderInfo와 추가 문구 additionalText는 선택 사항입니다. 파라미터와 호출 예제를 참고 부탁 드립니다. 3. 외부 프린터 연결 프론트에 연결한 시리얼·블루투스 프린터로 출력하는 경로가 있습니다. 유선 연결 예시는 CPP-3000이며, 프론트 Serial 포트에 연결한 후 프린터 설정에서 시리얼 케이블을 선택하고 테스트 출력으로 확인합니다. 사용할 프린터의 호환 여부는 구매·설치 대리점에 먼저 확인 부탁 드립니다. 연결 가이드의 유선 연결 및 프론트 설정 부분을 참고해 주세요. 해당 가이드의 POS 등록 단계는 현재 문의하신 프론트 단독 구성과 구분해 보셔야 합니다. paymentKey로 결제 정보를 조회해 출력하는 방식은 기존 Printer API 답변도 참고 부탁 드립니다.

Open API의 업데이트 내역을 안내드려요. 2026-10-28 주문 생성 시 주문자의 회원 식별자를 입력하고, 조회·웹훅 응답에서 확인할 수 있어요. 주문 주문 Order ALPHA 주문자 정보 (orderer) 필드가 추가됩니다. 주문자 정보 OrderOrderer 주문자 회원 식별자 (memberId) 필드가 추가됩니다. 주문 생성 - 주문자 정보 OrderOrderer.Create 주문자 회원 식별자 (memberId) 필드를 입력할 수 있습니다. 전체 변경 이력은 Open API 릴리즈 노트에서 확인할 수 있어요.

안녕하세요. 토스플레이스 개발자센터입니다. 네, 현재 Open API로 후불 매장의 추가 주문을 계속 확인하시려면 주문 조회 API를 주기적으로 호출하는 방식(폴링)이 필요합니다. 동일한 orderId에 상품이 추가되는 시점의 별도 웹훅은 제공하지 않습니다. 주문 조회 API로 해당 orderId의 lineItems를 조회하고, 이전 조회 결과와 비교해 변경 내역을 확인해 주세요. 조회 주기는 API 호출량 제한을 고려해 조정해 주세요. 앞서 안내 드린 update-line-items는 주문을 변경하는 API이므로, 추가 주문 내역을 확인하기 위해 호출하실 필요는 없습니다. 추가 주문 웹훅과 조회 방식에 대한 이전 답변도 함께 참고해 주세요.

안녕하세요. 10월 7일 (수)에 발생하였던 장애 대응 관련하여 내부 조치 사항을 공유드리고자 합니다. 장애 원인은 CDN으로 제공하던 SDK (https://cdn.tossplace.com/toss-front-sdk/v0/index.js) 요청이 실패했던 것으로 이에 대한 배포 파이프라인 및 인프라 관련 조치를 취했습니다. 재발 방지를 위하여 토스 프론트 내 SDK에 대한 캐싱을 플러그인을 로딩하는 앱 내 구현하여, 플러그인을 별도로 수정하지 않으시더라도 동일한 SDK 요청 실패 시, 캐싱을 통해 로딩되도록 조치를 취했습니다. 이에 대한 모니터링 과정에서 문제 없음이 확인되어 최종 공유드립니다. 앞으로 안정성 있는 시스템을 제공해드릴 수 있도록 최선을 다하겠습니다. 감사합니다.

안녕하세요. 토스플레이스 개발자센터입니다. 테스트 가맹점 로그인 조건과 현재 기기로 테스트하는 방법을 안내 드립니다. 테스트 가맹점이 모두 KIS 기기로만 제한되는 것은 아닙니다. 다만 로그인할 가맹점의 VAN과 프론트가 지원하는 VAN이 맞아야 합니다. 전달해 주신 기기의 로그에서도 KIS 지원 기기 안내와 함께 가맹점 인증이 거절된 내역을 확인했습니다. 현재 프론트의 VAN에 맞는 테스트 가맹점을 이용하는 방법으로 진행해 주세요. 단말을 공급한 VAN 대리점에 해당 VAN의 테스트 가맹점 생성을 요청하고, 생성된 가맹점 정보로 프론트에 로그인한 뒤 개발자센터에 연결하시면 됩니다. 기기 자체의 VAN 전환 가능 여부는 단말을 공급한 대리점에 확인 부탁 드립니다. 개발자센터 계정의 사업자번호 변경이 필요하면 아래 가이드의 필수 정보를 개발자센터 메일로 전달 부탁 드립니다. 자세한 절차는 테스트 가맹점 연결 가이드의 VAN 불일치 안내를 참고해 주세요.

안녕하세요. 토스플레이스 개발자센터입니다. 탭 화면 앱의 개발 버전이 적용된 점 확인했습니다. 추가로 문의 주신 웹 워커 앱 활성화 방법을 안내 드립니다. 개발자센터 → 테스트 가맹점 관리 → 해당 테스트 매장 상세에서 tokorder-worker의 사용 여부를 ON으로 설정해 주세요. POS의 서비스 코드 연결이 아닌, 테스트 가맹점의 앱 사용 설정으로 진행 부탁 드립니다. 라이브 배포 없이도 개발 배포 버전으로 테스트할 수 있습니다. 두 앱의 테스트 단말기 등록은 확인하셨으므로, 워커 앱 사용 설정 후 POS를 완전히 종료하고 다시 실행해 주세요. 웹 워커는 백그라운드에서 실행되며 별도 탭 화면이 생기지는 않습니다. 설정 후 탭 앱에서 보낸 메시지를 워커가 수신하는지 확인 부탁 드립니다. 앱 사용 설정은 POS 플러그인 테스트 가이드를, 두 앱의 구성과 통신 방법은 앞서 안내 드린 답변을 참고해 주세요. 지금까지 안내 드린 내용을 모두 확인하신 후에도 동일한 문제가 반복된다면, 개발자센터 메일로 문의 부탁 드립니다. 개발자센터 메일: developer-support@tossplace.com 메일에는 아래 내용을 함께 기재 부탁 드립니다. 탭 앱(season7-tokorder-pos)과 웹 워커 앱(tokorder-worker) 각각의 재현 시점 개발 배포 버전 테스트 매장명·매장고유번호, 워커 앱 사용 여부를 ON으로 설정하고 POS를 재시작했는지 여부 문제가 발생한 날짜와 시각(한국 시간, 가능한 분 단위) 문제를 재현한 순서, 기대한 동작과 실제 동작, 표시된 오류 문구(가능하면 화면 캡처 첨부) POS 시리얼번호는 기존에 전달해 주신 기기와 달라진 경우에만 추가

안녕하세요. 토스플레이스 개발자센터입니다. 문의 주신 내용 답변드립니다. 프론트 플러그인을 활성화하면 토스 POS와의 연동은 불가능합니다. 프론트 플러그인은 외부 솔루션이 프론트 단말기와 직접 연동되는 구조로 동작하며, 플러그인이 활성화된 환경에서는 토스 POS와의 연결이 끊어집니다. 따라서 두 가지 질문 모두 현재는 지원되지 않습니다. POS는 그대로 쓰고 프론트만 플러그인 적용 → 불가 POS 플러그인 + 프론트 플러그인 동시 사용 → 불가 혹시 어떤 기능을 구현하려고 하시는지 배경을 공유해 주시면, 현재 제공 중인 연동 방식으로 구현 가능한지 검토 후 대안을 안내드릴 수 있습니다. 감사합니다.

토스 POS 메뉴 개편에 따라 탭 화면(iframe) 플러그인의 진입 경로가 변경됐어요. 아래 경로로 플러그인을 실행해 주세요. 구분 플러그인을 여는 위치 변경 전 왼쪽 상단 메뉴 버튼 > 기타 > 외부 서비스 설정 > 플러그인 선택 변경 후 왼쪽 상단 메뉴 버튼 > 편의 > 서비스 연동 > 내 서비스 > 플러그인 선택 [image: Tobe 2.png] 참고: [내 서비스] 탭은 연동된 서비스·플러그인이 있을 때 표시돼요. 아직 연동 전이라면 서비스 리스트 에서 먼저 서비스를 연동해 주세요. 운영 매장에도 변경된 경로를 안내해 주세요 변경된 경로에서 플러그인 화면이 정상적으로 열리는지 확인해 주세요. 주문·결제 후 화면 전환을 포함해 실제 매장의 이용 흐름을 확인해 주세요. 운영 매장에 새로운 진입 경로를 안내하고, 사용 설명서나 안내 자료에도 반영해 주세요.

요새 병의원 쪽도 많이 보이는거 같은데 플러그인일까요??

안녕하세요. 토스플레이스 개발자센터입니다. 문의하신 터미널2의 결제내역 표시 여부를 안내 드립니다. 프론트 플러그인으로 처리한 결제내역을 터미널2에서 조회하는 기능은 지원하지 않습니다. 동일 매장에서 사용하거나 프론트2와 터미널2를 연결하더라도, 해당 플러그인 결제내역이 터미널2에 표시되지는 않습니다. 결제내역 확인은 현재 이용 중인 토스 POS에서 진행해 주세요.

안녕하세요. 토스플레이스 개발자센터입니다. 추가로 알려주신 KIS CAT 연결 구성을 기준으로 안내 드립니다. 1. Payment API 사용 조건 현재처럼 KIS-1421이 결제를 승인하고 프론트2는 멀티패드로만 사용하는 구성에서는 Payment API를 사용할 수 없습니다. Payment API를 사용하려면 프론트가 직접 결제를 승인하는 구성이어야 하며, 프론트에 TID를 포함한 매장정보 설정이 필요합니다. 기존 연결을 그대로 유지한 상태에서 Payment API만 추가하는 방식은 아니므로, 전환에 필요한 설정은 담당 KIS 대리점에 확인 부탁 드립니다. 2. 기존 CAT 결제의 웹훅 기존 KIS CAT에서 승인한 결제는 Open API 결제 웹훅으로 제공되지 않습니다. 결제 웹훅은 토스 POS·프론트 플러그인 등 토스 솔루션에서 처리한 결제를 대상으로 동작합니다. 토스 프론트를 카드 리더기로 사용한다는 이유만으로 외부 CAT의 승인 내역이 웹훅으로 전달되는 것은 아닙니다. 앞서 안내한 리더기 방식과 프론트 직접 승인 방식의 차이도 함께 참고해 주세요.

안녕하세요. 토스플레이스 개발자센터입니다. WebSocket 서버의 보안 기능과 로컬 저장소의 사용 범위를 나누어 안내 드립니다. 1. WSS 및 연결 단계의 인증 sdk.websocket.start()로 여는 서버는 WS 방식이며, TLS 인증서·개인키 설정이나 핸드셰이크 단계의 인증 헤더 검증 기능은 제공하지 않습니다. 따라서 해당 서버에 WSS를 설정하거나, SDK의 연결 콜백에서 핸드셰이크 이전에 연결을 거절하는 방식으로 구성할 수는 없습니다. 연결 후 인증 메시지를 확인하고 실패 시 disconnect()로 종료할 수는 있습니다. 이 경우 인증이 끝나기 전에는 결제·취소 명령을 처리하지 않도록 해야 하며, 연결 후 인증만으로 통신이 암호화되는 것은 아닙니다. 2. 암호화가 필요한 경우의 구성 자체 WSS 서버에 POS와 프론트 플러그인이 각각 접속하고, 해당 서버에서 인증과 요청 전달을 처리하는 구성을 검토해 주세요. 프론트 플러그인은 브라우저 표준 WebSocket으로 접속하며, 접속 대상에 맞는 유효한 인증서와 ACL 설정이 필요합니다. 인증서 검증을 해제하는 방식으로 구성하지 말아 주세요. 파트너 시스템 연동 가이드와 WebSocket API를 참고해 주세요. 프론트를 WS 서버로 사용하는 기존 구성은 이전 포럼 답변에서도 안내했지만, 해당 구성이 WSS를 제공한다는 의미는 아닙니다. 3. localStorage와 Storage API Storage API는 WebView의 localStorage가 아니라 단말기의 별도 네이티브 저장소를 사용합니다. localStorage 사용 자체를 일괄 금지하는 것은 아니지만, 사용만으로 검수가 승인되거나 데이터 보존이 보장되는 것은 아닙니다. SDK의 키·값 저장 기능이 필요하다면 Storage API를 사용하되, 전환만으로 주문·결제 복구의 안정성이 보장된다고 보시면 안 됩니다. 4. 데이터 유지와 격리 Storage API의 저장된 값은 일반적인 플러그인 새로고침, 앱 재시작 및 단말기 재부팅 후에도 보관하는 구조입니다. 다만 재온보딩 과정에서는 초기화됩니다. 업데이트·로그아웃·삭제·재설치의 모든 경우에 두 저장소의 데이터가 유지된다고 전제하지 말고, 값이 없는 경우 서버에서 복원할 수 있도록 구성해 주세요. Storage API를 앱·매장·계정별 자동 격리가 보장되는 저장소로 사용하지 마세요. 매장이나 계정이 바뀌었을 때 이전 상태를 그대로 적용하지 않도록 구분과 초기화 처리가 필요합니다. 5. 저장 용량·쓰기 보장·결제 복구 공통으로 보장하는 저장 용량이나, 저장 성공 직후 전원 차단까지 포함한 쓰기 보존·원자성을 제공하는 거래 저장소로 안내 드리기는 어렵습니다. 주문·결제의 기준 데이터는 서버에 저장하고, 로컬 저장소는 비민감 설정이나 복구 보조 상태용으로 사용해 주세요. 인증 토큰·API 키·민감한 결제정보를 보관하는 용도로 사용하지 마세요. Storage API는 암호화 저장소가 아닙니다. 승인 응답이 유실됐다면 동일 단말에서 같은 paymentKey로 getPayment를 호출해 결과를 복구할 수 있습니다. 해당 기능은 최근 성공 승인 결과의 로컬 캐시 조회이므로 영구적인 결제 원장이나 다른 단말의 조회 수단을 대신하지는 않습니다. Storage API · 프론트 FAQ · 승인 결과 복구 안내

안녕하세요. 토스플레이스 개발자센터입니다. 무카드 취소의 지원 범위와 VAN 거래 일련번호 확인 기준을 안내 드립니다. 1. NICE 계약과 vanTransactionKey 반환 NICE로 계약하더라도 vanTransactionKey가 모든 승인 응답에 항상 반환되는 것은 보장하지 않습니다. 해당 값은 VAN사와 결제 환경에 따라 비어 있을 수 있으므로, 계약한 VAN만으로 판단하지 말고 실제 승인 응답에 값이 있는지 확인해 주세요. 값을 요청하기 위한 별도 파라미터를 추가하는 방식은 아닙니다. 2. VAN·결제수단별 적용 범위 requestCardlessPaymentCancel의 현재 지원 범위는 NICE·CARD입니다. NICEPAY와 KSNET은 이 API의 지원 범위에 포함되지 않습니다. 신용카드·체크카드와 삼성페이·애플페이는 결제 결과가 CARD로 반환된 경우 위 기준으로 판단하되, 해당 수단이라는 이유만으로 vanTransactionKey 수신을 보장하지는 않습니다. 토스페이·네이버페이·카카오페이·알리페이·위챗페이가 BARCODE로 처리된 거래는 이 무카드 취소 API의 대상이 아닙니다. 3. 발급사·매입사 구분과 취소 처리 발급사·매입사별로 값이 항상 제공되는 목록을 기준으로 구현하기보다는, NICE·CARD 여부와 실제 vanTransactionKey 수신 여부를 함께 확인해 분기해 주세요. 원 승인 응답에 유효한 값이 있으면 다른 원거래 정보와 함께 저장해 무카드 취소에 사용하고, 값이 없는 카드 거래는 현재 구현하신 requestPaymentCancel 방식으로 처리해 주세요. BARCODE 거래의 취소는 해당 결제수단의 일반 취소 절차를 적용해야 하며, 카드 재인식 방식과는 구분해 주세요. Payment API의 무카드 취소 및 승인 응답 안내를 참고해 주세요.