VibeFox Braintree for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

WooCommerce: 8.0 以降がインストールされ、有効になっていること。

PHP: 8.0 以降。

HTTPS: サイトで HTTPS を使用することを推奨します。

Braintree アカウント: Braintree アカウントの Merchant ID、公開キー、秘密キーが必要です。これらは Braintree Control Panel にあります（サンドボックス: sandbox.braintreegateway.com、本番: www.braintreegateway.com）。歯車アイコン、API、API Keys の順に進むと表示されます。サンドボックスと本番のアカウントでは、キーが異なります。3-D Secure を Disabled に設定しない限り、Braintree の加盟店アカウントで 3-D Secure を有効にする必要があります。ウェブフックは不要です。

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

インストール

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

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

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

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

5. Braintree Control Panel から Merchant ID、公開キー、秘密キーを、サンドボックスまたは本番の欄にコピーします。

6. Enable/Disable をオンにします。Sandbox mode をオンのままにし、Braintree のテストカード（例: 4111 1111 1111 1111、有効期限は将来の任意の日付）を使ってテスト注文を行ってください。3-D Secure には、Braintree の 3-D Secure テストカードを使用します。

7. Sandbox mode のチェックを外すと、本番の認証情報を使って実際の決済を受け付けます。

設定

すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > Braintree。ゲートウェイが有効でも、選択したモードの Merchant ID、公開キー、秘密キーのいずれかが欠けている場合、ページには、入力されるまでこの支払い方法がチェックアウトに表示されないという警告が表示されます。ページには選択したモードの認証情報欄のみが表示されます。両方のセットは保存されたままです。

一般

Enable/Disable: Enable Braintree card payments で支払い方法をオンまたはオフにします。既定値はオフです。

Title: チェックアウトで購入者に表示される支払い方法の名前。既定値: Credit / debit card。

Description: チェックアウトでカード入力フォームの上に表示される説明文。既定値: Pay securely with your credit or debit card via Braintree.

API 認証情報

Braintree Control Panel（サンドボックスまたは本番）にログインし、歯車アイコン、API、API Keys の順にクリックします。公開キーと秘密キーがそこに一覧表示され、Merchant ID も同じページに表示されます。

Sandbox mode: Use the Braintree sandbox (test payments, no real money)。既定値はオンです。チェックを外すと、本番の認証情報を使って実際の決済を受け付けます。返金、キャプチャ、取り消しは、常に注文が支払われた環境を使用します。

Sandbox Merchant ID と Live Merchant ID: サンドボックスまたは本番アカウントの Merchant ID。

Sandbox Public Key と Live Public Key: そのアカウントの公開キー。

Sandbox Private Key と Live Private Key: そのアカウントの秘密キー。

Sandbox merchant account ID(s) と Live merchant account ID(s): 任意です。Braintree は加盟店アカウントの通貨で請求します。空欄にすると既定の加盟店アカウントを使用します。ID を 1 つ（例: mystore_EUR）、または通貨ごとに 1 つずつ入力します: EUR=mystore_EUR, USD=mystore_USD。請求通貨が注文通貨と一致しない場合、取引は自動的に取り消され、購入者には請求されません。

支払い

Transaction type: カードの請求方法。

Sale — charge immediately: 注文は直ちに支払い済みになります（既定値）。

Authorize only — capture later: 注文は保留（未払い）になります。注文画面で注文アクションの Capture Braintree payment または Void Braintree authorization を使ってキャプチャまたは取り消しします。承認は、カードによって約 7–30 日で期限切れになります。

3-D Secure: 3-D Secure 2（強力な顧客認証、SCA）は、EEA と英国のほとんどのカード決済で必須です。Braintree アカウントでも有効にする必要があります。

Enabled — verify cards, block failed authentications: 既定値。

Required — only accept payments with liability shift: サーバー側でも Braintree により強制されます。

Disabled: 3-D Secure のチェックは行いません。

詳細設定

Debug log: Also log API calls and payment steps (errors are always logged)。ログは WooCommerce > Status > Logs のソース wcp_braintree_gateway にあります。API キー、カード情報、購入者データは決して含まれません。既定値はオフです。

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted。既定値はオフです。

チェックアウト

購入者は支払い方法（既定では Credit / debit card）を選び、チェックアウトページの Braintree フォームにカード情報を入力します。サンドボックスモードでは、フォームに SANDBOX / TEST MODE — no real money is charged. と表示されます。3-D Secure が有効な場合、購入者は注文の確定時に銀行による認証を完了します。

プラグインは、注文通貨での注文合計額について、1 回限りのトークンを Braintree API 経由で請求し、注文番号を注文 ID として使用します。注文が支払い済みになるのは、請求額と通貨が注文と照合された後、Braintree の認証済みの応答を受けたときだけです。決済が承認されると、購入者は注文受付ページに移動します。カード決済にはウェブフックは不要です。結果はすぐにわかります。

決済が失敗した場合、注文は支払い待ちのままになり、理由が注文メモに追加され、購入者には次のような明確なメッセージが表示されます: Your card was declined. Please use another card or contact your bank.、3-D Secure authentication failed. Please try again or use another card.、または The card security code or billing address could not be verified. Please check your details and try again. 購入者はすぐに再度試せます。請求通貨が注文と一致しない場合、取引は取り消され、購入者には This payment could not be processed in the currency of your order. Your card has not been charged. Please choose another payment method or contact us. と表示されます。

注文が二重に請求されることは決してありません。決済の処理中に 2 回目の送信を行うと、This order is already being paid. Please wait a moment and check your e-mail before trying again. と表示されます。

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

本プラグインはカード決済のみに対応しています。保存済みカード（vaulting）、WooCommerce Subscriptions や予約注文、PayPal、Venmo、Apple Pay、Google Pay、ACH やローカル決済方法、Braintree のウェブフック、Level 2/3 データ、明細項目、Fastlane には対応していません。

注文と返金

注文ステータス

Pending payment: 支払いがまだ行われていないか、拒否されました。

Processing or Completed: カードに請求された（Sale）か、承認がキャプチャされました。WooCommerce は処理中を設定します。仮想のダウンロード可能な商品のみの注文の場合は完了を設定します。注文メモには、金額、取引 ID、3-D Secure の結果が表示されます。取引 ID は Braintree の取引 ID です。注文画面では、Braintree Control Panel の取引へのリンクになります。

On hold: 資金は承認されただけです（Authorize only）。Braintree が予期しない取引ステータスを返した場合、または誤った通貨の請求を自動的に取り消せなかった場合にも、注文は保留になります。注文メモには、Braintree Control Panel で確認すべき内容が書かれています。

Cancelled: 承認が Void Braintree authorization で取り消されました。

キャプチャと取り消し

承認のある注文は、注文を開き、注文アクションで Capture Braintree payment または Void Braintree authorization を選び、更新ボタンをクリックします。キャプチャすると注文は支払い済みになります。取り消しすると注文はキャンセルされ、保留中の金額が購入者に解放されます。操作が失敗した場合、エラーは注文画面に表示され、注文メモに追加されます。

返金

注文を開き、Refund をクリックして金額を入力し、Refund via Credit / debit card をクリックします（ボタンには支払い方法のタイトルが使われます）。全額返金と一部返金に対応しています。Braintree は清算済みの取引のみ返金できます。清算は通常 24 時間以内に行われます。清算前の全額返金は取り消しとして処理されます。その場合、一部返金は清算を待つよう表示されて失敗します。返金は、注文が支払われた環境（サンドボックスまたは本番）に送られます。Braintree が返金を受け付けない場合、WooCommerce にエラーが表示され、返金は記録されません。返金または取り消しが成功すると、注文メモに追加されます。

チャージバック（異議申し立て）と清算時の拒否は WooCommerce に同期されません。Braintree Control Panel で確認してください。

ライセンスキー

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

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

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

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

トラブルシューティング

チェックアウトに Braintree が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、選択したモードに Merchant ID、公開キー、秘密キーがあることを確認してください。キーが欠けている場合、設定ページに警告が表示されます。

支払いは完了したが、注文が Pending payment のまま: カード決済は、ウェブフックなしですぐに確定します。注文メモに Braintree からの応答が失われたと書かれている場合は、この注文番号の取引が Braintree Control Panel にないか確認してから、別の支払いを受け付けてください。Debug log をオンにして、WooCommerce > Status > Logs をソース wcp_braintree_gateway で確認してください。

カードフォームに Could not initialize payment form と表示される: 選択したモードのキーが誤っているか、そのアカウントに加盟店アカウント ID が存在しません。キーと加盟店アカウント ID を確認してから、ページを再読み込みしてください。

すべての決済で 3-D Secure が失敗する: Braintree の加盟店アカウントで 3-D Secure を有効にする必要があります。Braintree サポートに問い合わせるか、3-D Secure を Disabled に設定してください（SCA が必須の EEA と英国では推奨されません）。

購入者に、注文の通貨で決済を処理できなかったと表示される: Braintree は加盟店アカウントの通貨で請求しました。現在のモードの加盟店アカウント欄に、注文通貨用の加盟店アカウント ID を入力してください。

決済の直後に一部返金が失敗する: Braintree は清算済みの取引のみ返金でき、通常は 24 時間以内です。今すぐ取引を取り消すには全額返金するか、清算後に一部返金を行ってください。

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

アンインストール

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

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