자주 묻는 질문

개발자센터에서 회원가입 후 이메일 인증을 완료해 주세요. 가입 후 테스트 가맹점을 연결하고 애플리케이션을 생성하면 개발을 시작할 수 있어요.

테스트 가맹점 연결하기를 참고해 주세요.

결제가 가능한 테스트 가맹점과 단말기에서 결제를 진행하면 실제 승인이 발생해요. 반드시 본인 결제수단으로 테스트하고, 테스트 후 즉시 취소해 주세요.

반려 사유를 확인해 수정한 뒤 새 버전으로 다시 검수를 요청해 주세요. 제품별 절차는 프론트 플러그인 검수·배포와 POS 플러그인 배포를 참고해 주세요.

라이브 검수 통과 후 VAN 대리점이 토스플레이스 파트너스에서 해당 매장 또는 단말기에 앱을 활성화해야 해요.

검수가 완료된 서비스의 코드를 가맹점에 전달해 주세요. 가맹점은 토스 POS의 설정 > 기타설정 > 서비스 연동 > 서비스 코드로 연결에서 직접 설치할 수 있어요. POS 플러그인 설치와 Open API 설치를 참고해 주세요.

많이 찾는 질문

프론트 플러그인과 토스 POS 동시 연결은 지원하지 않아요.

외부 시스템과 WebSocket 또는 Serial로 통신하고, 프론트 플러그인에서 Payment API를 호출해 주세요.

응답은 솔루션사 서버에 저장하고, 결제 응답 유실은 getPayment, 취소 응답 유실은 getPaymentCancel로 보완해 주세요.

renderUsePointPage로 화면을 표시하고, 조회·차감·저장은 솔루션사 API로 처리해 주세요.

ACL 등록, 재온보딩, CORS 설정, 실제 호출 URL의 프로토콜을 순서대로 확인해 주세요.

라이브 검수 통과 후 VAN 대리점이 토스플레이스 파트너스에서 앱을 활성화해야 해요.

연동 범위와 구조

지원하지 않아요. 프론트 플러그인 모드는 외부 POS 또는 솔루션사 시스템과 토스 프론트를 연동하기 위한 모드예요. 토스 POS와 프론트를 함께 사용해야 한다면 프론트는 일반 연결 모드로 사용하고, 확장 기능은 POS 플러그인 SDK 또는 Open API를 검토해 주세요.

가능해요. 프론트만 사용하는 매장에서도 Open API 앱을 프론트 플러그인과 동일한 방법으로 매장에 적용할 수 있어요. 자세한 과정은 프론트 플러그인 설치 과정을 참고해 주세요.

가능해요. 외부 시스템에서 주문 금액을 확정하고, 토스 프론트는 결제 승인과 취소를 수행하는 구조로 연동할 수 있어요. 결제 결과는 Payment API 응답으로 받아 솔루션사 서버에 저장해 주세요.

토스 프론트 안에서 화면과 결제를 구성하려면 프론트 플러그인 SDK를 사용해 주세요. 기존 Windows POS에서 결제 기능만 연동해야 한다면 프론트 DLL 연동을 검토할 수 있어요. Open API는 프론트 결제 호출용이 아니라 토스플레이스 서버에 저장된 결제 데이터를 조회하는 용도로 사용해 주세요.

프론트 플러그인은 HTML/CSS/JavaScript 기반으로 구현해야 해요. 기존 솔루션사 시스템은 C#, Java, Python 등 어떤 언어로 구현되어 있어도 유지할 수 있어요. 프론트 플러그인과는 WebSocket API 또는 Serial API로 통신하는 구조를 권장해요.

DLL 파일 수령은 개발자센터 가입 완료 후 안내해 드려요. 문의 채널을 통해 요청해 주세요.

결제와 상태 처리

result.type === "SUCCESS"일 때만 성공으로 처리해 주세요. CANCELED, TIMEOUT, 승인 실패, VAN 또는 카드사 거절은 성공 결제가 아니에요. 실패 케이스는 try/catch 또는 실패 응답 분기로 별도 안내해 주세요.

WebView reload, 페이지 이동 등으로 응답 저장에 실패한 경우 결제는 getPayment, 취소는 getPaymentCancel을 보조 복구 API로 사용할 수 있어요. 두 API 모두 { paymentKey } 객체로 호출하며, 요청을 수행한 단말기의 로컬 캐시에서 성공 결과만 조회해요. 캐시는 TTL 14일, 최대 1,000건까지 보관돼요.

requestPaymentCancel은 원거래 승인값 기준으로 호출해요. 필수값인 paymentKey, paymentMethod, tax, supplyValue, tip, timestamp, approvalNumber와 카드 할부 거래의 installment 등 원 승인 응답값을 그대로 사용해 주세요. 알리페이·위챗페이는 extraData.vanTransactionManagementId도 필요해요. 프론트 플러그인 결제 취소는 전액 취소만 지원해요.

가능해요. Printer API의 printReceipt를 사용해 paymentKey 기준으로 다시 출력할 수 있어요. 단말기 내장 프린터에 임의 ESC/POS 명령을 직접 보내는 방식은 제공하지 않아요.

가능해요. requestCashPayment 또는 requestPayment의 현금 결제 흐름을 사용해 주세요. 현금영수증 발급·취소도 실제 거래이므로 승인 응답값을 솔루션사 서버에 저장해 주세요.

간편결제는 바코드 결제 응답, 해외카드는 카드 결제 응답 기준으로 처리해 주세요. 지원 여부는 단말기, VAN, 가맹점 설정에 따라 달라질 수 있어요. 취소까지 구현한다면 원 승인 응답값을 반드시 저장해 주세요.

외부 데이터와 고객 정보 연동

일반 설정값은 Storage API에 저장할 수 있어요. Storage API는 암호화 저장소가 아니므로 인증 토큰, API 키 같은 민감정보는 저장하지 말고 솔루션사 서버에서 관리해 주세요.

네, SDK를 통해 기본 정보를 조회할 수 있어요.

// 단말기 시리얼 번호 조회
const { serialNumber } = await sdk.app.getSerialNumber();

// 매장 정보 조회
const merchant = await sdk.app.getMerchant();
console.log("매장명:", merchant.name);
console.log("사업자등록번호:", merchant.businessNumber);

프론트 플러그인 SDK는 결제 기능을 제공하며 주문 원장을 생성하거나 관리하는 API는 제공하지 않아요. 주문 정보와 프론트 SDK 결제·취소 응답은 솔루션사 서버에서 연결해 관리해 주세요.

토스플레이스 포인트·쿠폰 데이터를 직접 조회하거나 관리하는 프론트 SDK API는 제공하지 않아요. 포인트 사용 화면은 renderUsePointPage를 사용할 수 있어요. 고객 조회, 포인트·쿠폰 계산, 적립·사용 이력 저장은 솔루션사 서버에서 처리하고, 최종 결제 금액만 결제 요청에 전달해 주세요. earned 같은 값은 화면 표시용이며, 표시만으로 포인트가 자동 적립되지는 않아요.

화면 UI와 기기 기능

공통 토스 UI/UX를 위해 프론트 플러그인의 화면은 Template API로 구성해야 해요. 플러그인 설정 화면인 settings.html은 안내된 방식에 따라 직접 구성할 수 있어요.

QR 또는 바코드 스캔은 Camera API 또는 renderQRScanPage를 사용해 주세요. 일반 브라우저 API인 getUserMedia나 마이크 사용은 공식 SDK 기능 범위로 제공되지 않아요.

아니요. Serial API는 외부 시리얼 장치 통신용이에요. 내장 프린터 또는 내장 카드리더 직접 제어 용도로는 제공되지 않으며, 결제는 Payment API의 requestPayment 흐름으로 처리해 주세요.

아니요. 프론트 플러그인은 프론트 단말기에서만 사용할 수 있으며, 대형 키오스크에서는 지원하지 않아요.

프론트 플러그인은 인앱브라우저 기반으로 동작해요. 마이크 등 특정 하드웨어 접근은 SDK에서 지원하는 기능만 사용할 수 있어요. SDK에서 지원하지 않는 기능은 사용이 제한될 수 있어요.

프론트 플러그인은 단말기에서 인앱브라우저 형태로 동작해요. 대기화면 템플릿을 포함해 결제 전·중·후 화면 흐름을 구성할 수 있어요.

개발 환경

프론트 SDK의 로컬 mock을 사용한 브라우저 개발은 가능해요. 다만 실제 결제, 카메라, 프린터 등 단말기 기능은 개발자센터에 ZIP 파일을 개발 배포한 뒤 테스트 단말기에서 확인해야 해요. 로컬 개발 서버 URL을 단말기에 직접 연결하는 방식은 제공하지 않아요.

인증은 솔루션사 서버에서 처리해 주세요. 비밀키를 플러그인 번들에 포함하지 말고, 인증에 사용하는 API 도메인은 ACL과 CORS를 함께 설정해 주세요. 쿠키나 외부 인증 화면을 사용하는 경우에는 프론트 WebView 환경에서 동작하는지 개발 배포로 확인해야 해요.

새 버전을 배포한 뒤 프론트를 재시작하거나, 설정 화면에서 7055 > 플러그인 > 업데이트를 실행해 주세요. 개발 튜토리얼을 참고해 주세요.

단말기를 재시작해도 플러그인이 바로 로딩되지 않을 수 있어요. 단말기의 개발자 설정 메뉴(7055)에서 플러그인 > 업데이트를 실행하거나, 재온보딩 절차를 거쳐야 해요.

보안과 운영 설정

보안상 제한이 있어요. 외부 링크는 기본적으로 차단되고, 개발자센터에서 ACL(접근 제어 목록)에 도메인을 등록해야 이동할 수 있어요.

ACL과 CORS는 서로 다른 설정이에요. 개발자센터 ACL에 실제 호출 URL을 등록하고, 솔루션사 서버에서도 플러그인 Origin을 허용하도록 CORS 응답 헤더를 설정해 주세요.

ACL은 플러그인이 호출할 수 있는 외부 URL 허용 목록이에요. https://, http://, wss://처럼 프로토콜까지 실제 호출 URL과 일치해야 해요. ACL 추가 후에는 프론트 단말기 > 설정 > 7055 > 매장명 선택 > 로그아웃 > 첫 화면에서 시작하기 순서로 재온보딩해 주세요. ACL이 맞아도 솔루션사 서버의 CORS 설정이 맞지 않으면 요청이 실패할 수 있어요.

가능해요. 호출하려는 http://... 또는 wss://... URL을 ACL에 등록해 주세요. 운영 환경에서는 보안상 HTTPS·WSS 사용을 권장해요.

운영 가맹점 플러그인 활성화

개발 배포는 테스트 단말기 확인용이고, 운영 매장 사용은 라이브 배포가 필요해요. 라이브 배포는 개발자센터에서 파일 업로드 후 검수를 요청하는 절차예요.

아니요. 검수 통과 후에도 VAN 대리점이 토스플레이스 파트너스에서 해당 매장 또는 단말기에 플러그인 앱을 활성화(ON)해야 해요. 활성화 후에도 최신 버전이 보이지 않으면 프론트 앱 재시작, 재온보딩, ACL 등록값을 순서대로 확인해 주세요.

많이 찾는 질문

탭 화면 플러그인을 사용해 주세요.

웹 워커 플러그인에서 Payment API의 payment.on 이벤트를 수신해 주세요.

DraftOrder API를 사용해 주세요.

PaymentMethod API와 솔루션사 서버를 함께 사용해 주세요.

POS 엑셀 업로드로 등록한 뒤 Catalog API 조회값을 확인해 주세요.

ACL에 실제 호출 URL이 등록되어 있는지 확인해 주세요.

검수 완료 후 서비스 코드를 전달하면 가맹점이 토스 POS의 서비스 연동 메뉴에서 직접 설치할 수 있어요.

연동 범위와 구조

프론트 플러그인은 토스 프론트 단말기(결제 단말기)에서 인앱브라우저 형태로 동작해요. POS 플러그인은 매장의 POS 시스템에서 웹 워커 또는 탭 화면 방식으로 동작해요. 동작 환경과 SDK가 서로 달라요.

탭 화면 플러그인은 POS 안에 iframe 기반 화면을 추가하는 방식이고, 웹 워커 플러그인은 화면 없이 백그라운드에서 동작하는 방식이에요. 탭 화면 플러그인은 토스 POS의 기타 > 외부 서비스 설정 영역에 메뉴로 표시되지만 웹 워커 플러그인은 메뉴에 표시되지 않아요. 주문 조회나 외부 주문 선택처럼 직원 조작이 필요하면 탭 화면, 결제·환불 동기화처럼 지속 이벤트 처리가 필요하면 웹 워커를 권장해요.

아니요. Storage는 앱별로 분리돼 있어 탭 앱과 워커 앱이 서로 다른 앱이라면 공유되지 않아요. 앱 간 공유가 필요한 데이터는 솔루션사 서버에서 관리해 주세요.

토스 POS 기본 화면의 문구나 옵션을 임의로 수정하거나 숨기는 기능은 제공하지 않아요. 매장 맞춤 UI가 필요하다면 별도 탭 화면 안에서 구성해 주세요.

결제와 주문 처리

DraftOrder API를 사용해 주세요. draftOrder.addLineItem()으로 상품을 담고, draftOrder.startPayment()로 POS 결제 화면을 시작하는 흐름이에요.

기본 판매 탭 장바구니에 담고 결제 화면으로 넘기는 목적이라면 order.add가 아니라 DraftOrder API를 사용해 주세요. order.add는 주문 데이터 생성 목적의 API예요.

변경 메서드가 반환하는 임시 주문 객체를 직접 사용하는 것이 가장 안전해요. 카트 변경을 화면에 반영해야 한다면 draftOrder.on('update', ...) 이벤트를 함께 사용해 주세요.

Payment API의 payment.on('paid'), payment.on('cancel') 이벤트를 사용해 주세요. 결제·환불 결과를 외부 서버에 안정적으로 동기화해야 한다면 탭 화면보다 웹 워커 플러그인 수신 구조를 권장해요.

결제 이벤트는 결제 건 단위로 발생해요. 전체 결제 완료는 order.paymentPrice.paymentUnpaidValue === 0, 전체 취소는 order.paymentPrice.paymentPaidValue === 0 기준으로 확인해 주세요.

가능해요. PaymentMethod API로 커스텀 결제수단을 추가할 수 있어요. 포인트 잔액 조회, 차감, 복구는 솔루션사 서버에서 관리해 주세요.

외부 데이터와 상품 연동

가능해요. HTTP API를 사용해 솔루션사 서버와 통신할 수 있어요. 외부 호출 URL은 ACL 등록이 필요해요.

상품코드나 바코드를 매핑값으로 사용해야 한다면 상품관리 > 상품 한번에 등록 > 엑셀 등록으로 등록해 주세요. 등록 방식에 따라 Catalog API의 code, price.sku, price.barcode 값이 비어 있을 수 있으므로 운영 전 등록 방식을 확정해 주세요.

현재 POS 플러그인 SDK는 상품 조회 중심으로 제공돼요. 상품 대량 등록이 필요한 경우에는 토스 POS의 엑셀 업로드 기능을 사용해 주세요.

DraftOrder의 ignorePrint가 false이면 POS의 프린터 설정에 따라 출력되고, true이면 출력을 건너뛰어요. 필요하면 updateIgnorePrint로 값을 변경한 뒤 실제 매장 출력 설정과 함께 확인해 주세요.

화면 UI와 사용자 입력

POS 탭 플러그인은 UI 구성 자유도가 높아요. 다만 결제나 주문 데이터와 연결되는 화면은 직원이 오동작하지 않도록 흐름을 명확하게 구성해 주세요.

보안과 검수

인증 토큰이나 민감한 키를 플러그인 번들에 직접 하드코딩하지 말아 주세요. 서버 프록시 또는 SecureStore API 같은 보안 저장 방식을 검토해 주세요.

필요해요. POS 플러그인에서 외부 URL을 호출하려면 ACL에 등록되어 있어야 해요. ACL은 프로토콜까지 포함해 확인하므로 https://, http://, wss://가 실제 호출 URL과 일치해야 해요.

SDK API 호출 빈도가 너무 높을 때 발생해요. 짧은 시간에 반복 호출하는 로직이 있다면 요청을 묶거나 간격을 조정해 주세요. Rate Limit 기준은 Rate Limit 가이드를 참고해 주세요.

운영 가맹점 플러그인 활성화

개발 배포는 테스트 POS 확인용이고, 운영 매장 사용은 라이브 배포가 필요해요. 라이브 배포는 개발자센터에서 파일 업로드 후 검수를 요청하는 절차예요.

아니요. 검수 완료 후 개발자센터에서 서비스 코드를 확인해 가맹점에 전달해 주세요. 가맹점이 토스 POS의 설정 > 기타설정 > 서비스 연동 > 서비스 코드로 연결에서 직접 설치해야 해요. 설치한 탭 화면 플러그인은 기타 > 외부 서비스 설정 영역에서 확인할 수 있으며, 웹 워커 플러그인은 메뉴에 표시되지 않아요. 서비스 설치하기를 참고해 주세요.

많이 찾는 질문

Open API를 사용해 주세요.

Open API 앱이 설치된 매장의 지원 결제 유형이면 조회할 수 있어요. 웹훅에서 받은 payment.id 또는 orderId를 저장해 Payment API 조회에 사용해 주세요. 프론트 SDK의 paymentKey로는 Open API를 직접 조회할 수 없어요.

제공 이벤트 범위 안에서 웹훅을 사용해 주세요.

현재 상품 등록·수정 API는 제공하지 않아요. POS 엑셀 업로드를 사용해 주세요.

Open API 응답만으로 단말기별 구분은 제공하지 않아요.

연동 범위와 구조

Open API는 토스플레이스 서버에 저장된 주문, 결제, 매장, 상품 등 문서에 명시된 데이터를 서버 간 연동하는 API예요. 프론트 플러그인 결제도 Open API 앱이 설치된 매장에서 발생하고 지원되는 결제 유형이라면 결제 API와 웹훅의 제공 범위에서 확인할 수 있어요.

가능해요. Open API 앱이 설치된 매장의 프론트 플러그인 결제는 Payment API와 payment.payment.approved.v1, payment.payment.cancelled.v1 웹훅의 제공 범위에서 확인할 수 있어요. 프론트 SDK의 paymentKey는 Open API 조회 키가 아니며 orderId로 자동 매핑되지 않으므로, 웹훅에서 받은 payment.id 또는 orderId를 저장해 조회해 주세요. 단말기 내 응답 유실 복구는 프론트 SDK의 getPayment를 사용해 주세요.

아니요. Open API는 토스플레이스 서버 데이터 연동용이며 결제 승인 기능은 제공하지 않아요. 결제 승인은 프론트 플러그인 Payment API로 처리하고, 승인 후 서버에 저장된 결제는 제공 범위 안에서 Open API로 조회해 주세요.

검수가 완료된 앱의 서비스 코드를 가맹점에 전달해 주세요. 가맹점은 토스 POS의 설정 > 기타설정 > 서비스 연동 > 서비스 코드로 연결에서 직접 설치할 수 있어요. 토스 POS 없이 프론트만 운영하는 매장은 VAN 대리점을 통해 Open API 앱을 적용해요. Open API 서비스 설치하기를 참고해 주세요.

결제와 주문 상태

Open API 조회 대상 결제라면 결제 조회 응답의 state: "CANCELLED", cancelledAt과 payment.payment.cancelled.v1 웹훅으로 취소를 확인할 수 있어요. 프론트 플러그인 결제도 Open API 앱이 설치된 매장에서 발생하고 지원되는 결제 유형이면 같은 범위에서 확인할 수 있어요. 조회에는 웹훅에서 받은 payment.id 또는 orderId를 사용해 주세요.

주문 생성과 주문 상태 변경은 승인된 앱에서 사용할 수 있어요. 상태 변경은 Open API로 생성한 주문의 수락·거절·취소만 지원하며, 주문 취소 API가 결제까지 취소하지는 않아요.

조리 완료와 고객 호출을 외부에서 변경하는 API는 제공하지 않아요. 배달 완료는 Open API로 생성하고 배달 정보를 연결한 주문에 한해 배달 API의 배달 완료 처리를 사용할 수 있어요.

웹훅

개발자센터의 내 애플리케이션 > Open API 앱 > 웹훅에서 Payload URL과 Event trigger를 직접 설정해 주세요. 웹훅을 생성하면 서명 검증용 Secret Key가 발급돼요. 앱이 설치된 여러 매장의 이벤트가 같은 endpoint로 전달되며, Payload의 merchantId로 매장을 구분할 수 있어요. 매장 ID 목록을 별도로 제출할 필요는 없어요.

웹훅은 최소 한 번 전달되므로 x-toss-webhook-id를 멱등 키로 사용해 중복 처리를 막아 주세요. x-toss-signature를 검증하고, 정상 처리한 요청에는 2xx로 응답해야 해요. 자세한 내용은 웹훅 가이드를 참고해 주세요.

Payload URL의 외부 접근 가능 여부, 방화벽의 웹훅 송신 IP 허용, Event trigger, 응답 시간과 HTTP 상태 코드를 확인해 주세요. 요청은 도착했지만 서명 검증에 실패한 경우에는 raw request body와 x-toss-timestamp로 서명을 계산했는지 확인해 주세요. 2xx가 아닌 응답이나 타임아웃은 재시도될 수 있어요.

외부 데이터와 상품 연동

현재 일반 제공 범위에서는 상품 등록·수정·삭제 API를 제공하지 않아요. 상품 대량 등록은 토스 POS의 상품관리 > 상품 한번에 등록 > 엑셀 등록을 사용하고, Catalog API는 조회 용도로 사용해 주세요.

토스 POS의 상품관리 > 상품 한번에 등록 > 엑셀 등록에서 상품코드와 바코드를 입력할 수 있어요. 등록한 값은 주문 조회의 OrderLineItem.item.code와 Catalog 조회의 code, price.barcode에서 확인해 주세요. 값이 입력되지 않은 상품은 해당 필드가 비어 있을 수 있어요.

실시간 재고 수량 조회 API와 외부에서 품절 상태를 변경하는 API는 제공하지 않아요. Catalog API의 state로 판매 상태를 조회할 수 있지만, 이 값은 전시용 상태이며 주문 가능 여부를 강제로 제한하지 않아요. 별도 재고 수량이 필요하면 솔루션사 시스템에서 관리해 주세요.

할인 정책 자동 적용 API는 적용 가능한 DiscountPolicy[]를 반환하며 우선순위 필드는 제공하지 않아요. 토스 POS는 적용 가능한 자동 할인 중 할인 금액이 가장 큰 정책을 선택해요. 주문에 실제 적용된 할인 목록의 precedence는 값이 작을수록 먼저 적용된다는 뜻이에요.

적립 추가 API는 ALPHA 기능으로 사용할 수 있어요. ALPHA 기능은 별도 공지 없이 변경되거나 중단될 수 있으므로 Open API 변경 이력을 주기적으로 확인해 주세요.

운영 데이터와 주문 출처

현재 Open API 응답에는 동일 매장 안의 POS 단말기를 구분하는 별도 기기 식별값이 없어요. 주문과 결제 데이터는 merchantId 기준으로 조회해 주세요.

토스 POS 주문으로 접수되거나 연동된 주문이면 조회 대상에 포함될 수 있어요. 외부 배달 프로그램에서만 처리되고 토스 POS에 생성되지 않은 주문은 조회할 수 없어요.

가능해요. 각 매장에 같은 앱을 설치하고 API와 웹훅의 merchantId로 매장을 구분해 주세요.

보안과 인증 관리

개발자센터에서 솔루션사가 직접 확인하고 관리할 수 있어요. Access Secret은 생성 시에만 확인할 수 있으므로 서버 환경변수나 안전한 비밀값 저장소에 보관해 주세요.

merchantId는 Open API에서 매장을 식별하는 ID예요. API 호출 경로와 웹훅 Payload에서 사용해요.

요청 헤더의 x-access-key, x-secret-key와 해당 매장의 서비스 설치 여부를 확인해 주세요. 계속 실패하면 응답 오류 코드와 x-toss-event-id를 함께 전달해 문의해 주세요.

Open API는 솔루션 파트너사를 위한 서비스예요. 가맹점은 연동 서비스를 제공하는 솔루션사의 앱을 서비스 코드로 설치해 이용해 주세요.