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 の webhook、5 分後のバックグラウンド確認により、ブラウザーを閉じた場合でも決済を確認します
WooCommerce から返金
WooCommerce の注文画面から全額または一部を返金できます
診断機能を内蔵
設定画面で接続と webhook の状態を確認し、トラブルシューティング用のサポート一式をダウンロードできます
仕組み
このゲートウェイは Mercado Pago のクラウド Orders API for Point を使用します。決済を開始すると、WooCommerce の注文合計全額で Mercado Pago の注文を作成し、選択した端末に送信します。Mercado Pago の注文は 5 分後に期限切れになります。
決済ページは 2 秒ごとに Mercado Pago に状態を問い合わせます。Webhook と 5 分後のバックグラウンド確認によっても、ブラウザーを閉じた場合に支払い済みの注文を完了できます。Webhook の設定は任意ですが推奨されます。Webhook シークレットがない場合も通知は処理されますが、署名検証は行われません。
端末は PDV（統合）モードである必要があります。端末は STANDALONE モードで出荷されるため、決済を受け付ける前にゲートウェイ設定で PDV に切り替え、端末を再起動してください。
セットアップ
Mercado Pago Terminal for WooCommerce をインストールする
GitHub のリリースページ から プラグインの zip アセット（GitHub のソースコード zip ではありません）をダウンロードします。WooCommerce がインストールされ有効になっていることを確認し、プラグイン > 新規追加 > プラグインのアップロード からアップロードして有効化します。
Mercado Pago の認証情報を追加する
WP Admin > WooCommerce > 設定 > 支払いに移動し、Mercado Pago Terminal を開きます- モードを選択します。
Testはサンドボックス仮想端末を使用し、Liveは実際の端末を使用します - Mercado Pago の Your integrations → Credentials から、アプリケーションの アクセストークン(
APP_USR-…)をコピーして貼り付けます
Live モードで TEST- トークンを使うと、決済はサンドボックスに送信されます。この組み合わせは設定画面で警告されます。実際の決済を受け付ける前に、本番用トークンを貼り付けてください。
webhook を登録する
- Mercado Pago で Your integrations → アプリケーション → Webhooks の順に移動します
- ゲートウェイ設定画面に表示されている webhook URL を追加します
- Order (Mercado Pago) イベントを選択して保存します
- secret signature をコピーし、WooCommerce の Webhook シークレットに貼り付けます
Webhook の設定は任意です。設定しなくてもポーリングによって決済は完了しますが、シークレットを設定するとプラグインが webhook の署名を検証できます。
端末をセットアップする
- 設定を保存し、画面を再読み込みします。既定のターミナルのドロップダウンと ターミナルの表に、アカウントの端末が表示されます
- STANDALONE モードと表示された端末は、PDV に切り替えるをクリックしてから、端末を再起動します
- 既定のターミナルを選択します
- (任意) 有効なターミナルを、レジ係が選択できる端末に限定します。空欄の場合はすべての端末を使用できます。保存済みの既定のターミナルは、ここで選択されていなくても使用できます
- (任意) ターミナル選択をロックを有効にすると、常に既定のターミナルを使用し、レジ係が変更できないようにします。この設定には既定のターミナルが必要です
- 設定を保存します
WCPOS で有効にする
WP Admin > POS > 設定 > 支払いに移動します- Mercado Pago Terminal ゲートウェイを見つけ、POS で有効にします
- 設定を保存します
WooCommerce 設定画面の 有効化／無効化チェックボックスが制御するのは、オンラインストア の決済のみです。このゲートウェイは設定後、チェックボックスの状態にかかわらず WCPOS で使用できます。
設定項目
| 設定 | 説明 |
|---|---|
| 有効化／無効化 | オンラインストアの決済でゲートウェイを有効にします。POS での有効化は POS > 設定 > 支払い で設定します |
| タイトル | 決済画面に表示するラベルです。既定値は Mercado Pago Terminal です |
| 説明 | 決済画面に表示する説明です。既定値は Pay in person on a Mercado Pago Point terminal. です |
| モード | Test（既定）はサンドボックス仮想端末を使用し、Live は本番用認証情報で実際の端末を使用します |
| アクセストークン | Mercado Pago の Your integrations → Credentials にあるアプリケーションのトークンです。保存済みのトークンは再表示されません。保持する場合は空欄にします |
| Webhook シークレット | 通知の検証に使用する、Mercado Pago の webhook 設定にある secret signature です |
| 既定のターミナル | 決済時に既定で使用する端末です。アカウントからリアルタイムで取得されます。一覧を取得できない場合はテキストフィールドが表示されます |
| 有効なターミナル | レジ係が選択できる端末を制限します。空欄の場合はすべての端末を使用でき、既定のターミナルは常に使用できます。一覧を読み込めない場合は非表示になります |
| ターミナル選択をロック | 常に既定のターミナルを使用し、レジ係が変更できないようにします。既定のターミナルが必要です |
| チェックアウトのデバッグログ | 決済パネルに ログを表示、コピー、消去を表示します。既定ではオフです。サポート用にログを収集する場合に有効にします |
| ログレベル | Off、Errors only、Debug のいずれかです。このリリースでは既定値は Debug で、シークレットを除いたリクエストとレスポンスを記録します |
各フィールドの下にある Mercado Pago Terminal の診断情報の表には、API チェック（端末数と PDV 数を含む）、最後に検証された webhook、アクティブな環境、認証情報の設定状況、既定のターミナル、webhook URL、決済ログへのリンクが表示されます。
使い方
決済処理
- 商品を追加: POS のカートに商品を追加します
- ゲートウェイを選択: 決済方法として Mercado Pago Terminal を選択します
- ターミナルを選択: 端末を選択するか、選択がロックされている場合は既定のターミナルを使用します
- 決済を開始: ターミナル決済を開始をクリックして注文合計を端末に送信します
- 顧客による決済: 顧客が端末で決済を完了する間、ステータスメッセージ
Sending to terminal…→Waiting for terminal…→Customer is paying on the terminal…を確認します - 自動完了: Mercado Pago が決済を確認すると、注文が完了し、POS はレシート画面に移動します
決済の操作
- ターミナル決済を開始: 選択した端末に新しい決済リクエストを送信します
- ターミナル決済をキャンセル: 端末が決済を受け取る前に限りキャンセルできます。受け取り後は端末でキャンセルするか、5 分後の期限切れまで待ちます
- ページの再読み込み: 進行中の決済を再開します
レシート
端末からレシートは印刷されません。決済完了後に POS のレシートを使用してください。
返金
WooCommerce の注文返金画面を開き、Mercado Pago Terminal 経由で返金を選択して全額または一部を返金します。Mercado Pago では、決済から 90 日以内の返金が可能です。
カードのアクワイアラーによっては、端末からの返金しか認められない場合があります。その場合は端末で返金し、WooCommerce に 手動返金を記録します。
ログとサポート一式
ログは WooCommerce > Status > ログ で、ソース mercadopago-terminal を選んで確認できます。このリリースではログレベルの既定値は Debug です。リクエスト、レスポンス、webhook、決済状態の変更が記録され、シークレットとカード番号は伏せられます。
ゲートウェイ設定画面で サポートバンドルをダウンロードをクリックして .txt ファイルをダウンロードし、サポートへの問い合わせに添付します。環境の詳細、認証情報をマスクした設定、端末一覧と動作モード、直近 10 件の注文の決済試行、最新 500 行のログが含まれます。このファイルを使って決済を行うことはできません。
チェックアウトのデバッグログを有効にすると、決済パネルに ログを表示、コピー、消去が追加されます。この設定に関係なく、決済の操作は WooCommerce のログに記録されます。
要件
対応範囲と制限事項
- 端末では注文合計全額が決済されます。注文の一部だけを端末で支払うことはできません
- チップには対応していません
- 金額は小数点以下2桁で送信されます。チリペソまたはコロンビアペソで販売する店舗は、まずテスト決済で確認してください
- オンラインストアのブロックベースのチェックアウトには対応していません
- このプラグインは、現時点で HPOS への対応を宣言していません
トラブルシューティング
よくある問題
Mercado Pago がアクセストークンを拒否する（HTTP 401）
- アクセストークンが無効か、古くなっています
- Your integrations → Credentials から新しいトークンをコピーし、アクセストークンに保存します
端末が一覧に表示されない
- アカウントに Point 端末がリンクされていない場合は、その Mercado Pago アカウントで端末にログインし、PDV に切り替えて再起動します
- 既定のターミナルがドロップダウンではなくテキストボックスの場合、一覧を取得できていません。トークンと診断情報を確認してから、設定画面を再読み込みします
端末が STANDALONE モードになっている
- 統合決済には PDV モードが必要です
- 設定画面の ターミナルの表で PDV に切り替えるをクリックし、端末を再起動します
決済がすでに端末に送信されている
- 端末が決済を受け取ったため、WooCommerce からキャンセルできません
- 端末でキャンセルするか、5 分後の期限切れまで待ちます。決済ページは引き続き状態を確認します
webhook が一度も検証されていない
- 診断情報に 最後に検証された webhook: なしと表示される場合は、Mercado Pago の webhook URL とシークレットを確認します
- Webhook シークレットが設定されていない場合は、Mercado Pago の secret signature を貼り付けます。ポーリングで決済は完了しますが、シークレットのない通知は署名検証されません
カードアクワイアラーが返金を拒否した
- アクワイアラーによっては端末からの返金しか認められません。また、Mercado Pago では返金可能期間が 90 日に制限されています
- 端末で返金し、WooCommerce に 手動返金を記録します
端末で決済の有効期限が切れた
- Mercado Pago の注文は 5 分で期限切れになります
- 決済を再度開始します
サポートを受ける
- サポートへの問い合わせに、ゲートウェイ設定画面から取得した サポートバンドルを添付してください
- 問題を報告するには GitHub リポジトリ にアクセスしてください
- アカウントやハードウェアに関する質問は Mercado Pago サポートにお問い合わせください