Square Terminal 결제 게이트웨이
Square Terminal 게이트웨이를 사용하면 WCPOS에서 Square Terminal 하드웨어로 WooCommerce 주문 결제를 직접 수금할 수 있습니다. WooCommerce에서 결제가 요청되고, 페어링된 Square Terminal 기기에서 결제가 완료되며, 결과가 주문에 기록됩니다.
기능
하드웨어 연동
페어링된 Square Terminal 기기로 결제를 전송하고 카드 대면 결제를 수금합니다
원클릭 연결
Square에서 바로 인증합니다 — 액세스 토큰을 만들거나 붙여넣을 필요가 없습니다
안정적인 완료 처리
결제는 폴링과 백그라운드 스위퍼로 확인되며, 웹훅을 추가하면 더 빨라집니다
안전한 거래
PCI 규격을 준수하며, Square 하드웨어에서 카드 대면 결제를 처리합니다
샌드박스 및 프로덕션
실제 결제로 전환하기 전에 Square 샌드박스에서 검증하세요
작동 방식
브라우저 SDK 게이트웨이와 달리, Square Terminal은 Square의 서버 측 Terminal API를 사용합니다. 결제를 시작하면 WooCommerce가 해당 주문에 대한 Terminal Checkout을 생성하고, Square가 이를 페어링된 기기로 전송합니다. 고객이 터미널에서 결제하면 그 결과가 주문에 기록됩니다.
결제가 확인되는 방식. POS는 결제가 진행되는 동안 Square를 폴링하며, 백그라운드 스위퍼가 폴링이 놓친 항목(예: 브라우저 탭이 닫힌 경우)을 대사합니다. Square 웹훅은 대기 시간을 줄여 주는 선택 사항이며, 필수가 아닙니다. 웹훅이 없는 사이트에서도 결제가 유실되지 않습니다.
Square Terminal 기기는 온라인 상태여야 하며, 플러그인과 동일한 Square 계정 및 위치에 로그인되어 있어야 합니다.
설정
Square Terminal for WooCommerce 설치
WP Admin > POS > 설정 > 확장에서 설치하거나, GitHub 릴리스 페이지에서 최신 플러그인 zip 파일(GitHub 소스 코드 zip 또는 tarball이 아닌)을 다운로드한 후 플러그인 > 새로 추가 > 플러그인 업로드를 통해 업로드하세요.
Square에 연결
WP Admin > WooCommerce > 설정 > 결제로 이동하여 Square Terminal을 엽니다- Square 계정 아래에서 환경을 선택합니다 — 테스트용은
Sandbox, 실결제용은Production입니다 - Connect to Square를 클릭하고 Square가 표시하는 권한을 승인합니다
- 위치 ID를 선택합니다 — Terminal이 결제를 수금하는 Square 위치입니다
연결하기 전에 환경을 선택하세요. 하나의 연결은 한 환경에만 적용되며, 샌드박스 연결로는 프로덕션 결제를 승인할 수 없습니다.
환경과 위치 ID가 해당 플러그인의 설정에서 미리 채워집니다. 읽어오는 값은 이 두 가지뿐이며, 플러그인 간에 자격 증명은 공유되지 않으므로 여기에서 별도로 연결하거나 액세스 토큰을 입력해야 합니다.
고급 설정을 열고 연결하는 대신 선택한 환경의 액세스 토큰을 붙여넣으세요. 나머지는 동일하게 작동합니다.
Square Terminal 페어링
Terminal 아래에서:
- 기기 코드 생성을 클릭하면 페어링 코드가 표시됩니다
- Square Terminal에서 기기 코드 로그인 화면을 열고 코드를 입력합니다. 해당 Terminal이 현재 Square POS나 다른 연동에 로그인되어 있다면 먼저 로그아웃하세요 — 다른 곳에서 사용 중이면 기기 코드 화면에 접근할 수 없습니다.
- 리더 확인을 클릭하여 해당 기기가 이제 이 플러그인과 페어링됨에 표시되는지 확인합니다
페어링 전에 목록이 비어 있는 것은 정상이며 오류가 아닙니다. Square의 기기 API는 Terminal API 용도로 설정된 Terminal만 보고하므로, Square POS를 실행 중인 Terminal은 기기 코드를 입력하기 전까지 전혀 표시되지 않습니다.
WCPOS에서 활성화
WP Admin > POS > 설정 > 결제로 이동합니다- Square Terminal 게이트웨이를 찾아 POS에서 활성화합니다
- 설정을 저장합니다
WooCommerce 설정 화면의 활성화/비활성화 체크박스는 온라인 스토어 결제에만 적용됩니다. WCPOS는 이 게이트웨이가 구성되어 있으면 해당 체크박스와 관계없이 자동으로 사용합니다.
Terminal 페어링
계산원이 Square Terminal을 선택할 수 있으려면 먼저 이 플러그인과 페어링되어야 합니다. 페어링은 Terminal API 기기 코드를 생성하며, 플러그인이 해당 기기를 지정할 수 있는 유일한 방법입니다.
설정 화면의 Terminal 아래에서:
- 기기 코드 생성 — Terminal에 입력할 코드를 생성합니다. 유효 시간이 짧으므로 만료되면 새로 생성하세요.
- 리더 확인 — Square가 볼 수 있는 기기를 두 그룹으로 나열합니다:
- 이 플러그인과 페어링됨 — 결제 시 선택할 수 있습니다
- 이 위치에서 Square가 볼 수 있는 다른 기기 — 다른 애플리케이션에서 설정한 기기이므로 이 플러그인과 페어링하기 전까지는 여기에서 선택할 수 없습니다
- 설정 검증 — 자격 증명과 위치를 Square와 대조하여 확인합니다
기기 코드는 이를 생성한 애플리케이션에 귀속되므로, 다른 Terminal API 연동에서 설정한 Terminal은 Square가 볼 수 있는 다른 기기에 표시되지만 여기에서는 선택할 수 없습니다. Square POS를 실행 중인 Terminal은 아예 표시되지 않습니다.
어느 경우든 해결 방법은 같습니다. 해당 Terminal을 현재 페어링된 곳에서 로그아웃한 뒤, 여기에서 기기 코드 생성으로 새 코드를 입력하세요.
웹훅
웹훅은 선택 사항입니다. 결제 확인에 걸리는 시간을 줄여 줍니다. 웹훅이 없어도 폴링과 백그라운드 스위퍼가 모든 결제를 확인하므로, 웹훅 구독이 없는 사이트도 정상적으로 작동합니다 — 정산이 조금 느릴 뿐입니다.
웹훅 구독은 Square 애플리케이션에 귀속되며, 구독을 추가하려면 Square Developer Dashboard에서 해당 애플리케이션에 접근할 수 있어야 합니다. Connect to Square로 연결했다면 직접 소유한 애플리케이션이 아니라 WCPOS 애플리케이션을 인증한 것이므로, 구독을 추가할 대시보드도, 복사할 서명 키도 없습니다.
결제는 폴링과 스위퍼를 통해 정상적으로 확인됩니다. 아래 단계는 고급 설정에서 직접 발급한 액세스 토큰으로 플러그인을 설정한 경우에만 해당합니다.
직접 소유한 Square 애플리케이션으로 웹훅을 추가하려면:
- 설정 화면의 Terminal → 웹훅에서 복사를 클릭하여 웹훅 URL을 복사합니다
- Square Developer Dashboard에서 애플리케이션을 열고 Webhooks로 이동합니다
terminal.checkout.updated이벤트에 대한 구독을 추가하고, 복사한 URL을 알림 URL로 붙여넣습니다- Square의 웹훅 서명 키를 플러그인의 고급 설정에 복사합니다
그러면 웹훅 행에 서명이 검증된 웹훅이 도착했는지, 그리고 언제 도착했는지가 표시됩니다.
Square는 전달받은 알림 URL을 기준으로 각 웹훅에 서명합니다. Square에 등록된 URL이 플러그인의 URL과 한 글자라도 다르면 모든 전송이 검증에 실패합니다. 직접 입력하지 말고 복사 버튼을 사용하세요.
Square의 Webhook Subscriptions API는 개별 판매자가 아니라 애플리케이션 단위로 범위가 정해져 있으며, 판매자 액세스 토큰으로는 호출할 수 없습니다. 따라서 플러그인이 구독을 대신 생성할 수 없습니다.
웹훅 검증이 되지 않는 경우
현재 설정에서 검증된 웹훅이 아직 도착하지 않았다면 웹훅 행에 아직 검증되지 않음이 표시됩니다. 이미 결제가 실행되었다면 다음 순서로 확인하세요:
- 고급 설정의 웹훅 서명 키가 Square의 키와 일치하는지
- Square의 알림 URL이 플러그인에 표시된 URL과 정확히 일치하는지
terminal.checkout.updated이벤트가 구독되어 있는지- 사이트가 HTTPS를 통해 공개적으로 접근 가능한지 — Square Dashboard에서 전송 시도를 확인하세요
환경, 웹훅 URL, 서명 키를 변경하면 다음 웹훅이 도착할 때까지 이 행이 초기화됩니다. 이는 의도된 동작으로, 이전 설정에서 검증된 전송은 새 설정에 대해 아무것도 보장하지 않기 때문입니다.
설정 참조
설정 화면은 설정을 진행하는 순서대로 구성되어 있습니다.
| 섹션 | 포함 항목 |
|---|---|
| Square 계정 | 환경, Connect to Square, 위치 ID |
| Terminal | 페어링 컨트롤, 리더 목록, 웹훅 상태 |
| 결제 동작 | 영수증 화면 건너뛰기, 서명 수집, 디버그 로그 |
| 고급 설정 | 액세스 토큰, 웹훅 서명 키, 웹훅 URL 재정의 |
고급 설정은 기본적으로 접혀 있습니다. 연결하지 않는 경우에만 필요한 수동 액세스 토큰과 웹훅 서명 키가 여기에 있습니다. 웹훅 URL 재정의는 프록시나 사용자 지정 도메인 뒤에 있어 공개 URL이 플러그인이 도출한 URL과 다른 경우가 아니라면 비워 두어야 합니다.
사용 방법
결제 처리
- 상품 추가: POS에서 장바구니에 상품을 추가합니다
- 게이트웨이 선택: 결제 수단으로 "Square Terminal"을 선택합니다
- 기기 선택: Terminal 기기 목록에서 페어링된 단말기를 선택합니다
- 결제 시작: 결제 시작을 클릭하면 Square가 해당 기기로 결제를 전송합니다
- 고객 결제: 고객이 Square Terminal에서 카드를 탭하거나 삽입하거나 스와이프합니다
- 완료: 대기 중 상태가 실시간으로 업데이트되며, Square가 결제를 확인하면 주문이 결제 완료로 표시됩니다
Sandbox에서는 기기 목록에 Square가 문서화한 테스트 기기 ID가 표시되므로, 하드웨어 없이도 성공·시간 초과·오프라인 등 모든 결과를 시험해 볼 수 있습니다.
결제 제어
- 결제 시작: 선택한 터미널로 새 결제 요청을 전송합니다
- 결제 취소: 터미널에서 현재 진행 중인 결제를 취소합니다
- 상태 확인: Square에 현재 상태를 즉시 조회합니다
- 결제 해제: 응답하지 않는 터미널을 분리하여 다른 방법으로 주문을 결제할 수 있게 합니다. 중단된 결제도 백그라운드에서 계속 대사됩니다
- 결제 로그: 각 Square 단계와 결과를 기록하는 선택적 주문별 로그입니다
주문 관리
- 검증된 완료 처리: 주문은 Square의 Payment 객체와 대조하여 결제가 검증된 후에만 결제 완료로 표시되며, 검증되지 않은 신호만으로는 절대 표시되지 않습니다
- 결제 추적: Square 식별자와 결제 로그가 주문에 저장되며, 주요 단계가 주문 메모에 기록됩니다
- 영수증 생성: 결제가 완료되면 표준 POS 영수증이 생성됩니다
요구 사항
하드웨어 호환성
Square Terminal은 Square의 서버 측 Terminal API를 사용합니다. 결제는 사이트에서 생성되어 Square를 통해 페어링된 기기로 전달됩니다. 단말기는 온라인 상태여야 하며 플러그인과 동일한 Square 계정 및 위치에 로그인되어 있어야 합니다.
지원 단말기
- Square Terminal ✅ — Square 전용 카운터탑 카드 단말기
범위 및 제한 사항
- POS / 주문 결제 흐름에 초점을 맞추고 있습니다. 고객용 스토어프론트 결제 페이지에서의 사용은 기본적으로 비활성화되어 있으며 명시적으로 활성화해야 합니다.
- 결제 수금만 지원되며 환불은 아직 지원되지 않습니다. 향후 환불 지원을 추가할 수 있도록 Square 식별자가 주문에 저장됩니다.
- 웹훅 구독은 Square에서 수동으로 추가해야 합니다. 웹훅을 참조하세요.
문제 해결
일반적인 문제
Terminal 기기 목록이 비어 있음
- Terminal을 먼저 이 플러그인과 페어링해야 합니다 — 기기 코드 생성을 사용하여 코드를 기기에 입력하세요
- Square Dashboard나 Square POS 앱을 통해 페어링한 Terminal은 여기에서 페어링하기 전까지 표시되지 않습니다
- 리더 확인을 클릭하세요. Square가 볼 수 있는 다른 기기에 표시된다면 기기는 존재하지만 이 플러그인과 페어링되지 않은 것입니다
- 위치 ID가 Terminal이 로그인된 위치와 일치하는지 확인하세요
기기가 페어링되지 않음
- 기기 코드가 만료되기 전에 입력했는지 확인하세요 — 기기 코드 생성으로 새 코드를 발급하세요
- 터미널이 온라인 상태이며 플러그인과 동일한 Square 계정 및 위치 ID로 로그인되어 있는지 확인하세요
- 환경이 터미널에 로그인된 계정과 일치하는지 확인하세요
설정 검증 실패
- 연결된 상태라면 Square 계정 행에 여전히 Square에 연결됨이 표시되는지 확인하세요. 다시 연결하라고 안내한다면 인증이 만료된 것입니다
- 액세스 토큰을 사용 중이라면 선택한 환경과 일치하는지 확인하세요 — Sandbox 토큰은 Production에서 작동하지 않으며, 그 반대도 마찬가지입니다
- 위치 ID가 해당 계정에 속하는지 확인하세요
터미널에서는 결제가 완료되었는데 주문 업데이트가 느림
- 웹훅이 해결해 주는 문제입니다. 웹훅이 없으면 다음 폴링이나 백그라운드 스위퍼가 대사할 때 주문이 업데이트됩니다
- 웹훅 행을 확인하세요. 결제가 실행된 뒤에도 아직 검증되지 않음이라면 웹훅 검증이 되지 않는 경우를 따르세요
- 주문이 유실되는 일은 없습니다. 폴링이 놓친 결제는 스위퍼가 대사합니다
결제가 시작되지 않음
- 터미널이 선택되어 있고 기기가 페어링되어 온라인 상태인지 확인하세요
- 기기가 설정된 위치 ID에 로그인되어 있는지 확인하세요
- 결제 로그와
WooCommerce > 상태 > 로그에서 Square API 메시지를 확인하세요
Square 재연결이 필요하다고 표시됨
Square 인증은 자동으로 갱신됩니다. 갱신이 완료되지 못하면 플러그인은 사용할 수 없는 상태로 두는 대신 인증을 종료하고, 설정 화면에서 다시 연결하도록 안내합니다. Square에 다시 연결을 클릭하세요 — 그 외에 변경할 것은 없습니다.
도움 받기
기술 지원 안내:
- 문제를 보고하려면 GitHub 리포지토리를 방문하세요
- 하드웨어 및 API 안내는 Square Terminal API 문서를 참고하세요
- 계정 및 하드웨어 관련 문제는 Square 지원팀에 문의하세요
로그는 WooCommerce > 상태 > 로그의 sqtwc 핸들에 기록되며, 각 기기 조회와 웹훅 결과가 남습니다.
스크린샷
다음 항목을 보여주는 스크린샷이 향후 업데이트에 추가될 예정입니다:
- Square 계정, Terminal, 고급 설정 섹션
- WCPOS 설정에서 게이트웨이 활성화
- POS 결제 화면에서의 결제 처리 워크플로