VibeFox Braintree for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。モジュールは、それより古い PHP バージョンではインストールされません。

Braintree アカウント: Braintree アカウントの Merchant ID、Public Key、Private Key が必要です。これらは Braintree Control Panel（サンドボックス: sandbox.braintreegateway.com、本番: www.braintreegateway.com）の歯車アイコン、API、API Keys の下にあります。サンドボックスと本番のアカウントでは、キーが異なります。3-D Secure を Disabled に設定しない限り、Braintree の加盟店アカウントで 3-D Secure を有効にしておく必要があります。Webhook は不要です。カード決済は直ちに確認されます。

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

インストール

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

2. アップロードが完了したら、Configure をクリックします。後から行う場合は、モジュール一覧で VibeFox Braintree Gateway を探し、Configure をクリックします。

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

4. Braintree Control Panel から Merchant ID、Public Key、Private Key をコピーし、サンドボックスまたは本番の各フィールドに貼り付けます。

5. Enable/Disable をオンにして Save をクリックします。Sandbox mode はオンのままにして、Braintree サンドボックスのテストカードでテスト注文を行います。その後、Sandbox mode をオフにすると、本番の認証情報で実際の決済を受け付けられます。

インストール時に、モジュールは 2 つの注文ステータス Braintree payment authorized と Braintree payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい支払いモジュールを提供します。Payment > Preferences で制限できます。

設定

すべての設定はモジュールのページにあります: Modules > Module Manager > VibeFox Braintree Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。支払い方法が有効になっていても、選択した環境の Merchant ID、Public Key、Private Key が未入力の場合、それらが入力されるまで支払い方法はチェックアウトに表示されないという警告がページに表示されます。サンドボックスモードがオンの間は、ページに Sandbox mode is on: test payments, no real money. と表示されます。

Braintree

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

Title: チェックアウトで購入者に表示される支払い方法の名前です。注文にも、この支払い方法名が保存されます。デフォルト: Credit / debit card。必須。

Description: チェックアウトで支払い方法の下に表示されるテキストです。デフォルト: Pay securely with your credit or debit card via Braintree.

API 認証情報

Braintree Control Panel（サンドボックスまたは本番）にログインし、歯車アイコンをクリックしてから、API と API Keys をクリックします。ここに Public Key と Private Key が表示され、Merchant ID も同じページに表示されます。このページには、選択した環境の認証情報フィールドのみが表示されます。両方のセットは保存されたままです。

Sandbox mode: Braintree のサンドボックスを使用します（テスト決済、実際の金額は請求されません）。デフォルト: on。オフにすると、本番の認証情報で実際の決済を受け付けます。返金、キャプチャ、取り消しは、注文が支払われた環境を常に使用します。オンの間、購入者には支払い方法の下に SANDBOX / TEST MODE — no real money is charged. と表示されます。

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

Sandbox Public Key と Live Public Key: そのアカウントの Public Key です。

Sandbox Private Key と Live Private Key: そのアカウントの Private Key です。保存済みの Private Key が再表示されることはありません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ、新しい値を入力してください。

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

Clear saved private keys: Sandbox Private Key または Live Private Key にチェックを入れ、Save をクリックすると削除されます。フィールドが空の場合は、保存されている値が保持されます。

支払い

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

3-D Secure: EEA と英国では、ほとんどのカード決済で 3-D Secure 2（強力な顧客認証）が必須です。Braintree アカウントでも有効にしておく必要があります（3-D Secure の設定エラーで決済に失敗する場合は、Braintree のサポートにお問い合わせください）。

3-D Secure の結果は、カードに請求される前に、ブラウザだけでなくサーバー側でも確認されます。

詳細設定

Debug log: API 呼び出しと決済の各ステップも、モジュールフォルダ内の logs/wc_btg_debug.log.php に記録します。このファイルはウェブから開くことはできません。この設定がオフでも、エラーは常に記録されます。ログには API キー、カード情報、購入者データは一切含まれません。デフォルト: off。

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

Delete data on uninstall: オンにすると、モジュールのアンインストール時にゲートウェイの設定とログが削除されます。Braintree の取引、返金、注文ステータスは常に残るため、再インストール後も、以前に支払われた注文を返金、キャプチャ、取り消しできます。デフォルト: off。

チェックアウト

支払いの段階で、購入者は支払い方法（デフォルトは Credit / debit card）を選び、支払いオプション内の Braintree フォームにカード情報を入力します。このフォームは、チェックアウトページでのみ Braintree から読み込まれ、ショップの言語が使用されます。3-D Secure がオンの場合、購入者は注文を確定する際に銀行による認証を完了します。カートの合計額、メールアドレス、請求先住所がこの認証に渡されます。

その後、モジュールは Braintree API を通じて、カートの通貨でカート合計額を 1 回限りのトークンに対して請求します。Braintree 上の注文 ID にはカート番号が使用されます。この時点までは注文は存在しません。請求された金額と通貨はカートと照合されます。注文は Braintree が決済を承認した後にのみ作成され、購入者には PrestaShop の標準の注文確認ページが表示されます。

決済に失敗した場合は、注文は作成されず、理由がモジュールのログに記録されます。購入者は支払いの段階に留まり、たとえば次のようなメッセージが表示されます: 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. と表示されます。カードには請求されたものの、PrestaShop が注文を完了できなかった場合、購入者には Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. と表示されます。同じカートでの次の試行では、再び請求することなく、保存済みの取引から注文が作成されます。

本モジュールはカード決済のみに対応しています。保存済みカード、サブスクリプションや定期払い、PayPal、Venmo、Apple Pay、Google Pay、ローカル決済には対応しておらず、Braintree のウェブフックも使用しません。

注文と返金

注文ステータス

まだ注文はありません: 支払いが行われなかったか、拒否されました。カートだけが存在します。

Payment accepted: カードに請求されたか（Sale）、承認がキャプチャされました。決済は Braintree の取引 ID とともに記録され、注文のメッセージ内の非公開メモに、金額、取引 ID、3-D Secure の結果が表示されます。

Braintree payment authorized: 資金は承認されただけです（Authorize only）。キャプチャするまで、決済は記録されません。

Braintree payment on hold: Braintree が予期しない取引ステータスを返したか、通貨や金額が誤った請求を自動的に取り消せませんでした。メモには、Braintree Control Panel で確認すべき内容が記載されています。

Canceled: 承認が取り消されました。

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

すでに作成済みの注文に別の取引が届いても、注文は変更されません。メモには、Braintree Control Panel で確認し、取り消すか返金するよう示されます。

Braintree payment ブロック

注文画面には Braintree payment ブロックが表示され、取引 ID（その環境の Braintree Control Panel 内の取引にリンク）、取引ステータス、金額と加盟店アカウント、3-D Secure の結果、請求額と返金額、サンドボックス決済の Sandbox バッジ、返金履歴が表示されます。ブロック内のボタンには注文を編集する権限が必要です。Modules ページへのアクセス権は必要ありません。

キャプチャと取り消し

ステータスが Braintree payment authorized の注文では、Capture Braintree payment をクリックすると注文総額が請求され、Void Braintree authorization をクリックすると保留中の金額が解放されます。キャプチャを行うと注文は Payment accepted になり、決済が記録されます。取り消しを行うと注文は Canceled になります。操作に失敗した場合は、エラーがブロック内に表示され、注文のメモにも追加されます。

返金

Braintree payment ブロックで金額を入力します（まだ返金されていない金額が自動的に入ります）。任意で理由を入力し、Refund via Braintree をクリックします。確認メッセージ Refund this amount through Braintree? This cannot be undone. で承認してください。全額返金と一部返金に対応しています。返金は Braintree が請求した金額と通貨で行われるため、金額または通貨に不一致があった場合は、購入者が実際に支払った額までを上限として返金できます。Braintree が返金に対応するのは清算済みの取引のみで、通常は 24 時間以内です。清算前の全額返金は取り消しとして処理されます。その場合、一部返金は清算を待つようにというメッセージとともに失敗します。返金は決済が行われた環境（サンドボックスまたは本番）に送信されるため、その環境の認証情報を設定しておく必要があります。Braintree が返金を受け付けなかった場合、ブロックにエラーが表示され、返金は記録されません。返金に成功すると、返金履歴とメモに追加されます。全額返金を行うと注文は Refunded になります。一部返金では、ステータスは変わりません。

このモジュールはクレジットスリップ（返金伝票）を作成しません。注文画面の PrestaShop 標準の返金ボタンでは、Braintree を通じて返金されません。チャージバック、清算時の拒否、Braintree Control Panel で行われた返金は、PrestaShop に同期されません。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Braintree が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、選択した環境に Merchant ID、Public Key、Private Key があることを確認してください。キーが不足している場合、設定ページに警告が表示されます。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループに対してモジュールが許可されているかを確認してください。

カードには請求されたが、注文が作成されていない: カード決済は Webhook を使わずに直ちに確認されます。モジュールページの Log フィールドを確認してください。ログに Braintree からの応答が失われたと記載されている場合は、別の決済を受け付ける前に、Braintree Control Panel で注文 ID としてカート番号を持つ取引が存在するかを確認してください。請求後に注文を作成できなかった場合は、同じカートに対する次の決済試行で、再び請求することなく注文が作成されます。

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

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

購入者に、注文の通貨では決済を処理できなかったと通知される: Braintree は加盟店アカウントの通貨で請求しました。現在の環境の加盟店アカウントのフィールドに、カートの通貨に対応する加盟店アカウント ID を入力してください。

購入者に The order total must be greater than zero to pay by card と表示される: クーポンを適用した後などで、カートの合計額がゼロになっています。このような注文はカードで支払うことができません。

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

返金、キャプチャ、取り消しが、環境に関するメッセージとともに失敗する: 決済はサンドボックスまたは本番環境で行われましたが、その環境の認証情報が設定されていません。認証情報を入力してから、もう一度お試しください。

アンインストール

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

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