VibeFox Midtrans for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

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

PHP: 8.0 以降。

ストア通貨: インドネシアルピア（IDR）。他の通貨の場合、チェックアウトで決済方法は表示されません。通貨換算はありません。

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

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

インストール

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

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

3. ストア通貨をインドネシアルピア（IDR）に設定します。

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

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

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

7. Enable/Disable をオンにします。Sandbox でテストしてから、Environment を Production に切り替えます。

設定

すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > Midtrans。項目の上部には、選択中の環境の Server Key が未入力の場合（その場合チェックアウトで決済方法が非表示になります）と、ストア通貨が IDR 以外の場合に警告が表示されます。Sandbox を選択中は Sandbox mode: payments are simulated, no real money is charged. が表示されます。決済方法の一覧では、Server Key が入力されるまで Midtrans に設定が必要であることが示され、Sandbox では Test mode と表示されます。

全般

Enable/Disable: Enable Midtrans payments で決済方法を有効または無効にします。デフォルト: off。

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。

Sandbox: テスト用。実際の代金は請求されません。

Production: 本番の支払い。

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

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

決済通知 URL

通知は、支払いが行われたことをストアに伝えます。このセクションには使用する URL が表示されます。形式は https://your-site/wc-api/midtrans_p_callback/ のようなものです。使用しているサンドボックスと本番の Midtrans ダッシュボードの Midtrans Dashboard > Settings > Payment > Notification URL に貼り付けてください。ブラウザで URL を開くと短い説明が表示されるので、到達可能かどうかを確認できます。Midtrans ダッシュボードの Test notification URL ボタンにも応答します。

各通知には、いずれかの Server Key で作成された有効な署名が含まれている必要があり、キーの環境が注文の環境と一致している必要があります。有効な署名がない通知は拒否されます。その後、ステータスは Midtrans のステータス API から再取得されます。プラグインは次の Midtrans 取引ステータスを処理します:

settlement, capture (accepted): 支払いが行われました。金額（整数のルピア）と通貨が一致すると、注文は支払い済みになります。

capture (challenge): Midtrans の不正検知によって保留とされたカード決済。Midtrans ダッシュボードで承認または拒否するまで、注文は保留のままです。

pending: 購入者が後払い方法（仮想口座、コンビニ決済）を選び、まだ支払っていません。注文は保留になります。

expire: 未払いの取引の期限が切れました。注文はキャンセルされ、在庫が戻ります。放棄されたカード決済は注文を変更しません。

cancel: 取引がキャンセルされました。注文はキャンセルされます。

deny: 支払いが拒否されました。challenge で保留になっている注文は失敗になります。それ以外の場合は備考が追加され、購入者は再度試すことができます。

failure: 支払いに失敗しました。注文は失敗になります。

refund, partial_refund: Midtrans ダッシュボードで行った返金は、WooCommerce の返金として記録されます。

決済通知 URL が設定されていない場合、購入者が支払い後にストアへ戻った時点でのみ注文が確定します。

支払い設定

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

Status after payment: 支払いが確認された後の注文ステータス。ステータスは 1 つの手順で設定され、購入者へのメールが重複して送られることはありません。

Processing: WooCommerce のデフォルトに従います。ダウンロード可能な仮想商品のみの注文は完了になります（デフォルト）。

Completed: 支払われたすべての注文が完了になります。

On hold: 支払われたすべての注文は、手動での確認を待ちます。

Payment page expiry (minutes): 購入者が支払いできる期間（Snap ページ、仮想口座など）。空白または 0 のままにすると、Midtrans のデフォルトが使われます。

Order ID prefix: Midtrans に送信される注文番号に追加されます。これにより、複数のストアで 1 つの Midtrans アカウントを共有できます。使用できるのは英数字と - _ . ~ のみで、最大 20 文字です。それ以外の文字は保存時に削除されます。他のストアからの通知は無視されます。デフォルト: WC-。

詳細設定

Debug log: Log API calls and notifications を有効にすると、WooCommerce > Status > Logs に、ソース wcp_midtrans_payment_gateway として書き込まれます。エラーは常に記録されます。キーと購入者データが記録されることはありません。デフォルト: off。

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (deactivation keeps everything). Order data is kept. デフォルト: off。

チェックアウト

購入者は決済方法（デフォルトは Midtrans）を選び、注文を確定します。プラグインは、注文金額を整数のルピアとした Midtrans Snap 取引を作成します。注文明細、配送料、税金、購入者の請求先情報と配送先情報も含まれ、購入者は Midtrans の決済ページに移動します。そこで購入者は、Midtrans アカウントで有効になっている任意の方法を選べます。

支払い後、購入者はストアの注文受付ページに戻ります。戻るリンクだけで注文が支払い済みになることはありません。プラグインは Midtrans のステータス API に問い合わせ、Midtrans が確認した場合にのみ注文を支払い済みにします。支払いが確認されるまで、ページには We are waiting for Midtrans to confirm your payment. ... が表示されます。ページには使用された決済方法も表示されます。

支払いが完了していない場合、購入者は The Midtrans payment was not completed. You can try again below. と表示された Pay for order ページに案内されます。支払いが拒否されたか期限切れの場合、メッセージは Your Midtrans payment was declined or has expired. ... になります。購入者が再度支払うと、同じ金額で未使用または保留中の Snap が再利用されます。金額が変わった場合は、保留中の取引が先に Midtrans で期限切れになります。その間に前の Snap が支払われていた場合、注文は確定し、新しい取引は作成されません。

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 からの理由が表示されます。技術的な理由は注文備考に追加されます。

この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce の高性能注文保存機能（HPOS）に対応しています。

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

注文と返金

注文ステータス

Pending payment: 購入者は Midtrans に送られましたが、まだ決済方法を選んでいません。

On hold: 購入者は後払い方法を選び、まだ支払っていないか、カード決済が不正審査（challenge）中か、支払われた金額または通貨が注文と一致しません。キャンセルされた注文に支払いが届いた場合も保留になります。注文は自動的に再開されません。注文備考に理由が記載されます。

Processing, Completed or On hold after payment: 支払いが確認されました。ステータスは Status after payment に従います。注文備考には決済方法と Midtrans の ID が表示されます。取引 ID は Midtrans の取引 ID で、注文画面からは、注文の環境の Midtrans ダッシュボードにある取引へのリンクになります。

Failed: 支払いに失敗したか、challenge 中のカード決済が拒否されました。

Cancelled: 未払いの取引の期限が切れたか、キャンセルされました。在庫は戻ります。WooCommerce で未払いの Midtrans 注文をキャンセルすると（または未払い注文のタイマーでキャンセルされると）、発行済みの仮想口座などの保留中の Midtrans 取引は期限切れになり、支払えなくなります。

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

返金

注文を開き、Refund をクリックして金額を入力し、Refund via Midtrans をクリックします（ボタンには Title が表示されます）。全額返金と一部返金は整数のルピア単位でサポートされ、小数を含む金額は拒否されます。返金は注文が支払われた環境で送信されるため、その環境の Server Key が設定されている必要があります。Midtrans が API による返金を受け付けるのは、一部の決済方法と取引状態のみです（たとえば決済済みのカード決済、GoPay、QRIS、ShopeePay の支払い）。Midtrans が返金を受け付けない場合、WooCommerce はエラーを表示し、返金は記録されません。その場合は Midtrans ダッシュボードで返金してください。返金に成功すると、注文備考に追加されます。

Midtrans ダッシュボードで行った返金は通知によって届き、理由 Refunded in the Midtrans dashboard とともに、WooCommerce の返金として自動的に記録されます。

ライセンスキー

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

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

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

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

トラブルシューティング

チェックアウトに Midtrans が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、選択中の Environment に Server Key があることを確認してください。ストア通貨（または Pay for order ページの注文通貨）が IDR であることを確認してください。設定ページには、これらの問題ごとに警告が表示されます。

支払いは完了したが、注文が Pending payment のまま: 通知が機能していません。使用中の環境（サンドボックスまたは本番）の Midtrans ダッシュボードで決済通知 URL が設定されていて、到達可能であることを確認してください。ブラウザで開くと短い説明が表示されます。Debug log を有効にすると通知を確認できます。購入者が支払い後にストアへ戻った場合も、注文は確定します。

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

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

通知の応答が Order not found — ignored: Midtrans の注文 ID が、このストアの注文ではありません。たとえば、同じ Midtrans アカウントを使う別のストアからのものです。各ストアには異なる Order ID prefix を設定してください。

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

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

注文が On hold: 注文備考を確認してください。購入者が後払いの支払いを完了していないか、カード決済が不正審査中か、支払われた金額または通貨が注文と一致しません。

注文時に購入者にエラーが表示される: 注文備考を開くか、Debug log を有効にして、WooCommerce > Status > Logs でソース wcp_midtrans_payment_gateway を確認してください。IDR 以外の注文では Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method. と表示されます。

返金に失敗する: 決済方法または取引の状態では API による返金ができません。Midtrans ダッシュボードで返金してください。返金は WooCommerce に自動的に記録されます。メッセージに、注文が支払われた環境の Server Key が設定されていないと書かれている場合は、そのキーを入力してからもう一度試してください。

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

アンインストール

プラグインを無効化してもデータはすべて保持されます。削除するには、無効化してから Plugins ページで削除してください。このプラグインのライセンスキーとライセンスステータスは、必ず削除されます。ゲートウェイの設定とログは、Delete data on uninstall がオンだった場合にのみ削除されます。それ以外の場合は、後で再インストールするために残ります。既存の注文は、支払い備考と取引 ID を保持します。

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