Mercado Pago Terminal 결제 게이트웨이
Mercado Pago Terminal 결제 게이트웨이를 사용하면 WCPOS에서 Mercado Pago Point Smart 단말기로 대면 결제를 받을 수 있습니다. WooCommerce에서 결제를 시작하고 단말기에서 완료하면 Mercado Pago의 결제 확인 결과가 주문에 반영됩니다.
Mercado Pago Terminal for WooCommerce는 새 확장 프로그램이며 0.1.0은 첫 번째 릴리스입니다. 베타 버전으로 취급하세요. 실제 결제를 받기 전에 Mercado Pago 샌드박스 가상 단말기를 사용해 Test 모드에서 테스트 결제를 진행하세요.
기능
Point Smart 하드웨어
Mercado Pago Point Smart 1 및 2 단말기로 대면 결제를 받으세요
실시간 단말기 목록
계정의 단말기 목록을 실시간으로 가져오며, 설정에서 한 번 클릭으로 PDV로 전환할 수 있습니다
안정적인 결제 완료
2초마다 상태를 확인하고 Mercado Pago 웹훅과 5분 백그라운드 확인을 통해 브라우저를 닫은 경우에도 결제를 확인합니다
WooCommerce에서 환불
WooCommerce 주문 화면에서 전액 또는 부분 환불을 요청하세요
내장 진단 기능
설정에서 연결 및 웹훅 상태를 확인하고 문제 해결을 위한 지원 자료 묶음을 다운로드하세요
작동 방식
이 결제 게이트웨이는 Mercado Pago의 클라우드 Orders API for Point를 사용합니다. 결제를 시작하면 WooCommerce 주문 총액 전체에 대한 Mercado Pago 주문을 만들고 선택한 단말기로 전송합니다. Mercado Pago 주문은 5분 후 만료됩니다.
결제 페이지는 2초마다 Mercado Pago에 상태를 확인합니다. 웹훅과 5분 백그라운드 확인으로도 브라우저를 닫은 경우 결제된 주문을 완료할 수 있습니다. 웹훅은 선택 사항이지만 권장합니다. Webhook secret이 없어도 알림은 처리되지만 서명은 검증되지 않습니다.
단말기는 PDV(통합) 모드여야 합니다. 단말기는 STANDALONE 모드로 제공되므로 결제를 받기 전에 결제 게이트웨이 설정에서 PDV로 전환하고 단말기를 다시 시작하세요.
설정
Mercado Pago Terminal for WooCommerce 설치
GitHub 릴리스 페이지에서 GitHub 소스 코드 zip이 아닌 플러그인 zip 파일을 다운로드하세요. WooCommerce가 설치되어 활성화된 상태에서 플러그인 > 새로 추가 > 플러그인 업로드를 통해 업로드하고 활성화하세요.
Mercado Pago 인증 정보 추가
WP Admin > WooCommerce > 설정 > 결제로 이동한 다음 Mercado Pago Terminal을 여세요- Mode를 선택하세요.
Test는 샌드박스 가상 단말기를 사용하고Live는 실제 단말기를 사용합니다 - Mercado Pago의 Your integrations → 애플리케이션 → Credentials에서 Access token(
APP_USR-…)을 복사해 붙여 넣으세요
Live 모드에서 TEST- 토큰을 사용하면 결제가 샌드박스로 전송됩니다. 설정 화면에 이 조합에 대한 경고가 표시됩니다. 실제 결제를 받기 전에 운영 토큰을 붙여 넣으세요.
웹훅 등록
- Mercado Pago에서 Your integrations → 애플리케이션 → Webhooks로 이동하세요
- 결제 게이트웨이 설정 화면에 표시된 웹훅 URL을 추가하세요
- Order (Mercado Pago) 이벤트를 선택하고 저장하세요
- Mercado Pago의 secret signature를 복사해 WooCommerce의 Webhook secret에 붙여 넣으세요
웹훅은 선택 사항입니다. 웹훅이 없어도 상태 확인을 통해 결제가 완료되지만, 비밀 키를 설정하면 플러그인이 웹훅 서명을 검증할 수 있습니다.
단말기 설정
- 설정을 저장하고 화면을 새로고침하세요. Default terminal 드롭다운과 Terminals 표에 계정의 단말기가 표시됩니다
- STANDALONE 모드로 표시된 단말기는 Switch to PDV를 클릭한 다음 단말기를 다시 시작하세요
- Default terminal을 선택하세요
- (선택 사항) 캐셔가 선택할 수 있는 기기를 Enabled terminals로 제한하세요. 비워 두면 모든 단말기를 사용할 수 있습니다. 저장된 기본 단말기는 여기서 선택하지 않아도 계속 사용할 수 있습니다
- (선택 사항) Lock terminal selection을 활성화하면 항상 기본 단말기를 사용해 캐셔가 변경하지 못하게 합니다. 기본 단말기를 지정해야 합니다
- 설정을 저장하세요
WCPOS에서 활성화
WP Admin > POS > 설정 > 결제로 이동하세요- Mercado Pago Terminal 결제 게이트웨이를 찾아 POS에서 활성화하세요
- 설정을 저장하세요
WooCommerce 설정 화면의 Enable/Disable 체크박스는 온라인 매장 결제만 제어합니다. WCPOS에서는 해당 체크박스의 선택 여부와 관계없이 이 결제 게이트웨이를 설정한 후 사용할 수 있습니다.
설정 참고
| 설정 | 기능 |
|---|---|
| Enable/Disable | 온라인 매장 결제에 결제 게이트웨이를 활성화합니다. POS 활성화는 POS > 설정 > 결제에서 제어합니다 |
| Title | 결제 시 표시되는 이름입니다. 기본값은 Mercado Pago Terminal입니다 |
| Description | 결제 설명입니다. 기본값은 Pay in person on a Mercado Pago Point terminal.입니다 |
| Mode | Test(기본값)는 샌드박스 가상 단말기를 사용하고 Live는 운영 인증 정보로 실제 단말기를 사용합니다 |
| Access token | Mercado Pago의 Your integrations → 애플리케이션 → Credentials에서 확인할 토큰입니다. 저장된 토큰은 다시 표시되지 않습니다. 그대로 유지하려면 비워 두세요 |
| Webhook secret | 알림을 검증하는 데 사용하는 Mercado Pago 웹훅 설정의 비밀 서명입니다 |
| Default terminal | 결제 시 기본으로 사용하는 단말기로, 계정에서 실시간으로 가져옵니다. 목록을 가져오지 못하면 텍스트 입력란이 표시됩니다 |
| Enabled terminals | 캐셔가 선택할 수 있는 단말기를 제한합니다. 비워 두면 모든 단말기를 사용할 수 있으며 기본 단말기는 항상 사용할 수 있습니다. 목록을 불러오지 못하면 표시되지 않습니다 |
| Lock terminal selection | 항상 기본 단말기를 사용해 캐셔가 변경하지 못하게 합니다. 기본 단말기를 지정해야 합니다 |
| Checkout debug logs | 결제 패널에 Show logs, Copy, Clear를 표시합니다. 기본적으로 꺼져 있습니다. 지원을 위해 로그를 수집할 때 활성화하세요 |
| Log level | Off, Errors only 또는 Debug입니다. 이 릴리스의 기본값은 Debug이며 비밀 정보가 제거된 요청과 응답을 기록합니다 |
필드 아래의 Mercado Pago Terminal diagnostics 표에는 API 확인 결과(단말기 및 PDV 수 포함), 마지막 웹훅 검증 시각, 활성 환경, 인증 정보 설정 여부, 기본 단말기, 웹훅 URL 및 결제 로그 링크가 표시됩니다.
사용 방법
결제 처리
- 상품 추가: POS에서 장바구니에 상품을 추가하세요
- 결제 게이트웨이 선택: 결제 방법으로 Mercado Pago Terminal을 선택하세요
- 단말기 선택: 단말기를 선택하거나 선택 잠금 상태라면 기본 단말기를 사용하세요
- 결제 시작: Start Terminal Payment를 클릭해 주문 총액을 단말기로 전송하세요
- 고객 결제: 고객이 단말기에서 결제를 완료하는 동안 상태 메시지
Sending to terminal…→Waiting for terminal…→Customer is paying on the terminal…을 확인하세요 - 자동 완료: Mercado Pago에서 결제를 확인하면 주문이 완료되고 POS에서 영수증 화면으로 이동합니다
결제 제어
- Start Terminal Payment: 선택한 단말기에 새 결제 요청을 전송합니다
- Cancel Terminal Payment: 단말기가 결제를 받기 전에만 취소할 수 있습니다. 그 이후에는 단말기에서 취소하거나 5분 만료까지 기다리세요
- 페이지 새로고침: 진행 중인 결제를 다시 불러옵니다
영수증
단말기에서는 영수증을 출력하지 않습니다. 결제가 완료된 후 POS 영수증을 사용하세요.
환불
WooCommerce 주문 환불 화면을 열고 Refund via Mercado Pago Terminal을 선택해 전액 또는 부분 환불을 요청하세요. Mercado Pago에서는 결제 후 90일까지 환불할 수 있습니다.
일부 카드 매입사는 단말기에서만 환불할 수 있습니다. 이 경우 단말기에서 환불하고 WooCommerce에 수동 환불을 기록하세요.
로그 및 지원 자료 묶음
WooCommerce > Status > 로그에서 mercadopago-terminal 소스의 로그를 확인하세요. 이 릴리스의 기본 로그 수준은 Debug입니다. 요청, 응답, 웹훅 및 결제 상태 변경을 기록하며 비밀 정보와 카드 번호는 가립니다.
결제 게이트웨이 설정 화면에서 Download support bundle을 클릭해 .txt 파일을 다운로드하고 지원 요청에 첨부하세요. 환경 정보, 인증 정보가 가려진 설정, 단말기 목록 및 작동 모드, 최근 10개 주문의 결제 시도, 마지막 500개 로그 줄이 포함됩니다. 이 자료로 결제를 실행할 수는 없습니다.
Checkout debug logs를 활성화하면 결제 패널에 Show logs, Copy, Clear가 추가됩니다. 이 설정과 관계없이 결제 활동은 WooCommerce 로그에 기록됩니다.
요구 사항
범위 및 제한 사항
- 단말기에는 주문 총액 전체가 청구됩니다. 단말기에서 주문 금액의 일부만 결제하는 기능은 지원하지 않습니다
- 팁은 지원하지 않습니다
- 금액은 소수점 이하 두 자리로 전송됩니다. 칠레 또는 콜롬비아 페소를 사용하는 매장은 먼저 테스트 결제로 확인하세요
- 온라인 매장의 Blocks checkout은 지원하지 않습니다
- 이 플러그인은 아직 HPOS 호환성을 선언하지 않았습니다
문제 해결
일반적인 문제
Mercado Pago에서 액세스 토큰을 거부함(HTTP 401)
- 액세스 토큰이 유효하지 않거나 오래되었습니다
- Your integrations → Credentials에서 새 토큰을 복사해 Access token에 저장하세요
단말기 목록이 표시되지 않음
- 계정에 연결된 Point 단말기가 없다면 Mercado Pago 계정으로 단말기에 로그인하고 PDV로 전환한 다음 다시 시작하세요
- Default terminal이 드롭다운 대신 텍스트 입력란으로 표시되면 목록을 가져오지 못한 것입니다. 토큰과 진단 정보를 확인한 다음 설정 화면을 새로고침하세요
단말기가 STANDALONE 모드임
- 통합 결제에는 PDV 모드가 필요합니다
- 설정 화면의 Terminals 표에서 Switch to PDV를 클릭한 다음 단말기를 다시 시작하세요
결제가 이미 단말기에 표시됨
- 단말기가 결제를 수신했으므로 더 이상 WooCommerce에서 취소할 수 없습니다
- 단말기에서 취소하거나 5분 후 만료될 때까지 기다리세요. 결제 페이지는 계속 상태를 확인합니다
웹훅을 한 번도 검증하지 않음
- 진단 정보에 Last verified webhook: never가 표시되면 Mercado Pago의 웹훅 URL과 비밀 키를 확인하세요
- Webhook secret이 비어 있다면 Mercado Pago의 secret signature를 붙여 넣으세요. 상태 확인을 통해 결제는 계속 완료되지만 비밀 키가 없는 알림은 서명이 검증되지 않습니다
카드 매입사가 환불을 거부함
- 일부 매입사는 단말기에서만 환불할 수 있으며 Mercado Pago는 환불 기간을 90일로 제한합니다
- 단말기에서 환불한 다음 WooCommerce에 수동 환불을 기록하세요
단말기에서 결제가 만료됨
- Mercado Pago 주문은 5분 후 만료됩니다
- 결제를 다시 시작하세요
도움 받기
- 결제 게이트웨이 설정 화면의 지원 자료 묶음을 지원 요청에 첨부하세요
- 문제를 신고하려면 GitHub 저장소를 방문하세요
- 계정 및 하드웨어 관련 문의는 Mercado Pago 지원팀에 문의하세요