Windcave 단말기 결제 게이트웨이
Windcave Terminal 게이트웨이를 사용하면 Windcave HIT를 통해 Windcave 단말기에서 대면 카드 결제를 받을 수 있습니다. WCPOS에서 결제를 시작하고 단말기에서 완료하면 확인 내용이 WooCommerce 주문에 기록됩니다.
0.1.0은 첫 번째 릴리스입니다. Windcave는 연동을 운영 환경에서 사용하기 전에 QA 인증을 요구하며, 이 연동은 아직 인증되지 않았습니다. 인증이 완료될 때까지 Windcave UAT(테스트) 자격 증명을 사용하세요. Vendor ID는 인증 과정에서 Windcave가 발급합니다.
기능
클라우드 HIT 연결
Windcave의 클라우드 HIT 서비스를 통해 연결합니다. 단말기마다 Station ID 하나를 사용하며 로컬 페어링은 필요하지 않습니다.
화면에 표시되는 단말기 안내
결제 패널에서 단말기의 안내와 버튼을 확인하세요. 서명 확인을 위한 YES/NO와 CANCEL도 표시됩니다.
검증 후 완료
결제 참조 번호, 금액, 환경, 주문 총액 및 통화를 확인한 후에만 주문이 완료됩니다.
결제 보류
시간 초과 후 대기 중인 결제를 보류하고 계속 진행할 수 있으며, 백그라운드 확인 작업이 후속 처리를 합니다.
결과 알림
선택 사항인 결과 알림(FPRN)을 사용하도록 설정하면 폴링의 보조 수단으로 Windcave가 사이트에 알림을 보낼 수 있습니다.
작동 방식
이 결제 게이트웨이는 HTTPS를 통해 Windcave **HIT (Host Initiated Transaction)**를 사용합니다. Environment에서 UAT 또는 운영 엔드포인트를 선택하며, 각 단말기는 Windcave가 발급한 Station ID로 지정됩니다.
결제를 시작하면 주문 총액과 통화가 단말기로 전송됩니다. 결제 페이지는 1.5초마다 Windcave를 폴링하며 단말기 안내와 사용 가능한 버튼을 화면에 반영합니다. 선택 사항인 **Result notifications (FPRN)**을 사용하면 폴링의 보조 수단으로 Windcave가 사이트에 알림을 보낼 수 있습니다.
설정
Windcave Terminal for WooCommerce 설치
GitHub 릴리스 페이지에서 플러그인 zip 파일(GitHub 소스 코드 zip이 아님)을 다운로드하세요. WooCommerce가 설치되어 활성화된 상태에서 플러그인 > 새로 추가 > 플러그인 업로드를 통해 업로드하고 활성화하세요.
활성화하려면 PHP 7.4+ 및 **PHP DOM 확장(php-xml)**이 필요합니다. 둘 중 하나라도 없으면 메시지와 함께 활성화가 거부됩니다.
Windcave에서 HIT 자격 증명 받기
Windcave에 HIT username, HIT key, 단말기마다 하나씩 필요한 Station ID를 요청하세요. Windcave의 Integration Requirements 양식을 통해 개발자 계정을 신청하세요.
UAT와 운영 자격 증명은 서로 다릅니다. 이 연동의 인증이 완료될 때까지 UAT 자격 증명을 사용하세요.
결제 게이트웨이 구성
WP Admin > WooCommerce > 설정 > 결제로 이동하여 Windcave Terminal을 여세요.- Environment를
UAT (testing)(기본값)으로 설정하세요.Production은 Windcave 인증을 받은 후 운영 자격 증명과 함께 사용합니다. - Windcave에서 발급한 HIT username과 HIT key를 입력하세요.
- Station IDs를 한 줄에 하나씩 입력하세요.
- (선택 사항) Default Station ID를 설정하세요. 항상 해당 기본값을 사용하고 캐셔가 변경하지 못하게 하려면 Lock terminal selection을 사용하도록 설정하세요.
- Windcave가 인증 과정에서 Vendor ID를 발급할 때까지 비워 두세요.
- 설정을 저장하세요.
결과 알림 사용(선택 사항)
**Result notifications (FPRN)**을 사용하도록 설정하고 저장하면 거래 결과가 준비되었을 때 Windcave가 사이트에 알림을 보냅니다. 이는 폴링의 보조 수단입니다.
WCPOS에서 활성화
WP Admin > POS > 설정 > 결제로 이동하세요.- Windcave Terminal 결제 게이트웨이를 찾아 POS에서 사용하도록 설정하세요.
- 설정을 저장하세요.
WooCommerce 설정 화면의 Enable/Disable 체크박스는 온라인 매장 결제만 제어합니다. WCPOS에서는 이 결제 게이트웨이를 구성한 후 해당 체크박스의 선택 여부와 관계없이 사용할 수 있습니다.
설정 참조
| 설정 | 기능 |
|---|---|
| Enable/Disable | 온라인 매장 결제에 결제 게이트웨이를 사용하도록 설정합니다. POS 사용 설정은 POS > 설정 > 결제에서 제어합니다. |
| Title | 결제 시 표시되는 이름입니다. 기본값은 Windcave Terminal입니다. |
| Description | 결제 설명입니다. 기본값은 Pay in person on the Windcave terminal.입니다. |
| Environment | UAT (testing)(기본값) 또는 Production입니다. 각 환경에는 별도의 HIT 자격 증명이 필요하며, 운영 환경을 사용하려면 Windcave 인증이 필요합니다. |
| HIT username | 선택한 환경에 대해 Windcave가 발급한 HIT 사용자 이름입니다. |
| HIT key | 선택한 환경에 대해 Windcave가 발급한 HIT 키입니다. |
| Station IDs | Windcave가 발급한 Station ID를 단말기마다 하나씩, 한 줄에 하나씩 입력합니다. |
| Default Station ID | 미리 선택되는 Station이며, 다른 Station을 선택하지 않은 경우에도 사용됩니다. |
| Lock terminal selection | 항상 기본 Station을 사용하여 캐셔가 변경할 수 없도록 합니다. 기본값을 설정한 경우에만 적용됩니다. |
| Vendor ID | Windcave가 인증 과정에서 발급합니다. Windcave가 제공할 때까지 비워 두세요. |
| POS name | POS를 식별하기 위해 Windcave에 전송하는 이름입니다. 기본값은 WCPOS입니다. |
| Result notifications (FPRN) | 거래 결과가 준비되었을 때 Windcave가 사이트에 알리도록 요청하며 폴링의 보조 수단으로 사용됩니다. 기본적으로 꺼져 있습니다. |
| Checkout logs | 결제 패널에 로그 도구를 표시합니다. 기본적으로 꺼져 있습니다. |
| Log level | Off, Errors only 또는 Debug입니다. 기본값은 Debug이며 키와 카드 데이터를 가린 채 요청과 응답을 기록합니다. |
| Support | Download support bundle 기능과 WooCommerce > Status > 로그에서 로그를 확인하는 링크를 제공합니다. |
연결 테스트 버튼은 없습니다. 첫 결제를 처리할 때 자격 증명과 Station ID를 확인합니다.
사용법
결제 처리
- Add Items: POS 장바구니에 상품을 추가하세요.
- Select Gateway: 결제 수단으로 Windcave Terminal을 선택하세요.
- Choose Terminal: Station을 선택하거나 잠금 설정된 기본값을 사용하세요. Station이 두 개 이상이고 기본값이 없으면 선택해야 합니다.
- Start Payment: Start Terminal Payment를 눌러 주문 총액을 단말기로 전송하세요.
- Follow Prompts: 서명 확인을 위한 YES/NO와 선택 가능한 경우의 CANCEL을 포함하여 단말기 안내와 사용 가능한 버튼이 화면에 표시됩니다.
- Automatic Completion: 승인 및 확인이 끝나면 주문이 완료되고 POS에 영수증이 표시됩니다.
결제 제어
- Start Terminal Payment: 선택한 Station으로 새 결제 요청을 전송합니다.
- Cancel Terminal Payment: 단말기에서 제공하는 경우 단말기의 CANCEL 버튼을 누릅니다. 그렇지 않으면 단말기에서 취소하거나 해당 옵션이 표시될 때 결제를 보류하세요.
- Set payment aside: 5분 시간 초과 후 표시됩니다. 결제 시도를 10분간 백그라운드 확인에 맡겨 두므로 다른 방법으로 결제를 받을 수 있습니다. Windcave의 결제는 취소되지 않습니다.
- 페이지 새로고침: 진행 중인 결제를 다시 이어서 처리합니다.
영수증
Windcave가 반환한 단말기 영수증 텍스트는 WooCommerce의 비공개 주문 메모로 저장됩니다.
환불
WooCommerce에서 환불은 0.1.0에서 지원되지 않습니다. Windcave 포털(Payline) 또는 단말기에서 환불한 다음 WooCommerce에 환불을 수동으로 기록하세요.
로그 및 지원 번들
WooCommerce > Status > 로그에서 windcave-terminal 소스의 로그를 확인하세요. 로그 수준은 기본적으로 Debug이며 키와 카드 데이터를 가린 채 Windcave 요청과 응답을 기록합니다.
결제 게이트웨이 설정 화면에서 지원 번들 다운로드를 클릭해 .json 파일을 다운로드한 다음 주문 번호와 함께 보내세요. 이 파일에는 환경 세부 정보, HIT 키와 사용자 이름을 마스킹한 설정, 영수증을 제외한 최근 주문 최대 20건의 결제 시도, 최신 로그 파일 2개의 마지막 1,000줄이 포함됩니다. 로그 줄에는 카드 번호가 마스킹된 단말기 영수증 텍스트가 포함될 수 있습니다.
WooCommerce에서 데이터베이스 로그 처리기를 사용하는 경우 번들에 로그 줄이 포함되지 않습니다. 대신 WooCommerce > Status > 로그에서 로그를 내보내세요.
Checkout logs를 사용하도록 설정하면 결제 패널에 로그 도구가 표시됩니다.
요구 사항
적용 범위 및 제한 사항
이 연동은 아직 Windcave 인증을 받지 않았습니다. Windcave QA 인증이 완료될 때까지 UAT 자격 증명을 사용하고, 인증 전에 운영 환경에서 사용하지 마세요.
- 0.1.0에서는 WooCommerce 환불을 지원하지 않습니다.
- 팁, 추가 요금 및 현금 인출은 지원하지 않습니다.
- 소수점 이하 두 자리 통화만 지원합니다.
- 단말기에는 주문 총액 전액이 청구됩니다. 주문 금액의 일부만 단말기에서 결제할 수 없습니다.
- Station IDs는 직접 입력해야 하며 단말기를 자동으로 검색하지 않습니다.
- 이 결제 게이트웨이는 POS용으로 만들어졌습니다. 온라인 매장에서는 order-pay 페이지에서만 작동합니다.
문제 해결
일반적인 문제
활성화 거부: PHP DOM 확장(php-xml)이 필요합니다
- 서버에 PHP DOM 확장이 없습니다.
- 호스팅 업체에 php-xml을 활성화해 달라고 요청하세요. 활성화하려면 **PHP 7.4+**도 필요합니다.
Station ID가 구성되지 않음
- Station IDs 설정이 비어 있습니다.
- Windcave에서 발급한 Station ID를 결제 게이트웨이 설정에 한 줄에 하나씩 추가한 다음 저장하세요.
Windcave HIT 자격 증명이 구성되지 않음
- HIT username 또는 HIT key가 비어 있습니다.
- 결제 게이트웨이 설정에 두 값을 모두 입력하고 저장하세요. Environment가 해당 자격 증명과 일치하는지 확인하세요.
단말기에서 이전 거래를 아직 처리하고 있습니다
- 해당 Station에서 이전 거래가 아직 진행 중입니다.
- 단말기에서 거래를 완료하거나 취소한 다음 다시 시도하세요.
Windcave에 이 거래 기록이 없습니다
- 최초 30초 유예 기간이 지난 후에도 Windcave에 거래 기록이 없습니다.
- 결제를 다시 시작하세요.
Windcave에서 결제를 승인했지만 적용할 수 없습니다
- 승인 결과가 이 주문을 완료하는 데 필요한 확인 절차를 통과하지 못했습니다.
- 다시 청구하기 전에 Windcave 포털과 주문 메모를 확인하세요.
이 결제는 다른 환경에서 시작되었습니다
- 결제가 진행되는 동안 Environment가 변경되었습니다.
- 결제를 시작한 환경으로 다시 전환하거나 Windcave 포털을 확인하세요.
도움 받기
- 결제 게이트웨이 설정 화면에서 지원 번들을 다운로드하고 주문 번호와 함께 보내세요.
- 문제를 신고하려면 GitHub 저장소를 방문하세요.
- 계정, 자격 증명 및 하드웨어 관련 문의는 Windcave 지원팀에 연락하세요.