Mercado Pago Terminal決済ゲートウェイ
レジからMercado Pago Point Smart端末に注文の合計金額を送信し、お客様が端末で支払います。Mercado Pagoが支払いを確認すると、販売処理が自動的に完了します。このページでは、レジでの決済の受付と、WP Adminでの設定を説明します。
この拡張機能は新しく、カード決済や払い戻しを完了した実績がまだありません。実際の運用に使う前に、少額の決済とその払い戻しを行ってください。 本番アカウントと実機のPoint Smartで、端末一覧の表示、端末のPDVモードへの切り替え、Mercado Pago経由での端末向け決済の作成とキャンセルが動作することを確認しています。その後の端末への決済表示、カード決済の完了、支払い済み注文に対するMercado Pagoからの通知、払い戻し、Mercado Pagoのサンドボックス(テストモード)はまだ確認していません。これまでに確認した内容
決済を受け付ける
決済はPOS内に表示される店舗サイトの決済ページで行われるため、WCPOS Proと、オンライン状態の店舗サイトが必要です。まず、WP Adminにアクセスできる担当者がゲートウェイを設定します。
レジの開閉がオンの場合、レジを閉じたままでは支払いを記録できず、すでにカードで受け取った代金は払い戻す必要があります。チェックアウトを参照してください。
端末はチェックアウトのレガシータブから操作します。下の画像ではMercado Pagoが未設定のため、他のゲートウェイが一覧に表示され、カードが選択されています。設定済みの店舗では、この一覧にMercado Pago Terminalが表示されます。

- レガシータブ — POS内で店舗サイトの決済ページを開きます。
- 店舗サイトの決済ページ — 注文の合計金額と店舗のゲートウェイが表示されます。設定後は、この一覧にMercado Pago Terminalが表示されます。選択すると、その下にパネルが開き、端末と端末決済を開始が表示されます。
- 支払いを処理 — Mercado Pagoでは不要です。支払いが確認されると、販売処理が自動的に完了します。
- カートに商品を追加し、チェックアウトを押します。
- レガシータブを開きます。POS内に店舗サイトの決済ページが開きます。レガシータブを参照してください。
- Mercado Pago Terminalを選択します。店舗によっては別の名前に変更されている場合があります。
- 端末欄で端末を確認します。デフォルトの端末があらかじめ選択されています。端末の選択がロックされている場合は変更できません。
- 端末決済を開始を押します。パネルに端末に送信中…、続いて端末の応答を待機中… と表示され、注文の合計金額が全額その端末に送信されます。
- お客様が端末で支払います。その間、パネルにはお客様が端末で支払い中… と表示されます。端末で支払いを確認してください。 と表示されたら、端末に表示される操作を完了してください。
- Mercado Pagoが支払いを確認すると、パネルに支払い完了 — 注文を完了しています… と表示され、POSがレシート画面に進みます。
レガシータブの下部にある支払いを処理は不要です。Mercado Pagoが確認すると、販売処理が自動的に完了します。その前に押しても、注文がまだ支払われていないというメッセージが表示されるだけです。
端末では常に注文の全額を決済するため、他の支払い方法と併用できません。注文の支払いを一度受け付けると、レガシータブは使えなくなります。先にその支払いをキャンセルしてください。
キャンセルする、または待つ
- 決済中は、端末決済を開始の代わりに端末決済をキャンセルが表示されます。キャンセルできるのは、端末が決済を受信するまでです。それ以降は、パネルに決済はすでに端末に送信されています。端末でキャンセルするか、有効期限が切れるまでお待ちください。 と表示されます。
- 開始から5分後に、Mercado Pago側で決済の有効期限が切れます。パネルは確認を続けるため、その前にお客様が支払いを完了すれば、販売処理は完了します。
- ページを再読み込みすると、進行中の決済が引き継がれ、端末決済をキャンセルが表示されます。
- 決済中にレジを閉じてしまった場合、カードに再度請求しないでください。店舗サイトは、Mercado Pagoからの通知と5分ごとの確認により、支払い済みの注文を自動的に完了する設計ですが、本番環境ではまだ確認していません。注文とMercado Pagoアカウント内の決済を開き、支払い済みかどうかを確認してください。
販売後
端末ではレシートを印刷しません。通常どおりPOSのレシートを印刷するか、メールで送信してください。チェックアウト時のレシートを参照してください。
注文には、Mercado Pagoの注文IDを取引IDとして支払いが記録されます。
払い戻し
WP Adminで注文を開き、払い戻しをクリックして金額を入力し、Mercado Pago Terminal経由で…を払い戻すを押します。注文の全額を指定すると全額払い戻し、それより少ない金額を指定すると一部払い戻しになります。Mercado Pagoでは、支払いから90日以内であれば払い戻しが可能です。
カード加盟店契約会社によっては、端末での払い戻ししか認めていない場合があります。Mercado Pagoで払い戻しが拒否された場合は、Point端末で払い戻しを行い、WooCommerceの手動で払い戻すで記録してください。払い戻しを参照してください。
問題が発生した場合
パネルのステータス行に状況が表示されます。同じ文言で始まる項目を開いてください。
決済が開始されない
先に端末を選択してください。
端末欄で端末を選択し、端末決済を開始をもう一度押します。
端末…はSTANDALONEモードです。
端末はまだレジからの決済を受け付けられません。ゲートウェイの設定担当者に、PDVへの切り替えと再起動を依頼してください。
このMercado Pagoアカウントに端末が見つかりません。 / 端末を読み込めませんでした。
店舗サイトで端末の一覧を取得できません。ゲートウェイの設定担当者に、診断情報の確認を依頼してください。
Mercado Pago Terminalは無効になっています。
POSでこのゲートウェイがオフになっています。WP Adminの担当者に、有効化を依頼してください。
Mercado Pago Terminalへのリクエストに失敗しました。
レジが店舗サイトまたはMercado Pagoに接続できませんでした。お客様がすでに支払った可能性がある場合は、別の決済を開始する前に注文とMercado Pagoアカウントを確認してください。それ以外の場合は、接続を確認して再試行してください。問題が続く場合は、サポート用ファイル一式を送信してください。
決済が進まない、または失敗する
再試行する前に、端末を確認してください。カードに二重請求しないでください。お客様がすでに支払った可能性がある場合は、先に注文とMercado Pagoアカウントを確認してください。
引き続き端末の応答を待機しています。
応答がないまま1分が経過しました。端末に決済が表示されている場合は、お客様に支払いを完了していただきます。表示されていない場合は、端末決済をキャンセルを押してやり直してください。
決済はすでに端末に送信されています。
端末でキャンセルするか、5分後に有効期限が切れるまでお待ちください。パネルは確認を続けるため、その間にお客様が支払えば販売処理は完了します。
決済に失敗しました。
カードまたは決済が拒否されました。端末決済を開始を押して再試行するか、別の支払い方法を使ってください。
端末で決済の有効期限が切れました。
5分が経過しました。端末決済を開始をもう一度押してください。
端末の応答待ちがタイムアウトしました。
結果が得られないまま6分が経過し、レジがMercado Pagoに決済のキャンセルを要求します。再試行する前に端末を確認してください。
Mercado Pagoから、この注文と一致しない決済が報告されました。
合計金額や通貨が変更されたなどの理由で、決済がこの注文と一致しませんでした。カードに再度請求しないでください。注文メモとMercado Pagoアカウント内の決済を確認し、責任者に連絡してください。
設定時のメッセージ
Mercado Pagoがアクセストークンを拒否しました(HTTP 401)。 トークンが誤っているか、有効期限が切れています。Mercado Pagoの連携一覧 → 認証情報から新しいトークンをコピーし、アクセストークンに保存してください。
アクセストークンにPointを使用する権限がありません(HTTP 403)。 トークンに対応するアプリケーションでPointを使用できません。連携一覧でアプリケーションを確認してください。
Mercado Pagoに接続できませんでした。 店舗サイトが接続できませんでした。トークンを確認してから、設定ページを再読み込みしてください。
このMercado Pagoアカウントには、まだPoint端末が紐付けられていません。 このMercado Pagoアカウントで端末にログインし、PDVに切り替えて再起動してください。
デフォルトの端末が一覧ではなくテキストボックスになっています。 端末一覧を読み込めませんでした。トークンと診断情報を確認してから、設定ページを再読み込みしてください。
本番モードが選択されていますが、アクセストークンはテスト用トークン(TEST-…)です。 この状態では決済がMercado Pagoのサンドボックスに送信されます。本番用トークンを貼り付けるか、モードをテストに戻してください。
最後に検証したWebhook:なし。 Mercado Pagoから署名付きの通知がまだ送信されていません。Webhook URLとWebhookシークレットを確認してください。決済パネルが開いている間は、引き続きパネルで決済を完了できます。
Mercado Pagoが払い戻しを拒否しました。 加盟店契約会社によっては端末での払い戻ししか認めていない場合があります。端末で払い戻しを行い、手動で払い戻すで記録してください。
有効化が拒否されます。 サーバーにはPHP 7.4以降が必要です。
設定する
ここからは、店舗サイトのWP Admin担当者向けの説明です。手順1に進む前に、必要なものを確認してください。
必要なもの
1. 拡張機能をインストールする
WP Admin > POS > 設定 > 拡張機能を開き、Mercado Pago Terminal for WooCommerceを探してインストールをクリックします。WCPOSがダウンロード、インストール、有効化をまとめて行います。拡張機能のインストールを参照してください。
ディレクトリを使わない場合は、GitHubのリリースページからプラグインのzipファイル(ソースコードのzipではありません)をダウンロードし、プラグイン > Add Pluginのプラグインのアップロードでアップロードしてから有効化します。WooCommerceが有効になっている必要があります。
2. Mercado Pagoで準備する
- 連携一覧でアプリケーションを作成し、本番用の認証情報を有効にします。Mercado Pagoでは、業種とウェブサイトの入力、利用規約への同意、reCAPTCHAの認証が求められます。
- Mercado Pagoで店舗とPOSを作成します。拡張機能では自動作成されません。
- Point Smart端末を紐付けます。同じMercado Pagoアカウントで端末にログインしてください。
3. ゲートウェイの設定を入力する
WP Admin > WooCommerce > 設定 > 支払いに移動し、Mercado Pago Terminalを開きます。- モードを選択します。テスト(デフォルト)ではMercado Pagoのサンドボックスの仮想端末を、本番では実機の端末を使用します。
- 連携一覧 → 認証情報にあるアプリケーションのアクセストークン(
APP_USR-…)を貼り付けます。モードに合ったトークンを使用してください。 - チリペソなど、小数単位のない通貨を使う場合は、
WooCommerce > 設定 > Generalで小数点以下の桁数を0に設定します。Mercado Pagoは、これらのアカウントでは小数を含む金額を拒否します。拡張機能が整数の金額を送信するのは、この設定が0の場合のみです。 - 保存します。
4. Webhookを追加する(推奨)
Webhookを使うと、Mercado Pagoから店舗サイトに決済の完了を通知できます。レジを閉じても支払い済みの注文を完了するための仕組みですが、本番環境ではまだ確認していません。再度請求する前に注文を確認してください。Webhookがなくても、決済パネルが開いている間はパネルで決済を完了できます。
- Mercado Pagoで、連携一覧 → 対象のアプリケーション → Webhookを開きます。
- ゲートウェイ設定のWebhookシークレットの下に表示されるWebhook URLを追加します。末尾は
admin-ajax.php?action=mptfwc_webhookです。 - 注文(Mercado Pago) イベントを選択して保存します。
- 署名用シークレットをWebhookシークレットにコピーして保存します。シークレットを保存すると、店舗サイトはそのシークレットで署名されていない通知を拒否します。シークレットがなくてもMercado Pagoの通知に応じて処理は行われますが、送信元がMercado Pagoであることを検証できず、最後に検証したWebhookはなしのままになります。
5. 端末を設定する
- 設定ページを再読み込みします。デフォルトの端末の一覧と端末の表に、アカウントの端末が表示されます。
- 端末はSTANDALONEモードで出荷されます。各端末でPDVに切り替えをクリックし、端末を再起動してください。Mercado Pagoでは再起動が必要です。
- デフォルトの端末を選択します。
- 任意で、有効な端末をレジ係が選択できる端末だけに制限します。空欄にするとすべて許可されます。デフォルトの端末は常に許可されます。
- 任意で、端末の選択をロックにチェックを入れると、レジ係は常にデフォルトの端末を使用します。
- 保存します。
6. POSで有効にする
WP Admin > POS > 設定 > 支払いに移動し、Mercado Pago Terminalを探して有効をオンにします。ゲートウェイの有効化を参照してください。
オンラインでも利用したい場合を除き、WooCommerce設定の有効化/無効化はオフのままにします。このチェックボックスの状態にかかわらず、ここで有効にすればPOSでゲートウェイを使用できます。
設定リファレンス
WP Admin > WooCommerce > 設定 > 支払い > Mercado Pago Terminalにあります。必要な設定は上の手順で説明しています。すべての設定とデフォルト値を確認するには、一覧を開いてください。
全11項目の設定と診断情報
| 設定 | 機能 |
|---|---|
| 有効化/無効化 | オンラインストアでもゲートウェイを利用できるようにします。デフォルトはオフです。POSには、POS > 設定 > 支払いに専用のスイッチがあります |
| タイトル | レジ係が決済ページで選択する名前です。デフォルトはMercado Pago Terminalです |
| 説明 | タイトルの下に表示される文です。デフォルトはPay in person on a Mercado Pago Point terminal.です |
| モード | テスト(デフォルト)ではサンドボックスの仮想端末を、本番では実機の端末を使用します |
| アクセストークン | 連携一覧 → 認証情報にあるアプリケーションのトークンです。保存後は末尾の4文字だけが表示され、全文は再表示されません。変更しない場合は空欄のままにします |
| Webhookシークレット | Mercado PagoのWebhook設定にある署名用シークレットです。トークンと同じ方法で保存・表示されます |
| デフォルトの端末 | 最初に選択される端末です。アカウントから取得した一覧が表示されます。一覧を読み込めない場合はテキストボックスになります |
| 有効な端末 | レジ係が選択できる端末です。空欄ではすべて許可され、デフォルトの端末は常に許可されます。一覧を読み込めない場合は非表示になります |
| 端末の選択をロック | レジ係が端末を変更できなくなり、常にデフォルトの端末を使用します。デフォルトの端末の設定が必要です |
| チェックアウトのデバッグログ | 決済パネルにログを表示、コピー、クリアを表示します。デフォルトはオフです。サポート用にログを収集するときにオンにしてください。この設定にかかわらず決済はログに記録されます |
| ログレベル | オフ、エラーのみ、デバッグ(デフォルト)から選択します |
設定の下にあるMercado Pago Terminalの診断情報には、端末数とPDVモードの端末数を含むAPIの確認結果、最後に検証したWebhook、使用中の環境、トークンとシークレットの設定状況、デフォルトの端末、Webhook URL、ログへのリンクが表示されます。端末の表には各端末のID、ラベル、動作モードが表示され、必要に応じてPDVに切り替えが表示されます。
ログとサポート用ファイル一式
ログはWP Admin > WooCommerce > Status > ログで、ソースmercadopago-terminalの下にあります。ログレベルの初期値はデバッグで、Mercado Pagoへのすべてのリクエストと応答、すべてのWebhook、決済状態のすべての変更を記録します。トークン、署名、カード番号は除外されます。
決済に失敗した場合は、ゲートウェイの設定ページでサポート用ファイル一式をダウンロードをクリックし、.txtファイルと注文番号をサポートに送信してください。このファイルには、決済の実行に使える情報は含まれていません。
サポート用ファイル一式に含まれるもの
- 店舗サイトの構成:拡張機能、WordPress、WooCommerce、PHP、WCPOSのバージョンと、HPOSの有効・無効。
- アクセストークンとWebhookシークレットを伏せたゲートウェイ設定。
- 端末とその動作モード。
- 端末を使用した直近10件の注文の決済試行。
mercadopago-terminalログの末尾500行。
対応していない機能
- 分割での支払い:端末では常に注文の全額を決済します。
- チップ。
- Mercado Pagoアカウントとは異なる通貨で価格を設定した店舗:注文を完了できません。
- 端末でのレシート印刷。
- オンラインストアのブロック形式のチェックアウト。
- HPOS(WooCommerceの注文テーブル):拡張機能はまだ対応を宣言していません。
開発者向けの動作説明
このゲートウェイは、Mercado PagoのPoint向け 注文API(POST /v1/orders に type: point を指定)を使用します。決済を開始すると、注文に冪等性キーと外部参照を保存し、選択した端末で注文の合計金額に相当するMercado Pagoの注文を作成します。有効期限は5分です(フィルター mptfwc_order_expiration_time)。タイムアウト後に再試行する場合は同じキーを再利用するため、二重に請求されることはありません。
パネルは2秒ごとにステータスを問い合わせ(フィルター mptfwc_poll_interval_ms)、6分後に確認を打ち切ります。Webhook(x-signature、HMAC-SHA256)と5分ごとの定期チェックでも、注文を完了できます。Webhookの本文は信頼せず、必ずMercado Pagoから注文を再取得します。
注文を完了するのは、Mercado Pagoの注文が対象の注文を指定し、この店舗サイトによって対象の注文用に作成され、point注文であり、合計金額と通貨が一致し、その決済試行の端末を使用している場合のみです。完了処理は注文単位のロックのもとで一度だけ実行されます。取引IDにはMercado Pagoの注文IDを使用します。
関連ドキュメント
- レガシータブ
- チェックアウト
- レジ設定
- 拡張機能
- GitHubで問題を報告してください。アカウント、認証情報、端末についてはMercado Pagoにお問い合わせください。