주 콘텐츠로 건너뛰기
버전: 2.x

Square Terminal 결제 게이트웨이

POS가 Square Terminal로 금액을 전송하면 고객이 단말기에서 결제하고, Square가 승인하면 판매가 자동으로 진행됩니다. 이 페이지는 POS에서 결제 받기와 WP Admin에서 설정하기, 두 부분으로 구성됩니다.

Pro 기능

Square Terminal을 사용하려면 WCPOS Pro 2.0 이상이 필요합니다.

결제 받기​

시작하기 전에
  • POS가 온라인 상태이고 단말기가 켜져 있어야 합니다. Square Terminal 타일이 없으면 WP Admin 관리자에게 설정을 요청하세요.
  • 계산대 열기 및 닫기 기능을 켰다면 계산대가 열려 있어야 합니다. 계산대가 닫혀 있으면 POS가 결제를 기록하지 않으며, 단말기에서 이미 청구한 카드 결제는 환불해야 합니다. 계산대 열기를 참고하세요.
  1. 장바구니에 상품을 담고 결제를 누르세요.
  2. 결제 탭에서 Square Terminal 타일을 누르세요.
  3. 단말기 표시 줄의 단말기: 표시와 단말기 이름을 확인하세요. 단말기가 여러 대이면 변경을 누르고 현재 POS에서 사용할 단말기를 선택하세요. 선택하기 전까지 패널에는 단말기 선택이 표시됩니다.
  4. 금액을 미결제 잔액 그대로 두거나, 일부만 카드로 받으려면 더 적은 금액을 입력하세요. 분할 결제를 참고하세요.
  5. Square Terminal로 $45.00 전송을 누르세요(버튼에는 입력한 금액이 표시됩니다). 패널에 단말기 시작 중… 이 표시된 다음 단말기에서 고객 결제 대기 중이 표시됩니다.
  6. 고객이 단말기에 카드를 대거나 삽입하거나 긁습니다.
  7. Square가 승인하면 승인됨, 매입 완료 단계로 진행됩니다. 잔액이 모두 결제되면 판매가 완료되고 영수증이 표시됩니다. 잔액이 남았다면 같은 방법이나 다른 방법으로 나머지 금액을 받으세요.

결제가 진행되는 동안 패널에 다음 항목이 표시됩니다.

  • 단말기에서 처리 중과 전송한 금액.
  • 단말기에서 고객 결제 대기 중과 같은 한 줄짜리 상태 메시지.
  • 결제 방법과 단말기 이름.
  • 네 단계: 전송됨, 단말기에서 처리 중, 승인됨, 매입 완료.
  • 상세 정보: Square가 보고한 각 단계와 시간, 리더기, 작업, 결제 ID가 표시됩니다. 복사(일부 기기에서는 공유)를 사용하면 지원 담당자에게 로그를 전달할 수 있습니다.
결제 상태 메시지와 조치 방법
  • 승인됨 다음에 매입 완료: 결제 금액을 받았습니다. 잔액이 모두 결제되면 영수증이 표시됩니다. 잔액이 남았다면 나머지 금액을 받으세요.
  • 결제 취소됨: 단말기가 취소를 확인했습니다. 다시 시도 또는 다른 방법 선택을 누르세요.
  • 시간 초과 — 결제 취소됨: 5분 안에 결제가 이루어지지 않았습니다. 다시 시도 또는 다른 방법 선택을 누르세요.
  • 취소 중 — 단말기 확인 대기 중: 단말기가 취소 요청에 응답하지 않았습니다. 기다리거나 이 결제 해제를 누르세요. 결제 중단하기를 참고하세요.
  • 결제 해제됨: 주문을 다른 방법으로 결제할 수 있게 되었지만, 단말기에서 이미 카드에 청구했을 수도 있습니다. 먼저 단말기 화면을 확인하세요.

결제 중단하기​

단말기에서 취소를 누르면 Square에 단말기 결제 취소를 요청합니다. 패널에 취소 중… 이 표시되고, 단말기가 확인하면 결제 취소됨이 표시됩니다. 다시 전송하려면 다시 시도를 누르고, 타일로 돌아가려면 다른 방법 선택을 누르세요.

단말기가 확인하지 못하면(전원이 꺼졌거나 신호가 없거나 멈춘 경우) 패널에 취소 중 — 단말기 확인 대기 중이 표시되고 이 결제 해제 버튼과 함께 주문을 다른 방법으로 결제할 수 있도록 해제합니다. 매장은 계속 단말기를 확인합니다. 안내가 나타납니다.

다시 청구하기 전에 단말기를 확인하세요

결제를 해제해도 Square에서 결제가 취소되지는 않습니다. 매장은 약 10분마다 백그라운드에서 계속 확인합니다. 다른 방법으로 결제를 받기 전에 단말기 화면을 확인하세요. 결제가 완료된 것으로 표시되면 다시 받지 마세요. 매장은 이후 확인 과정에서 해당 결제를 주문에 기록합니다. 문제가 발생한 경우를 참고하세요.

이 결제 해제는 주문을 해제할 뿐, 결제 취소를 확인하는 기능이 아닙니다. 패널에는 결제 해제됨이 표시됩니다. 다른 방법 선택을 누르기 전에 단말기를 확인하세요. 결제가 완료된 것으로 표시되면 다시 청구하지 말고 주문이 업데이트될 때까지 기다리세요. 결제가 취소된 것으로 표시되면 다른 방법 선택을 눌러 타일로 돌아가 다른 방법으로 결제를 받으세요. 확인할 수 없다면(단말기가 꺼져 있거나 신호가 없거나 아무것도 표시되지 않는 경우) 결과를 알 수 없는 상태입니다. 다른 방법으로 결제를 받은 뒤 매장의 확인 과정에서 단말기 결제가 발견되면, 해당 결제도 주문에 기록됩니다. 이때 주문에서 두 결제 중 하나를 환불하세요. 환불을 참고하세요.

5분 안에 단말기에서 결제가 이루어지지 않으면 결제가 취소되고 패널에 시간 초과 — 결제 취소됨이 표시됩니다.

문제가 발생한 경우​

Square Terminal에 설정된 단말기가 없습니다. 아직 이 확장 기능과 페어링된 단말기가 없습니다. WP Admin 관리자에게 페어링을 요청하세요.

주문 #…에서 사용 중 해당 단말기가 다른 주문의 결제를 처리하고 있습니다. 먼저 해당 결제를 완료하거나 취소하거나, 다른 단말기를 선택하세요.

결제 실패와 사유가 표시됩니다. 다시 시도 또는 다른 방법 선택을 누르세요. 상세 정보에서 Square의 응답을 확인할 수 있습니다.

취소 중 — 단말기 확인 대기 중. 단말기가 취소 요청에 응답하지 않았습니다. 기다리거나 이 결제 해제를 누르세요. 결제 중단하기를 참고하세요.

단말기에서 결제가 완료되었지만 POS가 계속 대기합니다. POS는 대기 중에 Square에 계속 확인하며, Square가 응답하면 다음 단계로 진행합니다. 웹훅을 사용하면 매장이 더 빨리 통지를 받습니다. POS가 대기를 중단한 경우(POS를 닫았거나 결제를 해제한 경우), 약 10분마다 실행되는 매장의 백그라운드 확인이 POS가 놓친 결제를 기록합니다. 대기 중에는 다른 방법으로 결제를 받지 말고 먼저 단말기 화면을 확인하세요.

타일이 없습니다. POS에서 이 결제 게이트웨이가 활성화되지 않았습니다. POS에서 활성화하기를 참고하세요.

WP Admin 관리자를 위한 설정 문제 해결
단말기가 목록에 없습니다

이 확장 기능과 페어링해야 합니다. 기기 코드 생성을 사용하고 단말기에 코드를 입력하세요. Square 대시보드나 Square 앱을 통해 페어링한 단말기는 여기에서 페어링하기 전까지 표시되지 않습니다. 리더기 확인에서 이 위치에서 Square가 감지한 다른 기기 아래에 표시된다면, 기기는 있지만 다른 애플리케이션에 속해 있다는 뜻입니다. 위치 ID가 단말기에 로그인된 위치와 일치하는지도 확인하세요.

단말기가 페어링되지 않습니다

코드의 유효 시간은 5분이므로 새 코드를 생성하세요. 이 코드는 여기에서 설정한 계정과 위치 ID로 로그인하므로, 단말기가 온라인 상태이고 Square 앱이나 다른 연동 서비스에서 로그아웃되어 있어야 합니다. 환경도 해당 계정과 일치해야 합니다.

설정 검증에 실패합니다

연결 기능을 사용했다면 Square 계정 행에 여전히 Square에 연결됨이 표시되는지 확인하세요. 직접 발급한 액세스 토큰을 사용한다면 선택한 환경용 토큰인지 확인하세요. 샌드박스 토큰은 실운영에서 작동하지 않으며 그 반대도 마찬가지입니다. 위치 ID가 해당 계정에 속하는지 확인하세요.

Square에 다시 연결해야 합니다

Square 인증은 자동으로 갱신됩니다. 갱신을 완료할 수 없으면 확장 기능이 인증을 종료하고 다시 연결하도록 요청합니다. Square에 다시 연결을 누르세요. 다른 설정은 변경할 필요가 없습니다.

로그를 찾는 위치

WooCommerce > Status > 로그에서 소스 square-terminal-for-woocommerce를 확인하세요. 주요 단계는 주문 메모에도 Square Terminal:로 시작하는 항목으로 기록됩니다.

설정하기​

이 부분은 매장의 WP Admin 관리자를 위한 안내입니다. 매장이 각 결제를 Square로 보내고 Square가 페어링된 단말기로 보내므로, POS는 매장에 연결되어 있어야 합니다. 다음 네 단계를 순서대로 진행하세요.

  1. 확장 기능 디렉터리에서 확장 기능을 설치하세요.
  2. Square에 연결하고 위치를 선택하세요.
  3. 단말기를 페어링하거나 샌드박스에서 Square의 테스트 기기를 사용하세요.
  4. POS에서 활성화하세요.

확장 기능 설치하기​

WP Admin > POS > 설정 > 확장을 열고 Square Terminal을 찾은 다음 설치, 활성화를 차례로 클릭하세요. 확장 기능 설치하기를 참고하세요.

디렉터리를 사용할 수 없다면 GitHub 릴리스 페이지에서 플러그인 zip(소스 코드 zip이 아님)을 다운로드한 후 플러그인 > Add Plugin에서 플러그인 업로드를 눌러 업로드하세요. WCPOS Pro 2.0이 없으면 확장 기능이 작동하지 않으며 해당 버전이 필요하다는 안내가 표시됩니다.

Square에 연결하기​

  1. WP Admin > WooCommerce > 설정 > 결제로 이동하여 Square Terminal을 여세요.
  2. Square 계정에서 환경을 선택하세요. 시험해 보려면 테스트 모드(샌드박스)(기본값), 실제 결제를 받으려면 실운영을 선택하세요. 연결 하나는 환경 하나에만 적용되므로 연결하기 전에 선택하세요.
  3. Square에 연결을 클릭하고 Square가 요청하는 권한을 승인하세요.
  4. 단말기가 결제를 받을 Square 위치의 위치 ID를 선택하세요.
  5. 어떤 Square 기기를 사용하시나요? 항목에서 Square Terminal을 그대로 두세요.

이미 공식 WooCommerce Square 플러그인을 사용하고 있나요? 해당 플러그인의 환경과 위치 ID가 미리 입력됩니다. 저장하여 적용하세요. 두 플러그인은 인증 정보를 공유하지 않으므로 여기에서도 연결해야 합니다.

직접 발급한 액세스 토큰을 사용하고 싶다면 연결 기능 대신 고급 설정을 열고 샌드박스 액세스 토큰 또는 프로덕션 액세스 토큰을 붙여넣으세요.

단말기 페어링하기​

단말기에서 기기 코드 생성을 클릭하고 5분 안에 단말기에 코드를 입력하세요. 그런 다음 리더기 확인을 클릭하세요. 전체 절차, 목록에 표시되는 내용, 샌드박스 테스트 기기에 대해서는 페어링된 단말기와 테스트 기기를 참고하세요.

POS에서 활성화하기​

WP Admin > POS > 설정 > 결제로 이동하여 Square Terminal을 찾고 활성화를 켜세요. 결제 게이트웨이 활성화하기를 참고하세요.

참고

Square Terminal은 POS 직원 전용이며 온라인 쇼핑몰의 결제 화면에는 표시되지 않습니다. WooCommerce 결제 목록의 활성화 토글은 이 기능에 영향을 주지 않습니다.

페어링된 단말기와 테스트 기기​

캐셔가 단말기를 선택하려면 먼저 이 확장 기능과 페어링해야 합니다. 페어링 과정에서 Square 기기 코드가 생성되며, 확장 기능은 이 방법으로만 단말기에 연결할 수 있습니다.

  1. 단말기에서 기기 코드 생성을 클릭하세요. 화면에 페어링 코드: … — 5분 안에 단말기에 입력하세요. 안내가 표시됩니다.
  2. 단말기에서 기기 코드 로그인 화면을 열고 코드를 입력하세요. 단말기가 Square 앱이나 다른 연동 서비스에 로그인되어 있다면 먼저 로그아웃하세요. 다른 곳에서 사용 중인 동안에는 기기 코드 화면을 열 수 없습니다.
  3. 리더기 확인을 클릭하세요. 이제 이 플러그인과 페어링됨 — 결제 시 선택 가능 아래에 단말기가 표시됩니다.

리더기 확인은 Square가 감지한 기기를 두 그룹으로 나누어 표시합니다.

  • 이 플러그인과 페어링됨 — 결제 시 선택 가능: 캐셔가 선택할 수 있는 단말기입니다.
  • 이 위치에서 Square가 감지한 다른 기기: 다른 애플리케이션에서 설정한 단말기입니다. 새 코드로 페어링하기 전까지는 여기에서 선택할 수 없습니다.

설정 검증은 연결(또는 액세스 토큰)과 위치가 정상적으로 작동하는지 Square에 확인합니다. 정상이라면 Square 인증 정보와 위치가 확인되었습니다. 메시지가 표시됩니다.

페어링 전에는 목록이 비어 있어도 정상입니다

Square는 기기 코드로 페어링된 단말기만 목록에 표시합니다. Square 앱을 실행 중인 단말기는 기기 코드를 입력하기 전까지 전혀 표시되지 않습니다.

테스트 모드: 단말기 대신 Square의 테스트 기기 사용

테스트 모드(샌드박스) 에는 기기 코드가 없으며 페어링할 필요도 없습니다. POS는 페어링된 단말기가 표시될 자리에 Square의 테스트 기기를 표시합니다. 각 기기는 하드웨어 없이 특정 결과를 재현합니다.

테스트 기기재현하는 결과
샌드박스: 성공($25 이하 청구)카드 결제가 승인됩니다. 금액을 $25 이하로 설정하세요.
샌드박스: 20% 팁 포함 성공팁이 포함된 결제입니다. 여기서는 Square가 팁을 받지 않으므로 단말기가 다른 금액을 확인했습니다라는 메시지와 함께 결제가 실패합니다.
샌드박스: 구매자가 단말기에서 취소고객이 단말기에서 취소합니다.
샌드박스: 즉시 시간 초과결제가 이루어지지 않고 즉시 시간이 초과됩니다.
샌드박스: 오프라인 단말기(대기 상태 유지)응답하지 않는 단말기입니다. 하드웨어 없이 결제 중단하기를 시험할 때 사용하세요.

웹훅​

웹훅은 선택 사항입니다. 결제 상태가 바뀌는 즉시 Square가 매장에 알릴 수 있어 POS가 더 빨리 다음 단계로 진행합니다. 웹훅이 없으면 POS는 대기하면서 Square에 결과를 확인하고, 매장의 백그라운드 확인이 약 10분마다 POS가 놓친 결과를 기록합니다. 어느 경우든 Square가 결제 자체를 확인한 경우에만 매장이 결제를 기록합니다. Square에서 결제 절차가 완료된 것으로 표시되는 것만으로는 충분하지 않습니다.

웹훅 추가하기

이 기능은 고급 설정에서 직접 발급한 액세스 토큰으로 확장 기능을 설정한 경우에만 사용할 수 있습니다. Square에 연결을 사용했다면 본인의 애플리케이션이 아닌 WCPOS 애플리케이션에 권한을 부여한 것이므로, 구독을 추가할 애플리케이션도 복사할 서명 키도 없습니다. 그래도 POS 자체 확인과 백그라운드 확인을 통해 결제가 확인됩니다.

직접 발급한 액세스 토큰을 사용하는 경우 Square 개발자 대시보드에서 본인의 애플리케이션으로 다음을 진행하세요.

  1. 설정 화면의 단말기 아래 웹훅 행에서 복사를 클릭하여 웹훅 URL을 복사하세요.
  2. Square 개발자 대시보드에서 애플리케이션을 열고 웹훅으로 이동하세요.
  3. 복사한 URL을 알림 URL로 지정하여 terminal.checkout.updated 이벤트 구독을 추가하세요.
  4. 구독의 서명 키를 복사하여 고급 설정의 웹훅 서명 키에 붙여넣고 저장하세요.

서명된 웹훅이 도착하면 웹훅 행에 … 전에 검증됨이 표시됩니다.

URL이 정확히 일치해야 합니다

Square는 제공받은 알림 URL로 각 웹훅에 서명합니다. Square에 입력한 URL이 설정 화면의 URL과 한 글자라도 다르면 모든 전송이 실패합니다. 직접 입력하지 말고 복사를 사용하세요.

버전 0.x에서 업그레이드하기

버전 1.0.0에는 새 웹훅 URL이 표시됩니다. 기존 구독이 있다면 Square에서 해당 구독의 알림 URL을 현재 설정 화면에 표시되는 URL로 수정하세요. 수정하면 서명 키는 유지됩니다. 웹훅 URL 재정의는 이 URL을 변경하지 않으며 확장 기능 자체의 결제 페이지에만 적용됩니다. 사이트의 공개 주소가 표시된 주소와 다르면 웹훅 검증이 실패하지만, POS 자체 확인과 백그라운드 확인을 통해 결제는 계속 확인됩니다.

Square의 웹훅 구독은 Square 애플리케이션에 속하며 판매자의 액세스 토큰으로는 추가할 수 없으므로, 확장 기능이 대신 구독을 추가할 수 없습니다.

웹훅 검증이 중단된 경우​

웹훅이 도착하여 현재 설정으로 검증될 때까지 웹훅 행에는 아직 검증되지 않음이 표시됩니다.

결제가 이루어졌는데도 아직 검증되지 않음이 표시됩니다

다음을 확인하세요.

  1. 웹훅 서명 키가 Square의 구독 키와 일치하는지 확인하세요.
  2. Square의 알림 URL이 설정 화면의 URL과 정확히 일치하는지 확인하세요.
  3. 구독에 terminal.checkout.updated가 포함되어 있는지 확인하세요.
  4. 인터넷에서 HTTPS로 사이트에 접속할 수 있는지 확인하세요. Square 대시보드에서 각 전송 시도를 볼 수 있습니다.

환경, 웹훅 URL 또는 서명 키를 변경하면 다음 웹훅이 도착할 때까지 이 행의 상태가 초기화됩니다. 이전 설정에서 웹훅이 검증되었다고 새 설정도 유효한 것은 아니므로 의도된 동작입니다.

설정 참조​

WP Admin > WooCommerce > 설정 > 결제 > Square Terminal의 항목을 설정 순서대로 안내합니다. 그룹을 열면 해당 설정을 볼 수 있습니다.

Square 계정
  • 환경: 테스트 모드(샌드박스)(기본값) 또는 실운영입니다. 연결 하나는 환경 하나에만 적용됩니다.
  • Square에 연결: Square에서 이 사이트에 권한을 부여합니다. 완료되면 Square에 연결됨, 판매자, 연결 해제가 표시됩니다.
  • 위치 ID: 단말기가 결제를 받는 Square 위치입니다.
  • 어떤 Square 기기를 사용하시나요?: Square Terminal(이 페이지에서 설명하는 기본값) 또는 Square Reader입니다.
단말기
  • 기기 코드 생성, 리더기 확인, 설정 검증: 각각 단말기를 페어링하고, Square가 감지한 기기를 나열하고, 설정을 확인합니다. 페어링된 단말기와 테스트 기기를 참고하세요.
  • 웹훅: 서명된 웹훅의 수신 여부와 복사할 URL을 표시합니다. 웹훅을 참고하세요.
결제 동작
  • 영수증 화면 건너뛰기: 단말기가 자체 영수증 화면을 표시하지 않고 대기 상태로 돌아갑니다.
  • 서명 받기: 해당 결제가 지원하는 경우 고객에게 단말기에서 서명하도록 요청합니다.
  • 결제 디버그 로그: 확장 기능 자체의 결제 페이지에 복사 가능한 로그 패널을 표시합니다. 지원용 기능이므로 꺼 두어도 됩니다.
고급 설정
  • 샌드박스 액세스 토큰, 프로덕션 액세스 토큰: 위의 연결 기능을 사용하지 않을 때만 필요합니다.
  • 웹훅 서명 키: 선택 사항입니다. 매장이 웹훅을 검증할 수 있게 하며, 없어도 결제는 확인됩니다.
  • 웹훅 URL 재정의: 확장 기능 자체의 결제 페이지에만 적용됩니다. 웹훅을 참고하세요.

설정 화면에서도 고급 설정은 기본적으로 접혀 있습니다.

단말기 대신 Square Reader 사용하기​

어떤 Square 기기를 사용하시나요? 항목을 Square Reader로 설정하면, 휴대폰이나 태블릿에 페어링된 Square Reader를 사용하여 Square Point of Sale 앱에서 결제를 받을 수 있습니다. 설정 화면에는 다섯 단계로 된 Square Reader 설정 체크리스트가 표시됩니다.

Square Reader 설정의 다섯 단계
  1. Square 계정을 연결하세요.
  2. 위치를 선택하세요.
  3. Square에 매장을 등록하세요. 애플리케이션 ID를 붙여넣으세요.
  4. Square에 매장으로 돌아올 주소를 제공하세요.
  5. 휴대폰이나 태블릿을 설정하세요.

POS에서는 레거시 탭에 있는 확장 기능 자체의 결제 페이지에서 결제가 진행됩니다. Square Point of Sale 열기를 누르고 Square 앱에서 결제를 완료하세요. 다음 조건에서만 작동합니다.

  • 테스트 모드가 아닌 실운영에서만 작동합니다.
  • Square Point of Sale 앱이 설치된 Android 또는 iOS 휴대폰이나 태블릿에서만 작동합니다. 그 외의 환경에서는 버튼이 비활성화되고 이유가 표시됩니다.

환불​

주문에서 Square Terminal 결제를 환불하면 Square를 통해 고객의 카드로 금액이 반환됩니다. 부분 환불도 가능합니다. 환불을 참고하세요.

1.0.0 이전 버전에서 받은 결제처럼 확장 기능 자체의 결제 페이지에서 받은 결제는 Square 대시보드에서 환불해야 합니다.

요구 사항​

WCPOS Pro: 버전 2.0.0 이상
Square 계정: 활성 Square 판매자 계정과 Square 위치
Square Terminal: 온라인 상태이며 Square 계정과 위치에 대한 기기 코드로 이 확장 기능과 페어링되어 있어야 합니다(위의 페어링된 단말기와 테스트 기기 참고).
연결: POS와 매장이 온라인 상태여야 합니다. 매장이 각 결제를 페어링된 단말기로 전송하므로 어느 POS에서든 페어링된 모든 단말기를 사용할 수 있습니다.
공개 HTTPS 사이트: 웹훅을 사용할 때만 필요하며, 웹훅 없이도 결제는 확인됩니다.