VibeFox Midtrans for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

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

通貨: インドネシアルピア（IDR）。Midtrans は IDR でのみ決済を受け付けるため、決済方法はカートの通貨が IDR の場合にのみ表示されます。通貨換算は行いません。ショップに IDR 通貨がない場合は、International > Localization で追加してください。

Midtrans アカウント: Midtrans Dashboard > Settings > Access Keys の Server Key が必要です。サンドボックスのダッシュボードと本番のダッシュボードの両方で取得してください。使用するのは Server Key のみです。Snap Redirect には Client Key は不要です。決済方法そのもの（GoPay、QRIS、仮想口座など）は Midtrans アカウントで有効にします。

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

インストール

1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。

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

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

4. Server Key を入力し、決済通知 URL を Midtrans ダッシュボードにコピーします（設定の項を参照）。

5. Enable/Disable を有効にして Save をクリックします。Sandbox でテストしてから、Environment を Production に切り替えてください。

インストール時に、モジュールは 2 つの注文ステータスを作成します。Awaiting Midtrans payment と Midtrans payment on hold です。PrestaShop は、すべての通貨、国、顧客グループに対する新しい支払いモジュールを提供します。これらは Payment > Preferences で制限できます。モジュールは IDR 通貨で許可された状態を保つ必要があります。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上では、選択した環境の Server Key がない場合（その場合、チェックアウトで決済方法が非表示になります）や、ショップの既定通貨が IDR でない場合に警告が表示され、Sandbox を選択している間は Sandbox mode: payments are simulated, no real money is charged. と表示されます。

Midtrans

Enable/Disable: Enable Midtrans payments で決済方法のオンとオフを切り替えます。既定値：オフ。

Title: チェックアウトで顧客に表示される決済方法のタイトルです。注文に保存される決済方法名にもなります。既定値：Midtrans。必須。

Description: チェックアウトで決済方法の下に表示されるテキストです。既定値：Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more。Sandbox では SANDBOX MODE: no real money is charged. の行が追加されます。

API 認証情報

Midtrans Dashboard > Settings > Access Keys から Server Key をコピーします。このセクションには、本番ダッシュボードとサンドボックスダッシュボードへのリンクがあります。

Environment: 新しい支払いに使用する Midtrans の環境です。切り替えると、選択した環境のキーと API が使われます。支払いは、返金と通知のために、行われた環境を保持します。既定値：Sandbox。

Production Server Key: Mid-server- で始まります。秘密にしてください。

Sandbox Server Key: SB-Mid-server- で始まります。

保存されたキーは再表示されません。フィールドは空のまま Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

Clear saved keys: キーにチェックを入れて Save をクリックすると削除されます。空のフィールドは保存された値を維持します。

決済通知 URL

通知は、支払いが行われたことをショップに知らせます。Notification URL フィールドに、使用する URL が表示されます。フレンドリー URL を有効にしている場合は、https://your-shop/module/wcp_midtrans_payment_gateway/webhook のような形式になり、/en/ のような言語コードが付くこともあります。設定に表示された URL をそのままコピーし、使用しているサンドボックスと本番の各ダッシュボードの Midtrans Dashboard > Settings > Payment > Notification URL に貼り付けてください。URL をブラウザで開くと短い説明が表示されるため、到達可能かどうかを確認できます。Midtrans ダッシュボードの Test notification URL ボタンにも応答します。

各通知には、いずれかの Server Key で作成された有効な署名が含まれている必要があり、キーの環境は支払いの環境と一致しなければなりません。有効な署名のない通知は拒否されます。その場合、ステータスは Midtrans のステータス API から再取得されます。モジュールは次の Midtrans 取引ステータスを処理します：

決済通知 URL がない場合、注文は顧客が支払い後にショップへ戻ったときにのみ作成されます。その後に行われた後払いは、顧客が戻るまで検知されません。

支払い設定

Midtrans は IDR でのみ決済を受け付け、金額は整数のルピアで送信されます。注文明細が丸めた合計と一致しない場合、Rounding adjustment の行が Midtrans に送信されます。

Status after payment: 支払いが確認された後の注文ステータスです。

Payment page expiry (minutes): 顧客が支払いできる期間です（Snap ページ、仮想口座など）。空欄にするか 0 を入力すると、Midtrans の既定値が使われます。分の整数でない値は、保存時にエラーとなって拒否されます。

Order ID prefix: Midtrans に送信される番号の先頭に付加されます。これにより、複数のショップで 1 つの Midtrans アカウントを共有できます。番号はカート ID にタイムスタンプを付けたもので、例えば WC-123-1700000000 のようになります。使用できるのは英字、数字、および - _ . ~ のみで、20 文字までです。それ以外の文字は保存時に削除されます。他のショップの通知は無視されます。既定値：WC-。

詳細設定

Debug log: API 呼び出しと通知を、モジュールフォルダ内の logs/midtrans_p_debug.log.php に書き込みます。このファイルは Web からは開けません。エラーは常に記録されます。キーと顧客データは記録されません。既定値：オフ。

Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。

Delete data on uninstall: オンにすると、モジュールをアンインストールした際にモジュールの設定とログが削除されます。注文、その Midtrans 支払い参照と返金、およびモジュールの注文ステータスは常に残るため、再インストール後も古い注文を返金できます。既定値：オフ。

チェックアウト

支払いステップで、顧客は支払い方法（既定では Midtrans）を選んで確定します。モジュールは、カート合計を整数のルピア単位として Midtrans Snap の取引を作成します。その際、注文明細、配送料、割引、ギフトラッピング、税金、および顧客の請求先・配送先情報が含まれます。その後、顧客を Midtrans の決済ページへ移動させます。そこで顧客は、Midtrans アカウントで有効になっている任意の方法を選べます。この時点では、まだ注文は存在しません。

支払い後、顧客はショップに戻ります。戻りのリンクだけで注文が支払い済みになることはありません。注文は、Midtrans が署名付き通知によって確認した後、または顧客が戻ったときに Midtrans のステータス API へ問い合わせた後にのみ、支払い済みになります。その後、注文が作成され、顧客には使用した決済方法とともに標準の注文確認ページが表示されます。後払いの場合、ページには We are waiting for Midtrans to confirm your payment. If you chose a bank transfer, virtual account or convenience store, please complete the payment using the instructions from Midtrans. You will receive an e-mail once the payment is confirmed. と表示されます。支払いなしで閉じられた注文の場合は Your Midtrans payment was not completed. Please contact us about this order. と表示されます。顧客が戻ったときに Midtrans に接続できない場合、Payment confirmation ページに We are confirming your payment with Midtrans. The order will be updated automatically — please do not pay again. と表示され、Check again ボタンが付きます。

顧客が支払わずに Snap ページを離れた場合、The Midtrans payment was not completed. You can try again below. と表示されてチェックアウトに戻ります。支払いが拒否されたか期限切れの場合、メッセージは Your Midtrans payment was declined or has expired. Please try again or choose another payment method. です。カートは保持されます。顧客が再度支払うと、同じ金額の未使用または保留中の Snap が再利用されます。金額が変わっている場合は、まず保留中の取引が Midtrans で期限切れになります。その間に以前の Snap が支払われていた場合は、注文が作成され、新しい取引は作成されません。注文がすでに存在し、支払いなしで閉じられている場合、メッセージは Your Midtrans payment was declined or has expired. Please place a new order or contact us. です。

Midtrans が支払いを開始できない場合、顧客は短いメッセージとともにチェックアウトに留まります：Could not connect to Midtrans. Please try again in a moment.、Midtrans payments are temporarily unavailable. Please choose another payment method or contact us.（Server Key が誤っている場合など）、または Midtrans が示す理由です。技術的な理由はログに書き込まれます。IDR 以外のカートでは Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method. と表示されます。

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

モジュールは Snap Redirect のみを使用します。Snap ポップアップ、サイト上のカードフォーム、保存済みカードやワンクリック決済、分割払いやプロモーションの設定（決済方法は Midtrans ダッシュボードで設定します）、サブスクリプションには対応していません。カード支払いは即時に確定され、オーソリとキャプチャは分かれていません。

注文と返金

注文ステータス

No order yet: 顧客は Midtrans に移動しましたが、まだ支払っていないか、Midtrans がまだ支払いを確認していません。カートのみが存在します。

Awaiting Midtrans payment: 顧客が後払いの方法（仮想口座、コンビニ決済）を選んだか、完了していないカード支払いを開始しました。Midtrans から支払いが報告されると、注文は支払い済みになります。

Payment accepted、Delivered、または Midtrans payment on hold: 支払いが確認されました。ステータスは Status after payment に従います。支払いは Midtrans の取引 ID とともに記録され、備考には決済方法と Midtrans の注文 ID が表示されます。

Midtrans payment on hold: カード支払いが不正審査中（challenge、まだ支払いは記録されていない）の場合、支払われた金額または通貨が注文と一致しなかった場合（注文は支払い済みとしてマークされない）、またはキャンセルされた注文に支払いが届いた場合（注文は自動的には再開されない）にも設定されます。備考に理由が説明されています。注文を確認し、対応するか支払いを返金してください。

Canceled: 未払いの取引が期限切れになったか、キャンセルされました。未払いの Midtrans 注文を自分でキャンセルすると、保留中の Midtrans 取引（発行済みの仮想口座など）も期限切れになり、もう支払うことはできなくなります。

Payment error: 支払いに失敗したか、審査中のカード支払いが拒否されました。

Refunded: 支払いが全額返金されました。

すでに支払い済みの注文に 2 回目の支払いが届いた場合、注文は変更されません。備考で、Midtrans ダッシュボードで 2 回目の支払いを返金するよう案内されます。返金済みの注文への支払いは、備考を追加するだけです。

Midtrans 支払いブロック

注文ページには Midtrans payment ブロックが表示され、Midtrans の注文 ID、取引 ID（支払いが行われた環境の Midtrans ダッシュボードの取引にリンク）、決済方法、ステータス、支払い済み金額と返金済み金額、サンドボックス支払い用の Sandbox バッジ、返金履歴、注文の Midtrans notes が含まれます。

返金

Midtrans payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Midtrans をクリックします。Refund this amount through Midtrans? This cannot be undone. の確認に応じてください。全額返金と一部返金は整数のルピア単位でサポートされます。小数を含む金額は拒否されます。注文を編集する権限が必要です。注文が後から編集されていても、Midtrans が実際に請求した金額までを返金できます。返金は支払いが行われた環境で送信されるため、その環境の Server Key が設定されている必要があります。Midtrans は一部の決済方法と取引状態に対してのみ API での返金を許可しています（例：決済済みのカード支払い、GoPay、QRIS、ShopeePay の支払い）。Midtrans が返金を受け付けない場合、ブロックにエラーが表示され、返金は記録されません。その場合は Midtrans ダッシュボードで返金してください。返金に成功すると、返金履歴と備考に追加されます。全額返金すると注文は Refunded になります。一部返金ではステータスは変わりません。返金は、Midtrans が支払いの決済完了を報告した後に利用できます。

モジュールはクレジットノートを作成しません。注文ページの PrestaShop 標準の返金ボタンでは、Midtrans を通じた返金は行われません。

Midtrans ダッシュボードで行われた返金は通知によって届き、理由 Refunded in the Midtrans dashboard とともに自動的に返金履歴に追加されます。支払い全額がそこで返金されると、注文は Refunded になります。

ライセンスキー

モジュールは vibefox.net で取得した VibeFox ライセンスキーで動作します。License — VibeFox Midtrans Payment Gateway のライセンスブロックは、Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure ページの最初のブロックで、設定の上にあります。License key にキーを入力し、Activate をクリックしてください。その後、ブロックにはキーがマスク表示され、ステータス（ライセンスの有効期限日やドメインなど）と、ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-payment-midtrans の行と、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 のアカウントで枠を解放してください。

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

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

トラブルシューティング

Midtrans does not appear at checkout: ライセンスが有効であること、Enable/Disable がオンであること、選択した Environment に Server Key が設定されていることを確認してください。カートの通貨が IDR であることも確認します。Payment > Preferences で、モジュールが IDR、顧客の国、顧客のグループに対して許可されているかを確認します。キーがない場合やショップの通貨が IDR でない場合、設定ページに警告が表示されます。

The payment went through, but no order was created: 通知が機能していません。使用している環境（サンドボックスまたは本番）の Midtrans ダッシュボードに決済通知 URL が設定されていること、Notification URL に表示された URL と完全に一致していること、そして到達可能であることを確認してください。ブラウザで開くと短い説明が表示されます。通知を確認するには Debug log をオンにしてください。顧客が支払い後にショップへ戻った場合も注文は作成されます。

Notification answers Invalid signature: 通知が、設定されているサンドボックスまたは本番の Server Key で署名されていません。設定のキーが、通知を送信しているダッシュボードと同じ Midtrans アカウントのものであることを確認してください。

Notification answers Server key not configured: Server Key が設定されていません。設定で入力してください。Midtrans は通知を再試行します。

Notification answers Order not found — ignored: この Midtrans 注文 ID は、このショップが発行したものではありません。例えば、同じ Midtrans アカウントを使う別のショップが発行した場合です。各ショップに異なる Order ID prefix を設定してください。

Notification answers Environment mismatch — ignored: 通知は、支払いが行われた環境とは別の環境のキーで署名されていました。

Notification answers Verification failed, please retry: Midtrans のステータス API に接続できませんでした。Midtrans は通知を再試行します。

Notification answers Busy, please retry: 同じ瞬間に別のリクエストによってカートが更新されていたか、注文を作成できませんでした（例：モジュールが無効になっている）。Midtrans は通知を再試行します。理由はログを確認してください。

The order is Midtrans payment on hold: ブロック内の Midtrans notes を確認してください。カード支払いが不正審査中である、支払われた金額または通貨が注文と一致しない、またはキャンセル後に支払いが届いた、のいずれかです。

The customer sees an error when choosing Midtrans: モジュールページの Log フィールドを確認してください。エラーは常に記録されます。Server Key が誤っている場合は、Midtrans の支払いが一時的に利用できないというメッセージが表示されます。

Refund fails: 決済方法または取引状態では API による返金が許可されていません。Midtrans ダッシュボードで返金してください。返金は自動的に注文に記録されます。メッセージが、注文の支払いが行われた環境の Server Key が設定されていないことを示している場合は、そのキーを入力して再度試してください。

開発者は actionWcpMidtransSnapPayload フックを使って、Midtrans に送信されるデータを変更できます。注文 ID と金額は変更できません。

アンインストール

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

Midtrans は各所有者の商標です。本モジュールは Midtrans と提携しておらず、Midtrans による推奨もありません。