Mollie Terminal 결제 게이트웨이
Mollie Terminal 게이트웨이를 사용하면 WCPOS에서 Mollie Terminal 하드웨어로 대면 결제를 직접 수금할 수 있습니다. 결제는 WooCommerce에서 시작되어 터미널에서 완료되며, Mollie의 확인 결과가 주문에 기록됩니다.
기능
하드웨어 연동
Mollie 계정에 등록된 Mollie 터미널로 결제를 전송하고 카드 대면 결제를 수금합니다
수동 페어링 불필요
터미널 목록은 Mollie 계정에서 실시간으로 불러옵니다. 드롭다운에서 선택하기만 하면 되며 붙여 넣을 기기 ID가 없습니다
확실한 완료 처리
Mollie 폴링으로 결제를 확인하며, 터미널이 확인되는 즉시 POS가 자동으로 영수증 화면으로 이동합니다
안전한 거래
PCI 규격을 준수하며, Mollie 하드웨어에서 카드 대면 결제를 처리합니다
환불 지원
WooCommerce 주문 화면에서 환불하며, Mollie와 대조하여 환불이 중복되지 않도록 합니다
작동 방식
Mollie Terminal은 Mollie의 서버 측 pointofsale 결제를 사용합니다. 결제를 시작하면 WooCommerce가 해당 주문에 대한 Mollie 결제를 생성하고, Mollie가 이를 선택된 터미널로 전송합니다. 고객이 기기에서 결제하며, 결제 및 환불 상태의 기준은 Mollie입니다. 로컬 WooCommerce 주문 메타는 캐시일 뿐입니다.
결제가 확인되는 방식. 결제가 진행되는 동안 POS는 Mollie를 폴링하며(기본값 2초 간격), 터미널이 확인되면 곧바로 감사 페이지로 이동합니다. 이를 앞당기기 위해 Mollie 웹훅도 함께 사용되며, 웹훅 URL은 모든 결제마다 자동으로 설정되므로 Mollie 대시보드에서 구성할 것이 없습니다.
터미널은 플러그인과 동일한 Mollie 계정에 등록되어 있고 활성 상태여야 합니다.
설정
Mollie Terminal for WooCommerce 설치
WP Admin > POS > 설정 > 확장에서 설치하거나, GitHub 릴리스 페이지에서 최신 플러그인 zip 파일(GitHub 소스 코드 zip 또는 tarball이 아닌)을 다운로드한 후 플러그인 > 새로 추가 > 플러그인 업로드를 통해 업로드하세요.
Mollie 자격 증명 구성
WP Admin > WooCommerce > 설정 > 결제로 이동하여 Mollie Terminal을 여세요- 모드를
Live로 설정하세요. 터미널 결제에는 실계정이 필요합니다(범위 및 제한 사항 참조) - API 키 소스를 설정하여 공식 Mollie Payments for WooCommerce 플러그인의 키를 재사용하거나, 이 화면에서 입력한 키를 사용하세요
- 여기에 키를 입력하는 경우 Mollie 라이브 API 키를 Mollie API Key에 붙여 넣으세요
- 저장하세요
Mollie 터미널은 라이브 계정에만 존재하므로 테스트 API 키로는 터미널을 제어할 수 없습니다. 테스트 모드를 선택하면 설정 화면에 경고가 표시됩니다. 결제를 수금하려면 라이브 API 키와 함께 Live로 전환하세요. 범위 및 제한 사항을 참조하세요.
pointofsale 결제에는 Mollie 프로필 ID가 필요하지 않으며, 터미널은 계정 전체에서 조회되므로 그 밖에 붙여 넣을 값이 없습니다.
터미널 선택
- 드롭다운에서 기본 터미널을 선택하세요. 목록은 선택한 Mollie 환경에서 가져오며, 비활성 터미널은 Mollie가 다시 활성화할 수 없기 때문에 표시되지 않습니다.
- (선택 사항) 사용 가능한 터미널을 실제로 사용 중인 기기로 제한하세요. 저장된 기본 터미널은 여기서 선택하지 않아도 계속 사용할 수 있습니다. 이 설정을 비워 두면 모든 활성 터미널이 허용됩니다. 터미널을 사용 중지하려면 기본 터미널도 변경하거나 비워야 합니다.
- (선택 사항) 터미널 선택 잠금을 활성화하면 계산원이 결제 시 터미널을 변경할 수 없습니다. 항상 기본 터미널이 사용되며, 이는 서버에서도 강제됩니다.
- 저장하세요
WCPOS에서 활성화
WP Admin > POS > 설정 > 결제로 이동하세요- Mollie Terminal 게이트웨이를 찾아 POS에서 활성화하세요
- 설정을 저장하세요
WooCommerce 설정 화면의 활성화/비활성화 체크박스는 온라인 스토어 결제에만 적용됩니다. WCPOS는 이 게이트웨이가 구성되어 있으면 해당 체크박스의 상태와 관계없이 사용합니다.
설정 참조
| 설정 | 기능 |
|---|---|
| 활성화/비활성화 | 온라인 스토어 결제에서 게이트웨이를 활성화합니다(POS에는 필요하지 않음) |
| 제목 / 설명 | 결제 시 고객에게 표시되는 라벨과 문구입니다 |
| 모드 | Test 또는 Live입니다. 터미널 결제에는 Live가 필요하며, 테스트 API 키로는 터미널을 제어할 수 없습니다 |
| API 키 소스 | 아래에 입력한 키를 사용하거나, 공식 Mollie Payments for WooCommerce 플러그인에서 해당 테스트/라이브 키를 재사용합니다. 공유 키를 사용할 수 없으면 플러그인은 아래 키로 대체합니다 |
| Mollie API Key | 선택한 모드에 해당하는 테스트 또는 라이브 API 키입니다. API 키 소스가 여기에 입력한 키로 설정된 경우에 사용되며, 공유 키가 없을 때의 대체 값으로도 사용됩니다 |
| 기본 터미널 | 결제 시 기본으로 사용되는 터미널이며, 선택한 Mollie 환경의 활성 터미널 드롭다운에서 선택합니다 |
| 사용 가능한 터미널 | 결제 화면의 목록을 선택한 터미널로 제한합니다. 비워 두면 모든 활성 터미널이 사용됩니다. 저장된 기본 터미널은 항상 사용할 수 있으므로, 터미널을 사용 중지할 때는 기본 터미널도 함께 변경하거나 비우세요 |
| 터미널 선택 잠금 | 결제 시 기본 터미널을 강제하여 계산원이 변경할 수 없게 합니다(기본 터미널이 설정되어 있어야 함) |
| 결제 디버그 로그 | 결제 패널에 로그 표시, 복사, 초기화 도구를 표시합니다. 지원팀에 제출할 로그를 수집하는 경우가 아니라면 꺼 두세요. 결제 활동은 언제나 WooCommerce > 상태 > 로그에 기록됩니다 |
웹훅 URL은 모든 결제마다 자동으로 적용되므로 입력할 웹훅 필드가 없으며 Mollie 대시보드에서 구성할 것도 없습니다.
사용 방법
결제 처리
- 상품 추가: POS에서 장바구니에 상품을 추가합니다
- 게이트웨이 선택: 결제 수단으로 “Mollie Terminal”을 선택합니다
- 터미널 선택: 드롭다운에서 터미널을 선택합니다(구성된 기본 터미널이 선택되어 있으며, 터미널 선택이 잠겨 있으면 표시되지 않습니다)
- 결제 시작: 터미널 결제 시작을 클릭하면 Mollie가 해당 기기로 결제를 전송합니다
- 고객 결제: 고객이 터미널에서 카드를 탭하거나 삽입하거나 스와이프합니다. 상태는 실시간으로 갱신됩니다 —
Sending to terminal…→Waiting for terminal… - 자동 완료: 터미널이 확인하면 주문이 결제 완료로 표시되고 POS가 자동으로 영수증 화면으로 이동합니다
결제 제어
- 터미널 결제 시작: 선택한 터미널로 새 결제 요청을 전송합니다
- 결제 취소: 아직 열려 있는 결제를 취소합니다. 결제가 이미 터미널에 도달한 뒤에는 Mollie가 취소할 수 없다고 보고하며, 계산원이 기기에서 직접 취소해야 합니다
주문 관리
- 검증된 완료 처리: 모든 웹훅, 폴링, 취소, 재시도는 주문을 변경하기 전에 Mollie의 정본 상태를 가져오므로, 주문은 확인된 Mollie 상태에 근거해서만 결제 완료로 표시됩니다
- 결제 추적: 결제 시도는 주문에 추가 전용 이력으로 기록됩니다
- 영수증 생성: 결제가 완료되면 표준 POS 영수증이 생성됩니다
환불
환불이 지원됩니다. 일반적인 WooCommerce 주문 화면에서 주문을 환불하면 환불 요청이 Mollie로 전송됩니다. 상태의 기준이 Mollie이므로, 환불을 재시도할 때는 다른 환불을 생성하기 전에 Mollie의 환불 ID 및 메타데이터와 대조합니다. 따라서 환불이 실수로 두 번 처리되는 일은 없습니다.
미완료 결제 정리
결제가 중단되면 Mollie pointofsale 결제가 Mollie 쪽에서 “열림” 상태로 남을 수 있습니다. 플러그인은 다음과 같은 경우 이렇게 열려 있는 결제를 자동으로 취소합니다:
- 자동 폴링이 시간 초과된 경우(기본값 5분) — 결제를 그대로 두지 않고 취소를 전송합니다
- 주문이 다른 결제 수단으로 완료되었거나(예: 고객이 현금으로 결제한 경우) WooCommerce에서 주문이 취소된 경우
- 결제 도중 결제 페이지가 닫힌 경우 — 탭이 닫힐 때 최선 노력으로 취소를 전송합니다
- WP-Cron 스윕이 10분마다 실행되어 기준 시간(기본값 10분)을 넘겨 열려 있는 결제를 취소하거나 정리하는 경우. 다른 정리 경로가 실행되기 전에 브라우저가 닫히거나 네트워크가 끊긴 경우도 포함됩니다
결제가 이미 터미널에 도달했다면 Mollie는 취소할 수 없다고 보고하며, 계산원이 기기에서 직접 취소해야 합니다. 이 경우 위의 정리 작업은 아무런 영향 없이 안전하게 넘어갑니다.
요구 사항
범위 및 제한 사항
Mollie 터미널은 라이브 계정에만 존재합니다. Mollie 테스트 API 키로는 실물(또는 iOS/Android) 터미널을 제어할 수 없으므로, 테스트 모드에서는 터미널 결제를 처음부터 끝까지 실행해 볼 수 없습니다. 이는 플러그인의 제약이 아니라 Mollie 플랫폼의 제약이며, 테스트 모드를 선택하면 설정 화면에 경고가 표시됩니다. 터미널 결제를 수금하려면 라이브 API 키와 함께 Live 모드를 사용하세요.
POS 터미널 결제는 Mollie Terminal의 더 넓은 통화 지원이 확인될 때까지 EUR로 제한됩니다.
문제 해결
일반적인 문제
드롭다운에 터미널이 표시되지 않음
- 모드가
Live로 설정되어 있고 실제 적용되는 API 키가 라이브 키인지 확인하세요. 터미널은 테스트 계정에 존재하지 않습니다 - 터미널이 Mollie 계정에 등록되어 있고 활성 상태인지 확인하세요. 비활성 터미널은 Mollie가 다시 활성화할 수 없기 때문에 표시되지 않습니다
- 사이트가 Mollie에 연결할 수 있는지 확인하세요. 목록은 API를 통해 실시간으로 조회됩니다
결제가 시작되지 않음
- 터미널이 선택되어 있는지(또는 선택이 잠겨 있는 경우 기본 터미널이 설정되어 있는지) 확인하세요
- 터미널의 전원이 켜져 있고 온라인 상태이며 동일한 Mollie 계정에서 활성 상태인지 확인하세요
- 주문 통화가 EUR인지 확인하세요
터미널이 시간 초과되었거나 결제가 열린 상태로 남음
- 플러그인은 시간 초과 시(기본값 5분) 열려 있는 결제를 자동으로 취소하려고 시도합니다
- 결제가 이미 터미널에 도달하여 자동으로 취소할 수 없다면 기기에서 직접 취소하세요
- 그 후에 새 결제를 시작하거나 다른 방법으로 결제를 수금할 수 있습니다
터미널에서는 결제가 완료되었지만 주문 업데이트가 느림
- POS는 2초마다 Mollie를 폴링하며 결제가 확인되면 화면을 이동합니다. 보통은 웹훅이 먼저 확인합니다
- 상태의 기준이 Mollie이므로 주문은 Mollie의 정본 상태와 대조되어 정리되며, 유실되지 않습니다
- Mollie API 메시지가 있는지
WooCommerce > 상태 > 로그를 확인하세요
도움 받기
기술 지원 안내:
- 문제를 보고하려면 GitHub 리포지토리를 방문하세요
- API 관련 질문은 Mollie Terminal 설정 가이드와 Mollie Create Payment API를 확인하세요
- 계정 및 하드웨어 관련 문제는 Mollie 지원팀에 문의하세요
스크린샷
다음 항목을 보여주는 스크린샷이 향후 업데이트에 추가될 예정입니다:
- Mollie Terminal 설정 화면 — API 키, 기본 터미널, 사용 가능한 터미널
- WCPOS 설정에서 게이트웨이 활성화
- POS 결제 화면에서의 결제 처리 워크플로