VibeFox MercadoPago for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

WooCommerce: 8.0 以降。インストールされ、有効になっている必要があります。WooCommerce がない場合、プラグインは有効化されません。

PHP: 8.0 以降。

ストアの通貨: MercadoPago アカウントの国の通貨です。ARS（アルゼンチン）、BRL（ブラジル）、CLP（チリ）、COP（コロンビア）、MXN（メキシコ）、PEN（ペルー）、UYU（ウルグアイ）のいずれかです。MercadoPago はアカウントの通貨で請求し、換算は行いません。そのため、通貨が一致しない場合は支払い方法が非表示になります。

MercadoPago アカウント: MercadoPago 開発者パネル（Your integrations > your application > Credentials）にアプリケーションがあり、テスト用の認証情報（TEST- で始まる）と本番用の認証情報（APP_USR- で始まる）を持っている必要があります。それぞれに公開キー（Public Key）とアクセストークン（Access Token）が必要です。通知の任意の署名検証には、your application > Webhooks の署名シークレットも必要です。

VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。

インストール

1. WordPress で Plugins > Add New > Upload Plugin に進み、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_mercadopago_gateway フォルダを /wp-content/plugins/ にアップロードすることもできます。

2. Activate をクリックします。

3. 設定を開きます。WooCommerce > Settings > Payments > MercadoPago > Manage、またはプラグインページのプラグイン名の下にある Settings をクリックします。

4. ページ上部のライセンスブロックに VibeFox ライセンスキーを入力し、Activate をクリックします。

5. Account country を選択し、テスト用と本番用の認証情報を入力します。必要に応じて、MercadoPago アプリケーションで通知を設定します（設定を参照）。

6. Enable / Disable をオンにして保存します。MercadoPago のテストカードで動作を確認します（カード名義人 APRO = 承認、CONT = 保留、OTHE = 拒否）。その後、Test mode のチェックを外します。

設定

すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > MercadoPago。テストモードがオンの間、フィールドの上に Test mode is on: the TEST- credentials are used and no real money is charged. と表示されます。現在のモードの認証情報が不足している場合、ストアの通貨が MercadoPago アカウントの通貨と異なる場合（この場合、支払い方法はチェックアウトで非表示になります）、認証情報が Account country とは別の国のアカウントに属している場合に警告が表示されます。支払い方法の一覧では、現在のモードに認証情報が設定されるまで、MercadoPago は設定が必要な状態として表示されます。

保存時、想定されるプレフィックス（テストフィールドは TEST-、本番フィールドは APP_USR-）で始まらない認証情報は保存されません。エラーが表示され、以前の値が保持されます。プラグインは、Access Token がどの国のものかも MercadoPago に問い合わせます。トークンを確認できない場合、アカウントが対応国にない場合、または国が Account country と一致しない場合は、エラーが表示されます。その場合、プラグインはアカウントの国を使用します。

一般

Enable / Disable: Enable MercadoPago card payments で支払い方法をオンまたはオフにします。デフォルト: オフ。

Title: チェックアウトで購入者に表示される支払い方法の名称です。デフォルト: Credit or debit card (MercadoPago)。

Description: チェックアウトでカードフィールドの上に表示されるテキストです。デフォルト: Pay securely with your credit or debit card. Card data is sent directly to MercadoPago.

MercadoPago アカウント

MercadoPago 開発者パネルでアプリケーションの認証情報を取得します：Your integrations > your application > Credentials。テスト用の認証情報は TEST-、本番用の認証情報は APP_USR- で始まります。

Account country: MercadoPago アカウントの国です。請求通貨、カードフィールドの言語、カード名義人の書類が必要かどうかを決定します。ストアの通貨は同じである必要があります。たとえばアルゼンチンなら ARS です。デフォルト: Argentina (ARS)。

Argentina (ARS), Brazil (BRL), Chile (CLP), Colombia (COP), Mexico (MXN), Peru (PEN), Uruguay (UYU): 対応している国です。書類のフィールドは、メキシコを除くすべての国で表示されます。

Test mode: Use the test credentials (no real charges)。テストモードでは TEST- の認証情報を使用し、MercadoPago のテストカードで支払います。チェックアウトには TEST MODE バッジが表示されます。チェックを外すと、本番用の認証情報で実際のカードに請求します。デフォルト: オン。MercadoPago のテストユーザーアカウント（APP_USR- の認証情報）でテストするには、そのアカウントの認証情報を本番用フィールドに入力し、テストモードをオフにします。

Test Public Key: TEST- で始まります。ブラウザでカードをトークン化するために使用されます。

Test Access Token: TEST- で始まります。サーバー側でのみ使用されます。秘密に保ってください。

Production Public Key: APP_USR- で始まります。

Production Access Token: APP_USR- で始まります。サーバー側でのみ使用されます。秘密に保ってください。

支払いオプション

Maximum installments: 購入者が選べる最大分割回数です（1 から 24）。1 = 一括払いのみで、分割回数のフィールドは表示されません。この上限はサーバー側でも適用されます。デフォルト: 1。

決済通知（Webhook）

カード決済は通常すぐに最終結果が返されます。MercadoPago が審査中（処理中または保留）として扱う決済は、MercadoPago からの通知によって完了します。サイトに公開アドレスがある場合、プラグインは各決済で通知 URL を送信します。your application > Webhooks の、イベント Payments で追加することもできます。この URL は設定のこのセクションに表示され、https://your-site/wc-api/wc_mpg_webhook/?source_news=webhooks のような形式です。

通知はそのままでは信頼されません。プラグインは、決済が行われた環境の Access Token を使用して、MercadoPago API から決済を再取得し、注文 ID と注文キーによって注文に紐付けます。通知がない場合、審査中の注文は、手動で更新するまで保留のままになります。

プラグインは以下の MercadoPago の決済ステータスを処理します：

approved: 決済が承認されました。金額と通貨が一致すると、注文は支払い済みになります。

in_process, pending, authorized: 決済は審査中です。注文は保留になり、後の通知によって完了します。

rejected, cancelled: 決済が拒否またはキャンセルされました。未払いの注文は失敗になります。

refunded, charged_back, in_mediation: メモが追加されます。注文ステータスは変わりません。

Webhook secret signature: 任意です。your application > Webhooks に表示される署名シークレットです。設定すると、有効な x-signature がない通知は拒否されます（HTTP 401）。

詳細設定

Debug log: Log API requests and notifications を有効にすると、WooCommerce > Status > Logs に、ソース wcp_mercadopago_gateway として記録されます。Access Token、カードトークン、支払者のデータはログに記録されません。デフォルト: オフ。

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted。注文に保存された MercadoPago の決済 ID は決済履歴であり、常に保持されます。デフォルト: オフ。

チェックアウト

購入者は支払い方法（デフォルトは Credit or debit card (MercadoPago)）を選択し、カードフィールドに入力します：Card number、Expiry (MM/YY)、Security code、Cardholder name。国やカードによっては、購入者は Document type を選択して Document number を入力し、Card issuer を選び、Installments の回数を指定する必要もあります。分割払いの選択肢と手数料は、注文合計に対して MercadoPago から提供されます。

注文が確定すると、MercadoPago がカードを 1 回限りのトークンに変換し、貴店のサーバーが注文合計金額で決済を作成します。請求先のメールアドレスと名前、書類、注文番号は MercadoPago に渡されます。CLP と COP の金額は小数点なしで請求され、整数に丸められます。そのため、これらの通貨については WooCommerce の小数点以下の桁数を 0 に設定してください。

承認された決済は直ちに支払い済みになり、購入者は注文受付ページに進みます。審査中の決済は注文を保留にします。購入者は同じく注文受付ページに進み、注文は通知によって完了します。拒否されたカードは、チェックアウトに短い理由を表示します。例：Your card has insufficient funds. Please use another card or payment method. または Please check the security code of your card.。購入者はデータを修正するか、別のカードを使用できます。試行ごとに新しいカードトークンが作成されます。

MercadoPago が応答しない場合、購入者には We could not confirm your payment with MercadoPago. Please wait a minute before trying again — if the payment went through, your order will be updated automatically. と表示されます。次の試行では、まず決済を照会するため、カードが二重に請求されることはありません。注文の支払い処理中にもう一度クリックすると、This order is already being paid. Please wait a moment and check your e-mail before trying again. と表示されます。

この支払い方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで利用できます。WooCommerce High-Performance Order Storage（HPOS）に対応しています。

本プラグインはクレジットカードとデビットカードのみに対応しています。Checkout Pro へのリダイレクト、MercadoPago ウォレットや口座残高、現金（Rapipago、OXXO、boleto など）、Pix、PSE、Yape、保存済みカードやサブスクリプション、個別のオーソリとキャプチャ、3-D Secure の認証、通貨換算には対応していません。

注文と返金

注文ステータス

Pending payment: 注文は作成されていますが、タイムアウトの後などで、まだ決済結果が届いていません。

Processing: MercadoPago が決済を承認し、金額と通貨が一致しています。ダウンロード可能な仮想商品のみの注文は、WooCommerce の標準動作どおり完了になります。注文メモには MercadoPago の決済 ID と分割回数が表示されます。取引 ID は MercadoPago の決済 ID です。

On hold: 決済は審査中（処理中または保留）で、MercadoPago の通知を待っています。承認された金額または通貨が注文と一致しない場合や、MercadoPago が予期しないステータスを返した場合も、保留になります。注文メモに理由が記載されます。

Failed: 決済が拒否またはキャンセルされました。注文メモにステータスと詳細が表示されます。購入者は再度支払うことができます。

キャンセルまたは返金済みの注文に対して MercadoPago が決済を承認した場合、ステータスは変わらず、注文を完了するか決済を返金するよう求めるメモが追加されます。すでに支払い済みの注文に別の決済が届いた場合、MercadoPago パネルで余分な決済を返金するよう求めるメモが追加されます。

返金

注文を開き、Refund をクリックして金額を入力し、Refund via Credit or debit card (MercadoPago) をクリックします（ボタンには Title で設定した名称が表示されます）。全額返金と一部返金に対応しています。返金は、決済が行われた環境（テストまたは本番）の認証情報で送信されるため、その環境の Access Token が設定されている必要があります。MercadoPago が返金を拒否した場合、WooCommerce は理由とともに MercadoPago refused the refund を表示し、返金は記録されません。承認済みまたは処理中の返金は、返金 ID とともに注文メモに追加されます。

MercadoPago パネルで行われた返金とチャージバックは、通知によって届き、注文メモに追加されます。WooCommerce の返金として自動的に記録されることはありません。

ライセンスキー

本プラグインは、vibefox.net で取得した VibeFox ライセンスキーを使用します。ライセンスブロックは WooCommerce > Settings > Payments > MercadoPago の上部にあります。キーを License key に貼り付け、Activate をクリックします。ブロックには、ライセンスの有効期限の日付やお使いのドメインなど、ステータスが表示されます。Check now でステータスを再確認でき、Change key で別のキーを入力でき、Remove key でこのサイトからキーを削除できます。Manage licenses and domains in your account のリンクから vibefox.net のアカウントを開けます。

1 つのキーは 1 つのドメインで使用できます。サイトからキーを削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。

有効なキーがない場合、MercadoPago はチェックアウトで購入者に表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。ログイン中のストア管理者には、(unlicensed — visible to admins only) と表示された状態で支払い方法が引き続き表示されるため、キーを購入する前にプラグインを設定してテストできます。プラグインページと WooCommerce のページには、リマインダーが表示されます。既存の注文は影響を受けません。すでに開始された決済は引き続き確認され、返金も機能します。

ライセンスの有効期限が切れた場合も、プラグインは動作を続けますが、アップデートとサポートには更新が必要です。ステータスはバックグラウンドで自動的に再確認されます。

トラブルシューティング

MercadoPago does not appear at checkout: ライセンスが有効であること、Enable / Disable がオンであること、現在のモードに正しいプレフィックスの認証情報が両方あることを確認してください。テストモードでは TEST- のキー、本番では APP_USR- のキーです。ストアの通貨（または Pay for order ページの注文通貨）が MercadoPago アカウントの通貨と一致しているか確認してください。設定ページには、不足している項目が表示されます。

The payment went through, but the order stays On hold or Pending payment: 決済は完了したものの、注文が保留または支払い待ちのままになっています。通知が届いていません。プラグインが通知 URL を送信するのは、サイトに公開アドレスがある場合のみです（localhost や .local、.test のドメインは対象外です）。設定にある URL を your application > Webhooks に、イベント Payments とともに追加してください。Webhook secret signature が設定されている場合は、同じアプリケーションのシークレットであることを確認してください。MercadoPago パネルには、通知ごとに貴店からの応答が表示されます。

Notification answers invalid signature: 署名シークレットが別のアプリケーションのものであるか、通知に有効な x-signature がありません。シークレットをもう一度コピーするか、フィールドを空にしてください。

Notification answers not for this store: この決済は、MercadoPago で支払われた本ストアの注文に属していません。注文は変更されません。

A credential is not saved: エラー must start with は、その値がフィールドに対して誤ったプレフィックスを持っていることを示します。テストフィールドには TEST- の認証情報、本番フィールドには APP_USR- の認証情報を入力してください。

The customer sees This payment method is not configured correctly. Please choose another payment method or contact the store.: 現在のモードの認証情報が不足しているか、プレフィックスが誤っているか、MercadoPago に拒否されています。設定ページで確認してください。

The customer sees MercadoPago cannot process payments in: 注文の通貨が MercadoPago アカウントの通貨ではありません。MercadoPago は通貨を換算しません。

The secure card form does not load: 購入者には The secure card form could not be loaded. Please reload the page or choose another payment method. と表示されます。現在のモードの Public Key を確認してください。詳細は、Debug log を有効にして、WooCommerce > Status > Logs でソース wcp_mercadopago_gateway を確認してください。

Refund fails with a message about the mode: 決済はテストモードまたは本番モードで行われましたが、そのモードの Access Token が設定されていません。入力してから、もう一度お試しください。

Refund fails with MercadoPago did not answer the refund request: 再試行する前に、MercadoPago パネルで決済を確認してください。

The license block shows an error: ライセンスブロックのメッセージに従ってください。たとえば、キーがすでに別のドメインで使用されている場合は、vibefox.net のアカウントで枠を解放し、Check now をクリックします。サイトのアドレスが変わった場合は、Check now をクリックして新しいドメインでキーを有効にします。ライセンスサーバーに接続できない場合、プラグインは最後に確認できたステータスで動作を続けます。

アンインストール

プラグインを無効化してもすべてのデータは保持されます。削除するには、無効化してから Plugins ページで削除してください。このプラグインのライセンスキーとライセンスステータスは、常に削除されます。ゲートウェイの設定、保存されたアカウントの確認結果、ログは、Delete data on uninstall がオンの場合のみ削除されます。それ以外の場合は、後日の再インストールのために残ります。既存の注文には、決済メモ、MercadoPago の決済 ID、取引 ID が保持されます。

MercadoPago は、それぞれの所有者の商標です。本プラグインは MercadoPago と提携しておらず、MercadoPago による推奨も受けていません。