VibeFox MercadoPago for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。古いバージョンの PHP ではモジュールをインストールできません。

ショップの通貨: 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. 管理画面で Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択してください。

2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox MercadoPago Gateway を探し、Configure をクリックすることもできます。

3. Configure ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。

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

5. Enable / Disable をオンにして Save をクリックします。テストモードで MercadoPago のテストカードを使って決済を試したら、Test mode をオフにします。

インストール時に、モジュールは 2 つの注文ステータスを作成します。Awaiting MercadoPago payment と MercadoPago payment on hold です。PrestaShop は、インストール時に有効になっている国に新しい決済モジュールを割り当てます。Payment > Preferences で、モジュールの通貨、国、顧客グループを確認してください。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox MercadoPago Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。テストモードがオンの間、フィールドの上に Test mode is on: the TEST- credentials are used and no real money is charged. と表示されます。また、現在のモードの Public Key または Access Token が未入力の場合、ショップの通貨が MercadoPago アカウントの通貨と一致しない場合（この場合チェックアウトで支払い方法が非表示になります）、認証情報が Account country と異なる国のアカウントのものである場合に警告します。

保存時に、想定されるプレフィックス（テスト用フィールドは TEST-、本番用フィールドは APP_USR-）で始まらない認証情報は保存されず、must start with … — the previous value was kept. というエラーが表示されます。また、モジュールは MercadoPago に各 Access Token の所属国を問い合わせます。現在のモードのトークンを確認できない場合、アカウントが対応国にない場合、または国が Account country と一致しない場合は、エラーが表示されます。その場合、モジュールはアカウントの国を使用します。

MercadoPago

Enable / Disable: Enable MercadoPago card payments で、支払い方法のオン／オフを切り替えます。デフォルト: off。

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: テストモードでは TEST- の認証情報が使われ、MercadoPago のテストカードで支払いを行います。チェックアウトには TEST MODE バッジが表示されます。本番の認証情報で実際のカードに請求するには、オフにしてください。デフォルト: on。

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

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

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

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

保存済みの Access Token と Webhook シークレットは、再表示されません。フィールドは空のままになり、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

支払いオプション

Maximum installments: 顧客が選択できる分割回数の上限です。1 から 24 まで設定できます。1 = 一括払いのみで、分割回数のフィールドは表示されません。この上限はサーバー側でも適用されます。デフォルト: 1。

決済通知（Webhook）

カード決済は通常、すぐに最終結果が返されます。MercadoPago が審査中（処理中または保留中）として保留した決済は、MercadoPago からの通知によって完了します。ショップに公開アドレスがある場合（localhost や .local、.test のドメインではない場合）、モジュールは各決済で通知 URL を送信します。your application > Webhooks で、イベント Payments を選んで URL を追加することもできます。URL は、このセクションの Notification URL に表示されます。フレンドリー URL の場合、次のような形式になります：https://your-shop/en/module/wcp_mercadopago_gateway/webhook?source_news=webhooks。設定に表示されたとおりに、URL を正確にコピーしてください。

通知は、それ自体では信頼されません。モジュールは、決済が行われた環境の Access Token を使って MercadoPago API から決済を再取得し、ショップの決済試行と照合します。通知がない場合、審査中の注文は手動で更新されるまで Awaiting MercadoPago payment のままになります。

モジュールは次の MercadoPago 決済ステータスを処理します：

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

in_process, pending, authorized: 決済は審査中です。注文は Awaiting MercadoPago payment で待機し、後の通知によって完了します。

rejected, cancelled: 決済が拒否またはキャンセルされました。注文は作成されません。待機中だった注文には Payment error が設定されます。

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

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

Clear saved secrets: Test Access Token、Production Access Token、Webhook secret signature のいずれかにチェックを入れ、Save をクリックすると削除されます。フィールドが空の場合は、保存済みの値が保持されます。

詳細設定

Debug log: MercadoPago のリクエストと通知を、モジュールフォルダ内の logs/wc_mpg_debug.log.php に書き込みます。このファイルはウェブから開けません。エラーは、この設定がオフでも常に記録されます。Access Token、カードトークン、支払者のデータは記録されません。デフォルト: off。

Log: ログのサイズと最新の記録を表示します。Clear log をクリックすると、ログを消去できます。

Delete data on uninstall: オンにすると、モジュールのアンインストール時にゲートウェイの設定とログが削除されます。MercadoPago の決済記録、返金、モジュールの注文ステータスは常に保持されるため、以前に支払われた注文は再インストール後も返金できます。デフォルト: off。

チェックアウト

支払いステップで、顧客は支払い方法（デフォルトは Credit or debit card (MercadoPago)）を選び、カードフィールドに入力します：Card number、Expiry (MM/YY)、Security code、Cardholder name。国やカードによっては、顧客は Document type を選んで Document number を入力し、Card issuer を選び、Installments の回数を選ぶ必要もあります。分割払いの選択肢と手数料は、カート合計額に対して MercadoPago から提供されます。カードフォームは Classic テーマと Hummingbird テーマで動作します。

顧客が確定すると、MercadoPago がカードを 1 回限りのトークンに変換し、ショップがカート合計額の決済をサーバーで作成します。顧客のメールアドレスと氏名、書類、カード番号（カート番号）は MercadoPago に送信されます。決済は Cart #、カート番号、ショップ名で表示されます。CLP と COP の金額は小数点なしで請求されます。MercadoPago が応答するまで、注文は存在しません。

承認された決済では支払い済みの注文が作成され、顧客には Your card payment has been received. と表示される注文確認ページが表示されます。審査中の決済では Awaiting MercadoPago payment の注文が作成され、ページには MercadoPago is reviewing your payment. Your order will be updated automatically as soon as MercadoPago confirms it. と表示されます。審査中の決済が後で拒否された場合、ページには Your MercadoPago payment was not completed. Please contact us about this order. と表示されます。保留中の注文には Your payment is being reviewed. We will update your order as soon as the review is complete. と表示されます。

拒否されたカードでは注文は作成されません。顧客は支払いステップに留まり、例えば 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. と表示されます。注文が作成済みのカートが再請求されることはなく、顧客はその注文の確認ページに案内されます。

通知 URL は、ショップがメンテナンスモードの間も機能し、ショップの国制限でブロックされることはありません。

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

注文と返金

注文ステータス

No order: カードが拒否されたか、MercadoPago がまだ応答していません。カートのみが存在します。

Payment accepted: MercadoPago が決済を承認し、金額と通貨がカートと一致しています。決済は MercadoPago の決済 ID をトランザクション ID として記録され、メモには決済 ID、環境、分割回数が表示されます。

Awaiting MercadoPago payment: 決済は審査中（処理中または保留中）で、MercadoPago からの通知を待っています。MercadoPago が承認すると、注文は Payment accepted に移行します。

MercadoPago payment on hold: 承認された金額または通貨がカートと異なる、または MercadoPago が予期しないステータスを返しました。メモに理由が記載されます。注文を確認して処理するか、決済を返金してください。

Payment error: 審査中の決済が拒否またはキャンセルされました。メモにステータスと詳細が表示されます。

Refunded: モジュールを通じて決済が全額返金されました。

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

MercadoPago payment ブロック

注文ページには MercadoPago payment ブロックが表示され、決済 ID、決済ステータス、環境（テスト決済には Test バッジ）、分割回数、MercadoPago が請求した金額と注文合計、返金済みの金額、返金履歴、注文の MercadoPago notes が表示されます。

返金

MercadoPago payment ブロックで金額を入力し（まだ返金されていない金額が自動入力されます）、必要に応じて理由を入力して、Refund via MercadoPago をクリックします。確認の質問 Refund this amount through MercadoPago? This cannot be undone. で OK を選んでください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。返金は MercadoPago が請求した金額が上限です。そのため、金額の不一致が生じた場合は、注文合計ではなく顧客が実際に支払った金額まで返金できます。返金は決済が行われた環境（テストまたは本番）の認証情報で送信されるため、その環境の Access Token が設定されている必要があります。MercadoPago が返金を拒否した場合、ブロックに理由とともに MercadoPago refused the refund が表示され、返金は記録されません。承認済みまたは処理中の返金は、返金 ID とともに返金履歴とメモに追加されます。全額返金を行うと、注文は Refunded になります。一部返金ではステータスは変わりません。

モジュールはクレジットスリップを作成しません。注文ページにある PrestaShop の標準の返金ボタンでは、MercadoPago を通じて返金は行われません。

MercadoPago の管理画面で行われた返金、チャージバック、調停は、通知により届いてメモに追加されます。注文ステータスとクレジットスリップは自動的には変更されません。必要に応じて手動で更新してください。

ライセンスキー

モジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。License — VibeFox MercadoPago Gateway のライセンスブロックは、Modules > Module Manager > VibeFox MercadoPago Gateway > Configure ページの最初のブロックで、設定の上にあります。License key にキーを入力し、Activate をクリックしてください。その後、ブロックにはキーがマスク表示され、ステータス（ライセンスの有効期限日やドメインなど）と、ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-payment-mercadopago の行と、vibefox.net のアカウントを開くリンク Manage licenses and domains in your account があります。キーを変更できるのは、このモジュールの Configure 権限を持つスタッフだけです。ブロックのテキストはバックオフィスの言語に従います（英語とロシア語を含みます）。

キーが受け付けられない場合、ブロックには理由が表示されます。例えば Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on です。ショップのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認できたステータスで動作を続けます。

1 つのキーは 1 つのドメインで使用できます。マルチストア構成でも、メインショップのドメインに対して有効です。ショップからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがないと、チェックアウトで顧客に MercadoPago は表示されません。それでも決済が開始された場合、顧客には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、バックオフィスにログインしていることを認識しないため、決済方法はあなたにも非表示になります。購入前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。すでに開始された決済は引き続き確認され、返金も機能します。

ライセンスの期限が切れても、モジュールは動作し続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キー入力後最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンス状態は常に削除されます。

トラブルシューティング

チェックアウトに MercadoPago が表示されない: ライセンスが有効か、Enable / Disable がオンか、現在のモードに正しいプレフィックスを持つ両方の認証情報があるかを確認してください。テストモードでは TEST- のキー、本番では APP_USR- のキーです。カートの通貨が MercadoPago アカウントの通貨であることも確認してください。設定ページには、不足している項目が表示されます。Payment > Preferences で、モジュールがカートの通貨、顧客の国、顧客グループに対して許可されているかを確認してください。

決済は完了したが、注文が Awaiting MercadoPago payment のまま: 通知が届いていません。モジュールは、ショップに公開アドレスがある場合（localhost や .local、.test のドメインではない場合）にのみ通知 URL を送信します。Notification URL の URL を、イベント Payments とともに your application > Webhooks に追加してください。Webhook secret signature が設定されている場合は、同じアプリケーションのシークレットかどうか確認してください。MercadoPago の管理画面には、各通知に対するショップの応答が表示されます。

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

通知が no credentials for test または no credentials for live を返す: 決済が行われた環境の Access Token が設定されていません。入力してください。MercadoPago は通知を再送します。

通知が not for this store を返す: その決済は、このショップの決済試行に紐付いていません。注文は変更されません。

通知が order busy または payment could not be read を返す: 同じタイミングで別のリクエストによって注文が更新されていたか、MercadoPago に接続できませんでした。MercadoPago は自動的に通知を再送します。

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

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

顧客に MercadoPago cannot process payments in と表示される: カートの通貨が MercadoPago アカウントの通貨ではありません。MercadoPago は通貨換算を行いません。

安全なカードフォームが読み込まれない: 顧客には The secure card form could not be loaded. Please reload the page or choose another payment method. と表示されます。現在のモードの Public Key を確認してください。

顧客に Your payment was received, but the order could not be completed automatically と表示される: MercadoPago は決済を受け付けましたが、PrestaShop は注文を作成できませんでした（たとえば、その時点でモジュールが無効になっていた場合）。モジュールページの Log 欄を確認してください。エラーは常に記録されます。顧客には再度支払わないよう案内されます。そのカートに対する次の決済試行または通知によって、再請求なしで注文が作成されます。

支払い後に注文が MercadoPago payment on hold になる: 注文ブロックの MercadoPago notes を確認し（注文ステータスを参照）、注文を処理するか決済を返金してください。

モードに関するメッセージで返金が失敗する: 決済はテストまたは本番モードで行われましたが、そのモードの Access Token が設定されていません。入力してから再試行してください。

MercadoPago did not answer the refund request で返金が失敗する: 再試行する前に、MercadoPago の管理画面で決済を確認してください。

アンインストール

Modules > Module Manager に移動し、VibeFox MercadoPago Gateway の横にあるメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンス状態は常に削除されます。Delete data on uninstall がオンの場合、ゲートウェイの設定、保存済みのアカウント確認、ログが削除されます。オフの場合、後で再インストールできるようにすべての設定が保持されます。MercadoPago の決済記録と返金、注文ステータス Awaiting MercadoPago payment と MercadoPago payment on hold は常に保持されるため、以前に支払われた注文は再インストール後も返金できます。既存の注文は、決済メモと取引 ID を保持します。

MercadoPago は、その所有者の商標です。本モジュールは MercadoPago と提携しておらず、MercadoPago による承認も受けていません。