Square Terminal 결제 게이트웨이
Square Terminal 게이트웨이를 사용하면 WCPOS에서 Square Terminal 하드웨어로 WooCommerce 주문 결제를 직접 수금할 수 있습니다. WooCommerce에서 결제가 요청되고, 페어링된 Square Terminal 기기에서 결제가 완료되며, 결과가 주문에 기록됩니다.
기능
하드웨어 연동
페어링된 Square Terminal 기기로 결제를 전송하고 카드 대면 결제를 수금합니다
간편한 페어링
단기 유효 Square Device Code를 사용하여 WooCommerce에서 터미널을 페어링합니다
웹훅 확인 방식
검증된 Square 웹훅으로 결제 완료를 확인하며, 대기 중 실시간 상태를 표시합니다
안전한 거래
PCI 규격을 준수하며, Square 하드웨어에서 카드 대면 결제를 처리합니다
샌드박스 및 프로덕션
실제 결제로 전환하기 전에 Square 샌드박스에서 검증하세요
작동 방식
브라우저 SDK 게이트웨이와 달리, Square Terminal은 Square의 서버 측 Terminal API를 사용합니다. 결제를 시작하면 WooCommerce가 해당 주문에 대한 Terminal Checkout을 생성하고, Square가 이를 페어링된 기기로 전송합니다. 고객이 터미널에서 결제하면 Square가 서명된 웹훅으로 사이트에 알립니다. 웹훅이 최종 완료 신호이며, POS도 폴링을 수행하므로 대기 중에도 상태가 업데이트됩니다.
이는 Square Terminal 기기가 온라인 상태이고 동일한 Square 계정 및 위치에 로그인되어 있어야 하며, Square가 웹훅을 전달할 수 있도록 사이트가 HTTPS를 통해 공개적으로 접근 가능해야 함을 의미합니다.
설치
Square Terminal for WooCommerce 설치
WP Admin > POS > 설정 > 확장 에서 설치하거나, GitHub 릴리스 페이지에서 최신 플러그인 zip 파일 (GitHub 소스 코드 zip 또는 tarball이 아닌)을 다운로드한 후 플러그인 > 새로 추가 > 플러그인 업로드 를 통해 업로드하세요.
Square 설정 구성
WP Admin > WooCommerce > 설정 > 결제로 이동하세요- 결제 수단 목록에서 Square Terminal을 찾아 클릭하여 설정을 여세요
- 환경을 선택합니다 (테스트용
Sandbox, 실결제용Production) - 선택한 환경(Sandbox 또는 Production)에 맞는 액세스 토큰을 입력합니다. Square Developer Dashboard에서 확인할 수 있습니다.
- 위치 ID를 입력합니다 — Terminal 결제가 이루어지는 Square 위치입니다
- 웹훅 서명 키와 웹훅 알림 URL을 입력합니다 (다음 단계 참조)
- 설정 검증을 클릭하여 자격 증명이 올바르게 작동하는지 확인한 후 저장합니다
WooCommerce 설정에서 Square Terminal 게이트웨이를 활성화할 필요가 없습니다. 이후 단계에서 POS 전용으로 활성화됩니다.
Square에서 웹훅 설정
Square는 Terminal 결제가 완료되면 서명된 웹훅을 전송하며, 이를 통해 주문이 결제 완료로 표시됩니다.
- Square Developer Dashboard에서 애플리케이션을 열고 웹훅 섹션으로 이동합니다
terminal.checkout.updated이벤트에 대한 구독을 추가합니다- 알림 URL을 플러그인 설정에 표시된 Webhook 알림 URL로 설정하세요 — 정확히 일치해야 합니다
- Webhook 서명 키를 플러그인 설정에 복사하여 수신 이벤트를 검증할 수 있도록 하세요
Square의 Webhook 알림 URL은 플러그인 설정의 값과 정확히 일치해야 하며, Webhook 서명 키도 올바르게 입력되어야 합니다. 일치하지 않으면 Square 결제가 기기에서는 완료되지만 WooCommerce 주문이 업데이트되지 않습니다.
Square Terminal 페어링
- 동일한 설정 페이지에서 기기 코드 생성을 클릭하세요
- 페어링 코드가 생성되어 화면에 표시됩니다
- Square Terminal에서 로그인한 후 기기 페어링 화면에 코드를 입력하세요
- 페어링이 완료되면 터미널이 설정된 위치에 연결됩니다. 기기 ID를 확인해 두세요 — 결제 시 이 ID를 입력해야 합니다
결제를 처리하려면 터미널이 성공적으로 페어링되고 온라인 상태여야 합니다. 다음 단계로 진행하기 전에 페어링이 완료되었는지 확인하세요.
WCPOS에서 활성화
WP Admin > POS > 설정 > 결제로 이동합니다- 목록에서 Square Terminal 게이트웨이를 찾습니다
- POS에서 사용할 게이트웨이를 활성화합니다
- 설정을 저장합니다
사용 방법
결제 처리
- 상품 추가: POS에서 장바구니에 상품을 추가합니다
- 게이트웨이 선택: 결제 수단으로 "Square Terminal"을 선택합니다
- 기기 선택: 결제를 처리할 페어링된 단말기의 단말기 기기 ID를 입력합니다
- 결제 시작: 결제 시작을 클릭하면 Square가 해당 기기로 결제를 전송합니다
- 고객 결제: 고객이 Square Terminal에서 카드를 탭하거나 삽입하거나 스와이프합니다
- 자동 완료: Square의 인증된 웹훅이 결제를 확인하면 주문이 결제 완료로 표시됩니다. 대기 중 실시간으로 상태가 업데이트됩니다.
결제 제어
Square Terminal 게이트웨이를 사용할 때 다음 옵션을 사용할 수 있습니다:
- 결제 시작: 선택한 터미널로 새 결제 요청을 전송합니다
- 결제 취소: 터미널에서 현재 진행 중인 결제를 취소합니다
- 결제 상태: 실시간 상태 영역에 현재 결제 상태가 표시됩니다
- 결제 로그: 주문별 로그에 각 주요 Square 단계와 결과가 기록됩니다
주문 관리
- 웹훅 기반 완료 처리: 인증된 Square 웹훅이 터미널 결제를 확인한 경우에만 주문이 결제 완료로 표시됩니다
- 결제 추적: Square 식별자와 결제 로그가 주문에 저장되며, 주요 단계가 주문 메모에 기록됩니다
- 영수증 생성: 결제가 완료되면 표준 POS 영수증이 생성됩니다
요구 사항
하드웨어 호환성
Square Terminal은 Square의 서버 측 Terminal API를 사용합니다. 결제는 사이트에서 생성되어 Square를 통해 페어링된 기기로 전달됩니다. 단말기는 온라인 상태여야 하며 동일한 Square 계정 및 위치에 로그인되어 있어야 하고, 주문이 업데이트되려면 사이트에서 HTTPS를 통해 Square 웹훅을 수신할 수 있어야 합니다.
지원 단말기
- Square Terminal ✅ — Square 전용 카운터탑 카드 단말기
범위 및 제한 사항
- 이 초기 릴리스는 POS / 주문 결제 흐름에 초점을 맞추고 있습니다. 고객용 스토어프론트 결제 페이지에서의 사용은 기본적으로 비활성화되어 있으며 명시적으로 활성화해야 합니다.
- 결제 수금만 지원되며 환불은 아직 지원되지 않습니다. 향후 환불 지원을 추가할 수 있도록 Square 식별자가 주문에 저장됩니다.
문제 해결
일반적인 문제
기기가 페어링되지 않음
- 기기 코드가 만료되기 전에 입력했는지 확인하세요 — 필요한 경우 기기 코드 생성으로 새 코드를 발급하세요
- 터미널이 온라인 상태이며 플러그인과 동일한 Square 계정 및 위치 ID로 로그인되어 있는지 확인하세요
- 환경(Sandbox/Production)과 액세스 토큰이 터미널에 로그인된 계정과 일치하는지 확인하세요
설정 유효성 검사 실패
- 액세스 토큰이 선택한 환경과 일치하는지 확인하세요(Sandbox 토큰은 Production에서 작동하지 않으며, 그 반대도 마찬가지입니다)
- 위치 ID가 해당 계정에 속하는지 확인하세요
- 불필요한 문자가 포함되었을 수 있으므로 Square Developer Dashboard에서 토큰을 다시 복사하세요
터미널에서 결제가 완료되었지만 주문이 업데이트되지 않음
- Square의 웹훅 알림 URL이 플러그인 설정과 정확히 일치해야 합니다
- Square Developer Dashboard에서
terminal.checkout.updated이벤트가 구독되어 있는지 확인하세요 - 플러그인의 웹훅 서명 키가 Square의 키와 일치하는지 확인하세요
- 사이트가 HTTPS를 통해 공개적으로 접근 가능한지 확인하고, Square Dashboard에서 웹훅 전송 시도를 점검하세요
결제가 시작되지 않음
- 유효한 터미널 기기 ID가 입력되어 있고, 기기가 페어링되어 온라인 상태인지 확인하세요
- 기기가 설정된 위치 ID에 로그인되어 있는지 확인하세요
- 결제 로그와 WordPress 오류 로그에서 Square API 메시지를 확인하세요
도움 받기
기술 지원 안내:
- 문제를 보고하려면 GitHub 리포지토리를 방문하세요
- 하드웨어 및 API 안내는 Square Terminal API 문서를 참고하세요
- 계정 및 하드웨어 관련 문제는 Square 지원팀에 문의하세요
스크린샷
다음 항목을 보여주는 스크린샷이 향후 업데이트에 추가될 예정입니다:
- Square 자격 증명, 웹훅 및 기기 페어링 구성
- WCPOS 설정에서 게이트웨이 활성화
- POS 결제 화면에서의 결제 처리 워크플로