외부 단말 연동 및 매장별 결제·정산 데이터 제공 범위 문의

[끼뀨]

안녕하세요. 회사 명의로 토스플레이스 매장을 개설하고, 여러 점포(직영점 및 가맹점주 운영 점포)에 키오스크 부스를 설치하려고 합니다.

부스 웹앱이 토스플레이스에서 지원하는 외부 단말(듀얼아이 등)과 직접 통신해 카드 결제를 처리하고, Open API로 받은 결제 내역을 부스 주문과 대조한 뒤 점포별로 정산하는 구조를 검토하고 있습니다. 동일 사업자번호로 온라인 결제에는 토스페이먼츠도 사용하고 있습니다.

개발 문서를 확인하면서 아래 사항을 추가로 확인하고자 문의드립니다. 문서나 별도 담당 창구가 있다면 안내 부탁드립니다.

1. 동일 사업자번호로 여러 매장 개설

   같은 사업자번호로 점포별 매장(merchantId)을 여러 개 개설할 수 있나요? 이 경우 매장마다 카드사 가맹점번호도 별도로 발급되는지 궁금합니다. 지점 사업자번호 또는 종사업장 번호로 매장을 개설할 수 있는지도 확인 부탁드립니다.

2. 외부 단말 연동 규격 및 지원 범위

   외부 단말과 부스 웹앱을 직접 연결하는 연동 규격(통신 방식, 요청·응답 필드, 오류 코드)을 제공받을 수 있나요? 프론트 플러그인 SDK와 Windows DLL 문서는 확인했지만 외부 단말 관련 문서는 찾지 못했습니다. 지원 단말 목록, 승인에 사용하는 VAN사, 응답에 VAN 거래 고유번호가 포함되는지도 안내 부탁드립니다.

3. 결제 건과 주문·단말 연결

   외부 단말로 결제한 내역이 Open API나 웹훅에 전달될 때, 결제 단말을 식별할 수 있는 TID 또는 시리얼 번호가 포함되나요? 승인번호·승인시각·금액 외에 단말 식별 정보를 확인할 수 있는지 궁금합니다. 한 매장에 단말이 여러 대인 경우의 구분 방법과, 결제 요청에 저희 주문번호 같은 참조값을 넣어 결제 내역에서 다시 받을 수 있는지도 확인 부탁드립니다.

4. 부분취소·무카드 취소 및 응답 유실 시 조회

   외부 단말 결제는 부분취소가 가능한가요? 프론트 플러그인은 전액 취소만 가능하고, 카드 없는 취소는 NICE VAN의 vanTransactionKey가 있는 경우에만 가능하다고 이해했는데, 이 이해가 맞는지와 외부 단말에도 같은 조건이 적용되는지 확인 부탁드립니다.

   취소 시 기존 결제의 상태가 변경되는지, 별도 취소 기록이 생성되는지도 궁금합니다. 결제 또는 취소 요청 후 응답을 받지 못했을 때, 실제 처리 결과를 확인할 수 있는 조회 방법도 안내 부탁드립니다.

5. 승인시각과 매출 일자 기준

   결제 내역의 approvedAt은 어떤 타임존을 사용하며, 초 또는 밀리초 중 어느 정밀도로 제공되나요? 매출 일자는 승인시각 기준인지, 매장의 영업 마감 기준인지도 확인 부탁드립니다.

6. PG 정산 구분과 토스페이먼츠 중복 집계 여부

   settlementType이 PG인 결제는 어떤 결제수단에 해당하나요? settlementSubject에 들어올 수 있는 값과 의미, 해당 PG가 토스페이먼츠인 경우도 있는지 궁금합니다. 동일 사업자번호로 두 서비스를 사용하므로, 같은 결제가 양쪽 정산 자료에 중복으로 포함될 수 있는지와 중복 여부를 식별하는 방법도 확인 부탁드립니다.

7. 과거 결제 내역 조회 기간과 호출 한도

   Open API에서 과거 결제 내역은 어느 시점까지 조회할 수 있나요? 문서에서 매장별 초당 10회, 주문 목록 한 페이지당 최대 500건으로 이해했는데, 이 한도가 맞는지 확인 부탁드립니다. 조회 가능한 기간과 대량 조회 시 적용되는 별도 한도도 안내 부탁드립니다.

8. 매장별·결제 건별 정산 자료 제공

   회사 명의 매장의 카드사별 매출·수수료·입금 내역과 토스페이 정산 내역을 매장별 및 결제 건별로 받을 수 있나요? 카드사별 입금 예정일과 예정액도 제공되는지 궁금합니다. 제공 방식이 API, 정기 파일, 대시보드 엑셀 중 무엇인지도 안내 부탁드립니다. 각 결제에서 실제 차감된 수수료를 반영해 점포별로 정산해야 하므로, 결제 건별 실제 수수료를 확인할 수 있는 자료가 필요합니다.

9. 입금 단위와 통장 적요

   토스페이 정산금의 입금 적요가 토스_yyyyMMdd 형식이라고 이해했는데, 맞는지 확인 부탁드립니다. 매장이 여러 개인 경우 매장별로 입금되는지, 사업자 단위로 합산되는지와 매장별 입금 내역을 받을 수 있는지도 궁금합니다.

   카드사 매출대금은 카드사·가맹점번호(매장)·입금일별로 구분되어 입금되나요, 아니면 사업자 단위로 합산되나요? 카드사 입금 적요의 형식도 안내 부탁드립니다. 통장 입금액을 매장별 정산 자료와 대조할 수 있는 방법을 확인하고자 합니다.

10. 대형가맹점 기준과 단말 제공·설치 조건

    단말 구매 안내에서 대형가맹점의 구매가 제한되는 것으로 이해했는데, 해당 조건이 맞는지 확인 부탁드립니다. 대형가맹점 판정 기준이 회사의 연간 카드 매출 합계 3억 원 초과인지, 이때 토스페이먼츠를 통해 받는 온라인 카드 매출도 합산되는지 궁금합니다.

    대형가맹점에 해당한다면 외부 단말은 어떤 구매·임대·제공 조건으로 이용할 수 있나요? 또한 회사 명의 단말을 다른 사업자인 가맹점주가 운영하는 점포 내 부스에 설치하는 구조가 카드 가맹 심사상 가능한지, 필요한 조건이나 서류가 있는지도 확인 부탁드립니다.

11. 토스플레이스·토스페이먼츠 간 사업자 정보 및 계약 연동

    동일 사업자번호로 두 서비스를 이용할 때, 사업자 정보나 정산 계좌를 변경하면 다른 서비스에도 반영되나요? 서비스별로 별도 변경 신청이 필요한지, 한쪽의 계약 해지 또는 이용 정지가 다른 쪽에 영향을 미치는지도 확인 부탁드립니다.

질문이 많아 답변 가능한 항목부터 안내해 주셔도 큰 도움이 됩니다. 확인이 필요한 항목의 담당 부서나 관련 문서도 알려주시면 감사하겠습니다.

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

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

문의하신 내용은 Open API에서 제공하는 기능과 외부 단말 연동·가맹·정산 계약에 따라 확인해야 하는 사항으로 나눠 안내 드립니다.

1. 외부 단말 연동과 데이터 수집 · 문의 2번

프론트 플러그인 SDK와 DLL은 토스 프론트 연동용이며, 듀얼아이 등 외부 리더기의 직접 연동 규격과는 다릅니다.

외부 리더기는 단말 모델, 부스 운영체제, 결제 모듈과 VAN·PG에 맞는 연동 규격을 확인해야 합니다.

2. 주문·단말 식별 · 문의 3번

Open API 결제 조회와 결제 웹훅에서는 merchantId, orderId, 결제 ID를 확인할 수 있지만, 결제 단말의 TID·시리얼 번호는 제공하지 않습니다.

여러 단말의 거래를 구분하려면 자체 연동 단계에서 부스·단말·주문번호와 결제 결과의 연결 정보를 관리해야 합니다. 외부 단말에 전달한 자체 주문번호를 Open API로 구성 가능한지는 연동가이드 스펙 혹은 직접 테스트 해주시어 검토 부탁 드리겠습니다.

Open API 결제 가이드

3. 결제 취소와 응답 유실 · 문의 4번

• 프론트 플러그인은 전액 취소만 지원하며, 무카드 취소는 NICE의 카드 결제에서 원거래의 vanTransactionKey를 사용하는 방식입니다. 이 조건을 외부 리더기에 동일하게 적용할 수는 없습니다.
• Open API에서는 취소된 결제의 기존 결제 ID를 유지하고 상태와 취소 시각을 갱신합니다. 다만 Open API의 결제 취소 기록 기능은 실제 카드 승인을 취소하는 기능이 아닙니다.
• 프론트 SDK는 같은 paymentKey로 getPayment·getPaymentCancel을 호출해 단말에 저장된 승인·취소 성공 결과를 다시 확인할 수 있습니다. 이는 실시간 VAN 거래 조회가 아니므로, 조회 결과가 없다는 이유만으로 거래 실패를 단정하면 안 됩니다. 외부 리더기의 응답 유실 확인 방법은 해당 결제 모듈의 규격을 따라야 합니다.

프론트 결제 API 가이드 · 결제 테스트 가이드

4. 승인시각·과거 내역·호출 한도 · 문의 5·7번

• approvedAt은 결제 승인시각이며, 매장의 영업 마감일자가 아닙니다. 초·밀리초 단위의 숫자가 아니라 ISO 8601 문자열이며, 끝에 Z가 붙은 값은 UTC 기준입니다. POS의 영업일별 매출 집계 기준은 이 필드와 구분해야 합니다.
• 앱 설치 이전이라도 토스 서버에 저장된 해당 매장의 주문·결제 내역은 조회할 수 있습니다. 구체적인 보관기간은 조회 기능과 별도로 확인이 필요합니다.
• 주문 목록은 페이지당 최대 500건입니다. 호출 한도는 매장별로 토큰을 초당 10개 충전하고 최대 100개까지 보유하는 방식입니다. 대량 조회도 응답의 잔여 호출량과 429 응답을 확인해 속도를 조절해 주세요.

Open API 공통 가이드

5. PG 구분과 정산 자료 · 문의 6·8·9번

settlementType의 PG는 결제수단이 아니라 정산 주체의 종류를 뜻합니다. settlementSubject는 정산 주체를 나타내는 문자열이며, 고정된 전체 값 목록은 제공중이지 않습니다.

PG 상세에는 토스페이먼츠가 포함될 수 있고, 값이 제공되는 경우 pgDetails의 provider와 transactionId로 PG사와 거래 ID를 확인할 수 있습니다. 두 서비스의 거래 ID가 동일하다는 의미는 아닙니다.

현재 Open API는 결제 건별 실제 차감 수수료, 입금 예정일·예정액, 실제 입금 내역을 제공하지 않습니다. 따라서 실제 수수료를 반영한 점포별 정산에는 별도의 정산 자료가 필요합니다.

Open API 결제 가이드

아래 토스페이먼츠 PG 거래에 관한 아래 항목은 토스페이먼츠 계약·도입 담당자에게 문의 부탁 드립니다.

• 매장별·결제 건별 실제 수수료와 정산 자료 제공 범위 및 제공 방식
• 정산금의 입금 단위·일정·통장 적요와 매장별 구분 방법
• 토스플레이스 결제 내역과 페이먼츠 정산 자료의 중복 집계 여부 및 거래 대조 기준

토스페이먼츠에는 별도의 정산 조회 API가 있습니다. 다만 이번 외부 단말 결제에도 해당 API를 적용할 수 있는지는 페이먼츠 측에 확인해 주세요.

카드사에서 직접 정산받는 거래는 해당 카드사·VAN 또는 대리점에 확인해야 합니다. 토스페이 거래도 페이먼츠 PG를 경유하는지에 따라 확인 창구가 달라지므로, 모든 토스페이 정산을 토스페이먼츠 정산과 동일하게 보시면 안 됩니다.

6. 매장 개설·단말 제공·계약 조건 · 문의 1·10·11번

토스페이먼츠 오프라인 결제 도입을 검토 중이라면 아래 사항은 페이먼츠 계약·도입 담당자에게 먼저 문의 부탁 드립니다.

• 해당 도입 상품의 대형가맹점 판정 기준, 온라인 카드 매출 합산 여부 및 단말 구매·임대 조건
• 회사 명의 단말을 다른 사업자가 운영하는 점포에 설치하고, 결제대금을 가맹점주에게 정산하는 구조의 허용 여부와 심사 조건·필요 서류
• 토스페이먼츠의 사업자 정보·정산 계좌 변경 절차 및 계약 해지·이용 정지에 따른 영향

또한 두 서비스 간 정보 변경의 자동 반영 여부와 계약의 상호 영향은 토스플레이스와 토스페이먼츠 각각의 계약 기준으로 확인해야 합니다.

특히 회사 명의로 결제받은 금액을 가맹점주에게 정산하는 구조는 기술 연동 가능 여부와 별도로 사전 확인이 필요합니다.