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

Mercado Pago Terminal 결제 게이트웨이

Mercado Pago Terminal은 계산대에서 Mercado Pago Point 단말기로 판매 정보를 전송합니다. 고객이 단말기에서 결제하면 Mercado Pago의 확인 후 계산대에 결제가 기록됩니다.

이 페이지는 계산대 사용법부터 안내합니다. 매장 관리자: Mercado Pago Terminal 설정하기에서 액세스 토큰, 웹훅, 단말기 설정 및 작동 확인 방법을 알아보세요.

Pro 기능

Mercado Pago Terminal을 사용하려면 WCPOS Pro 2.0 이상과 확장 기능 1.0 이상이 필요합니다.

매장 관리자: 먼저 테스트 결제를 진행하세요

버전 1.0은 아직 실제 Point 단말기나 Mercado Pago 계정에서 실행되지 않았습니다. 고객의 카드를 받기 전에 본인 카드로 소액을 결제한 다음 환불하세요.

테스트한 항목과 아직 테스트하지 않은 항목

버전 1.0은 Mercado Pago 문서를 바탕으로 만든 대체 환경에서 테스트했습니다. 버전 0.1은 실운영 계정과 실제 Point Smart에서 단말기 목록 조회, PDV 모드 전환, 결제 생성 및 취소를 테스트했습니다. 두 버전 모두 실제 카드 결제 완료, 결제 거부, 단말기에서 취소, Mercado Pago 알림, 환불 및 Mercado Pago 샌드박스는 아직 테스트하지 않았습니다.

카드 결제 받기​

먼저 계산대를 여세요

계산대 열기 및 닫기가 켜져 있으면 계산대가 닫힌 동안 결제를 기록할 수 없으며, 이미 받은 카드 결제는 환불해야 합니다. 설정 방법은 계산대를 참고하세요.

  1. 장바구니에서 결제를 누른 다음 결제 탭에서 Mercado Pago Terminal 타일을 누르세요. 매장에서 다른 이름으로 지정했을 수도 있습니다.
  2. 키패드 위를 확인하세요. 단말기 선택이 표시되면 계산대에 있는 단말기를 누르세요. 단말기: 와 이름이 표시되면 현재 이 계산대에서 사용하는 단말기입니다. 다른 단말기를 선택하려면 변경을 누르세요. 선택한 단말기는 저장됩니다.
  3. 잔액의 일부만 카드로 결제하려면 금액을 입력하세요. 나머지 금액은 미결제 상태로 남아 다음 결제를 기다립니다. 전체 잔액을 누르면 전체 금액이 결제 금액으로 입력됩니다.
  4. Mercado Pago Terminal로 … 전송을 누르세요. 계산대에 단말기에서 고객 응답 대기 중이 표시됩니다.
  5. 고객이 단말기에서 결제합니다. 금액이 결제되고 미결제 잔액이 없으면 영수증이 열립니다. 잔액이 남으면 다른 타일로 결제를 받으세요.
계산대에 표시되는 단계의 의미

결제가 진행되는 동안 계산대에 전송됨, 단말기에서 처리 중, 결제 완료가 차례로 표시됩니다. 결제 완료는 금액이 청구되었다는 뜻입니다. Mercado Pago는 한 단계로 금액을 청구하므로 승인됨은 표시되지 않습니다.

단말기에서는 전표를 인쇄하지 않습니다. 평소처럼 POS 영수증을 인쇄하거나 이메일로 보내세요. 결제 시 영수증을 참고하세요. 단말기에서는 팁을 추가할 수 없습니다.

결제 취소하기​

계산대에서 단말기에서 취소를 누르세요. 결제가 단말기 화면에 표시되기 전까지만 취소할 수 있습니다. 고객이 결제 내용을 볼 수 있게 되면 계산대에서 취소할 수 없습니다:

  1. 고객이 이미 금액을 볼 수 있다면 Mercado Pago 단말기에서 직접 취소하거나 고객에게 결제하지 말아 달라고 요청하세요.
  2. 계산대의 응답을 기다리세요. 확인을 진행하는 동안 취소 중 — 단말기 확인 대기 중 상태가 유지될 수 있습니다. 단말기에서 취소될 때까지 고객이 결제할 수 있으므로 아직 다른 방법으로 결제받지 마세요.
  3. 단말기에서 취소되면 계산대에 결제가 취소되었습니다가 표시됩니다. 아무도 취소하지 않으면 Mercado Pago가 5분 후 결제를 만료시키고 계산대에 결제 실패: 단말기 응답 시간 초과가 표시됩니다.

대신 이 결제 해제가 표시되면 관리자가 Mercado Pago를 확인할 때까지 누르지 마세요. 자세한 내용은 기타 메시지의 계산대에 '이 결제 해제'가 표시됨을 참고하세요.

문제가 발생한 경우​

고객이 이미 결제했을 수 있는 경우​

결제를 다시 받지 마세요

이 경우 카드에서 이미 금액이 청구되었을 수 있습니다. 관리자는 먼저 Mercado Pago 계정을 확인해야 합니다. 결제 내역에는 주문 # 과 주문 번호가 표시됩니다.

카드에서 금액이 청구되었지만 주문이 완료되지 않았습니다. Mercado Pago에서 금액을 받았지만 계산대가 주문을 완료하지 못했습니다. 다시 청구하지 마세요. 앱을 새로고침하면 계산대가 판매 완료를 다시 시도합니다. 주문이 계속 열려 있으면 관리자가 완료해야 합니다. 카드 결제는 되었지만 주문이 완료되지 않음을 참고하세요.

결제 실패: 단말기에서 다른 금액을 확인했습니다. 단말기에서 계산대가 전송한 금액과 다른 금액을 청구했으므로 계산대에 결제가 기록되지 않았지만, 카드에서 금액이 청구되었을 수 있습니다. 관리자에게 Mercado Pago에서 결제를 찾아 주문과 비교해 달라고 요청하세요.

결제 도중 계산대가 닫혔거나 연결이 끊겼습니다. 다른 계산대에서 결제를 다시 전송하지 마세요. 관리자가 웹훅을 설정했다면 계산대가 닫혀 있어도 매장에 결제가 기록됩니다. 주문을 열어 미결제로 표시되는지 확인하고, 미결제라면 관리자가 Mercado Pago를 확인한 후 다시 결제받으세요.

기타 메시지​

결제 실패: 카드가 거부됨

단말기로 다시 전송하려면 다시 시도를 누르고, 다른 타일로 결제하려면 다른 결제 방법 선택을 누르세요.

결제 실패: 뒤에 코드가 표시됨

Mercado Pago가 결제를 거부하고 계산대에서 번역할 수 없는 사유를 반환하여 Mercado Pago 자체 코드를 표시합니다. 다시 시도 또는 다른 결제 방법 선택을 누르세요. 같은 코드가 계속 표시되면 주문 번호와 함께 지원 자료 묶음을 보내세요.

단말기에서 이전 주문을 아직 처리 중입니다

단말기에서 다른 결제를 처리 중입니다. 단말기에서 결제를 완료하거나 취소한 다음 다시 시도를 누르세요.

결제 실패: 단말기 응답 시간 초과

5분 안에 결제되지 않았습니다. 단말기를 확인한 다음 다시 시도를 누르세요.

계산대에 '이 결제 해제'가 표시됨

Mercado Pago가 취소 요청을 수락했지만 아직 확인하지 않았습니다. 해제는 취소를 뜻하지 않습니다. 관리자가 Mercado Pago 계정을 확인하여 주문에 승인된 결제가 없는 것을 확인한 경우에만 누르세요. 이후 다른 방법으로 주문을 결제할 수 있습니다.

Mercado Pago Terminal 타일이 회색으로 표시되거나 보이지 않음

타일 아래에 계산대에서 사용할 수 없는 이유가 표시됩니다. 모든 사유는 타일을 사용할 수 없는 경우를 참고하세요.

  • 주문 #…에서 사용 중 — 단말기에서 다른 주문의 결제를 처리 중입니다. 해당 결제를 완료하거나 취소하거나 변경을 눌러 다른 단말기를 선택하세요.
  • 연결 필요 — 계산대가 오프라인입니다. 단말기 결제는 매장을 거치므로 다른 결제 방법을 사용하거나 연결될 때까지 기다리세요.
  • Mercado Pago Terminal용 단말기가 설정되지 않음 — PDV 모드인 단말기가 없습니다. 관리자에게 PDV 모드로 전환해 달라고 요청하세요.
  • 타일이 표시되지 않음 — 결제 게이트웨이에 액세스 토큰이 없거나 WCPOS에서 켜져 있지 않습니다. 관리자에게 설정을 확인해 달라고 요청하세요.

Mercado Pago 결제 환불하기​

환불하면 전액 또는 일부 금액이 Mercado Pago를 통해 고객의 카드로 반환됩니다.

  1. POS에서 주문의 환불 화면을 여세요. 환불을 참고하세요.
  2. Mercado Pago Terminal로 환불을 선택하고 환불 처리를 누르세요.
  3. 매장에서 Mercado Pago에 환불을 요청하고 결과를 주문 메모에 추가합니다.

WooCommerce의 Mercado Pago Terminal을 통해 … 환불 버튼을 사용하면 WP Admin에서도 같은 방식으로 환불할 수 있습니다. 버전 0.1로 받은 판매도 같은 방식으로 환불됩니다.

환불이 대기 중인 상태로 유지됨

Mercado Pago가 응답했을 때 환불 처리가 끝나지 않았으며 매장에서 상태를 자동으로 업데이트하지 않을 수 있습니다. 다시 환불하기 전에 Mercado Pago 계정에서 환불을 확인하세요. 환불이 완료되었다면 고객에게 금액이 반환된 것입니다.

Mercado Pago에서 환불을 거부함

일부 카드 매입사는 단말기에서만 환불을 허용합니다. Point 단말기 또는 Mercado Pago 계정에서 환불한 다음 WooCommerce에서 수동으로 … 환불로 기록하세요.

단말기 또는 Mercado Pago에서 환불함

해당 위치에서 처리한 환불은 매장에 전달되지 않으므로 주문에는 결제 금액 전체가 표시됩니다. 금액이 두 번 반환되지 않도록 WooCommerce에서 수동으로 … 환불로 기록하세요.

Mercado Pago Terminal 설정하기​

관리자가 WP Admin에서 매장별로 한 번 설정한 다음 각 계산대에서 단말기를 선택합니다. 매장은 인터넷을 통해 Mercado Pago를 거쳐 각 단말기에 연결하므로 페어링할 필요가 없고 모든 계산대에서 보유한 단말기를 사용할 수 있습니다.

필요한 사항​

Mercado Pago 계정: Point 판매자 계정과 액세스 토큰이 있는 내 연동의 애플리케이션
단말기: 동일한 계정으로 로그인한 Mercado Pago Point 단말기(예: Point Smart)
통화: 매장의 통화는 Mercado Pago 계정의 통화와 같아야 합니다. 통화는 변환되지 않습니다.
WCPOS: WCPOS Pro 2.0 이상 및 확장 기능 1.0 이상
서버: WordPress 6.0 이상, WooCommerce, PHP 7.4 이상. 웹훅을 사용하려면 사이트가 인터넷에서 연결 가능해야 합니다.

칠레 페소처럼 센트 단위가 없는 통화를 사용하는 경우 WooCommerce > 설정 > General에서 소수 자릿수를 0으로 설정하세요. Mercado Pago는 해당 계정에서 소수점이 있는 금액을 거부합니다.

확장 기능 설치하기​

WP Admin > POS > 설정 > 확장을 열고 Mercado Pago Terminal for WooCommerce를 찾아 설치한 다음 활성화하세요. 1.0 이상이 필요하며 버전 0.1은 WCPOS 2.0 이전 버전용입니다. 확장 기능을 참고하세요.

GitHub 릴리스 페이지의 플러그인 > Add Plugin > 플러그인 업로드에서 플러그인 zip(소스 코드 zip이 아님)을 업로드할 수도 있습니다.

WCPOS Pro 2.0이 없으면 WP Admin에 *Mercado Pago Terminal requires WooCommerce POS Pro 2.0 or newer.*가 표시되고 결제 게이트웨이가 추가되지 않습니다.

액세스 토큰 입력하기​

판매자 계정으로 Mercado Pago Developers에 로그인하고 내 연동을 여세요. 애플리케이션이 없다면 새로 만든 다음 여세요. 운영용 인증 정보에서 액세스 토큰을 복사하세요. 토큰은 APP_USR-로 시작합니다. 이 토큰은 실제 결제용입니다. 테스트 인증 정보의 토큰은 Mercado Pago 샌드박스에만 연결되며, 이 확장 기능에서는 아직 테스트하지 않았습니다.

그런 다음 WP Admin > WooCommerce > 설정 > 결제로 이동하여 Mercado Pago Terminal을 여세요.

WP Admin의 Mercado Pago Terminal 설정: Enable은 선택 해제, Title은 Mercado Pago Terminal, Description은 기본값, Mode는 Test, Access token과 Webhook secret 입력란은 비어 있음
  1. 활성화 — 선택하지 않은 상태로 두세요. 이 옵션은 온라인 매장에서 결제 게이트웨이를 제공합니다. POS에는 별도 스위치가 있습니다.
  2. 제목 — 계산대에 표시되는 타일 이름입니다.
  3. 설명 — 매장의 결제 페이지에서 제목 아래에 표시됩니다.
  4. 모드 — 기본값인 테스트가 표시됩니다. 실운영으로 설정하세요. 아래 안내는 오래된 내용입니다. 실제 결제 여부는 모드가 아니라 액세스 토큰으로 결정됩니다.
  5. 액세스 토큰 — 운영용 토큰을 붙여넣으세요. 저장하면 입력란이 비어 있으므로 저장된 토큰을 유지하려면 비워 두세요.
  6. 웹훅 비밀 키 — 지금은 비워 두세요. 웹훅 추가 단계에서 입력합니다.

변경 사항 저장을 클릭하세요.

웹훅 추가하기​

웹훅을 사용하면 결제가 완료되는 즉시 Mercado Pago가 매장에 알립니다. 계산대와 매장이 Mercado Pago에 계속 상태를 요청하므로 웹훅 없이도 결제는 작동하지만, 계산대가 닫힌 뒤에도 결제된 주문이 완료되도록 웹훅을 설정하세요.

  1. 웹훅 비밀 키 아래 설명에 표시된 웹훅 URL을 복사하세요. URL은 wp-json/wcpos/v2/payments/webhook?provider=mercadopago로 끝납니다.
  2. Mercado Pago Developers에서 내 연동, 애플리케이션, 웹훅 순서로 여세요. URL을 추가하고 주문(Mercado Pago) 이벤트를 선택하세요.
  3. Mercado Pago에 표시된 비밀 서명을 복사하여 웹훅 비밀 키에 붙여넣고 변경 사항 저장을 클릭하세요.

매장은 이 비밀 키로 서명되지 않은 알림을 모두 거부하므로 비밀 키가 없으면 웹훅이 작동하지 않습니다.

단말기를 PDV 모드로 전환하기​

Point 단말기는 계산대 결제를 받을 수 없는 STANDALONE 모드로 출고됩니다. 결제 화면에는 PDV 모드인 단말기만 표시됩니다.

  1. 아직 로그인하지 않았다면 각 단말기에서 동일한 Mercado Pago 계정으로 로그인하세요.
  2. Mercado Pago Terminal 설정 페이지를 새로고침하세요. Mercado Pago 진단 정보 아래 표에 단말기별 ID, 단말기 이름 및 모드가 표시됩니다.
  3. STANDALONE 모드인 각 단말기에서 PDV로 전환을 클릭한 다음 단말기를 다시 시작하세요. Mercado Pago에서 다시 시작해야 합니다.

표에는 최대 50개의 단말기가 표시됩니다.

WCPOS에서 켜기​

WP Admin > POS > 설정 > 결제로 이동하여 결제 게이트웨이 표에서 Mercado Pago Terminal을 찾은 다음 활성화됨을 켜세요. 이 화면에서는 변경 사항이 자동 저장되므로 저장 버튼이 없습니다.

WP Admin의 POS 설정, Checkout 화면: 결제 게이트웨이 표의 세 행인 Cash on delivery, Mercado Pago Terminal, Mollie Terminal이 모두 꺼져 있음
  1. Mercado Pago Terminal — 결제 게이트웨이 표에서 확장 기능에 해당하는 행입니다.
  2. 활성화됨 — 결제 게이트웨이 ID 옆의 스위치입니다. 켜면 POS를 새로고침한 뒤 계산대에 Mercado Pago Terminal 타일이 표시됩니다.

WooCommerce 설정 페이지의 활성화는 꺼진 상태로 두세요. 여기에서 활성화됨을 켜면 해당 확인란의 선택 여부와 관계없이 POS에서 결제 게이트웨이를 사용합니다. 결제 설정을 참고하세요.

각 계산대에서 단말기 선택하기​

각 계산대에서 설정 > 카드 리더기를 여세요. Mercado Pago에서 지정한 이름의 단말기가 스마트 리더기 아래에 표시됩니다. 오프라인으로 표시된 단말기는 아직 전환하지 않은 것입니다. 단말기를 PDV 모드로 전환을 참고하세요. 해당 계산대에 있는 단말기에서 이 리더기 사용을 누르면 행에 선택됨이 표시됩니다. 캐셔는 결제 화면에서 변경을 누를 수 있습니다.

PDV 모드인 단말기가 하나뿐이면 선택할 필요가 없습니다. 모든 계산대에서 이미 선택됨 상태입니다. 스마트 리더기 선택을 참고하세요.

설정 확인하기​

  1. Mercado Pago Terminal 설정 페이지의 Mercado Pago 진단 정보 아래에 다음 메시지가 표시됩니다:

    인증 정보가 승인되었습니다. PDV로 전환한 후 단말기를 다시 시작하세요.

    Mercado Pago에서 액세스 토큰을 승인했다는 뜻입니다. *Mercado Pago access token is missing.*가 표시되면 저장된 토큰이 없는 것입니다. 다른 문구는 토큰에 대한 Mercado Pago의 응답입니다.

  2. 사용할 각 단말기의 모드에 PDV가 표시됩니다.

  3. 계산대에서 POS를 새로고침하고 결제를 누르세요. 결제 방법에 Mercado Pago Terminal 타일이 표시되고 키패드 위에 단말기가 나타납니다.

  4. 본인 카드로 소액을 결제한 다음 환불하세요.

버전 0.1에서 업그레이드하기​

  • 먼저 WCPOS, WCPOS Pro, 앱을 2.0으로 업데이트한 다음 확장 기능을 업데이트하세요.
  • 새 웹훅과 비밀 키를 추가하세요. 웹훅 추가를 참고하세요. 0.1 웹훅 주소는 더 이상 사용할 수 없으며 서명이 없는 알림은 거부됩니다.
  • 업그레이드 도중 진행 중이던 결제는 이어집니다. 금액이 두 번 청구되지 않습니다.
  • 다음 0.1 설정은 없어졌습니다: 기본 단말기, 활성화된 단말기, 단말기 선택 잠금, 결제 디버그 로그, 로그 수준. 이제 계산대에서 설정 > 카드 리더기로 단말기를 선택합니다.
  • 모드로는 더 이상 환경을 선택하지 않습니다. 저장된 액세스 토큰이 사용하려는 토큰인지 확인하세요.
  • 이제 결제 탭에서 결제를 진행합니다. 레거시 탭도 계속 사용할 수 있지만 전체 잔액 결제만 가능합니다.
  • 0.1에서 받은 판매도 평소처럼 환불할 수 있습니다. Mercado Pago 결제 환불하기를 참고하세요.

설정 참고 자료​

WP Admin > WooCommerce > 설정 > 결제 > Mercado Pago Terminal에서:

설정기능
활성화온라인 매장의 결제 화면에 결제 게이트웨이를 표시합니다. 끈 상태로 두세요. POS에는 POS > 설정 > 결제의 별도 스위치가 있습니다.
제목계산대 타일의 이름입니다. 기본값은 Mercado Pago Terminal입니다.
설명기본값은 Pay in person on a Mercado Pago Point terminal.입니다.
모드기본값인 테스트 또는 실운영입니다. 운영용 토큰에 맞게 실운영으로 설정하세요. 표시용 레이블일 뿐이며 필드 설명과 관계없이 실제 결제 여부는 액세스 토큰으로 결정됩니다.
액세스 토큰Mercado Pago Developers → 내 연동 → 애플리케이션 → 운영용 인증 정보에서 확인합니다. 저장 후에는 끝부분만 표시됩니다. 저장된 토큰을 유지하려면 비워 두세요. 교체하기 전에 진행 중인 결제를 완료하세요.
웹훅 비밀 키Mercado Pago 애플리케이션 웹훅의 비밀 서명입니다. 설명에 매장의 웹훅 URL이 표시됩니다. 토큰과 같은 방식으로 저장되며 표시됩니다.

로그 및 지원용 자료 묶음​

설정 페이지 아래에 지원 자료 묶음, 진단 메시지 및 로그 링크가 있습니다.

아직 설정하지 않은 매장의 Mercado Pago Terminal 설정 하단: Download support bundle 버튼이 있는 Support bundle, Mercado Pago access token is missing 메시지가 있는 Mercado Pago diagnostics, View logs
  1. 진단 메시지 — 아직 설정하지 않은 이 매장에는 *Mercado Pago access token is missing.*가 표시됩니다. 설정된 매장에는 단말기 목록과 함께 *Credentials accepted.*가 표시됩니다.
  2. 로그 보기 — WooCommerce > Status > 로그를 열며 소스는 mercadopago-terminal입니다.
  3. 지원 자료 묶음 다운로드 — WCPOS 지원팀에 전달할 파일입니다.

로그에는 토큰과 카드 번호를 제거한 뒤 Mercado Pago로 보낸 요청과 응답이 기록됩니다.

결제에 문제가 생기면 지원 자료 묶음 다운로드를 클릭하고 주문 번호와 함께 파일을 WCPOS 지원팀에 보내세요. WCPOS Pro에서 이 버튼을 추가합니다. 자료 묶음에는 사이트의 모든 POS 결제 제공업체 기록이 포함되며 비밀 정보와 카드 번호는 제거됩니다. 매장에서 서명된 웹훅을 마지막으로 받은 시점도 표시됩니다.

지원하지 않는 기능​

  • 팁 또는 지금 승인하고 나중에 청구하기
  • 단말기에서 전표 인쇄하기
  • STANDALONE 모드인 단말기에서 결제 받기
  • 단말기 또는 Mercado Pago에서 처리한 환불 기록하기
  • 통화 변환: 매장과 Mercado Pago 계정에서 같은 통화를 사용해야 합니다.
  • 계정당 단말기 50개 초과
  • WP Admin에서 매장 전체의 기본 단말기를 설정하거나 계산대에서 사용할 수 있는 단말기를 제한할 수 있습니다. 각 계산대에서 단말기를 선택합니다.
  • HPOS(WooCommerce 주문 테이블): 확장 기능이 아직 지원을 선언하지 않았습니다.
개발자를 위한 작동 원리

이 결제 게이트웨이는 WCPOS Pro 결제 제공업체를 통해 Point용 Mercado Pago Orders API(POST /v1/orders with type: point)를 사용합니다. 결제마다 계산대의 금액, 단말기 ID, print_on_terminal: no_ticket, 결제 외부 참조 및 멱등성 키를 포함한 Mercado Pago 주문이 생성되므로 다시 시도해도 중복 청구되지 않습니다. 주문은 5분 후 만료됩니다(필터 mptfwc_order_expiration_time).

계산대는 2초마다 상태를 확인합니다. 웹훅 wp-json/wcpos/v2/payments/webhook?provider=mercadopago에는 유효한 x-signature(웹훅 비밀 키를 사용한 HMAC-SHA256)가 있어야 합니다. 본문은 신뢰하지 않으며 매장에서 Mercado Pago에 주문을 다시 요청합니다. WooCommerce POS는 보완 조치로 응답을 받지 못한 결제를 10분마다 확인합니다.

단말기 정보는 /terminals/v1/list에서 가져오며 PDV 모드인 단말기만 온라인으로 간주합니다. 버전 0.1의 필터 mptfwc_order_payload 및 mptfwc_poll_interval_ms는 없어졌습니다.