VibeFox Braintree for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 で動作確認済み）または 4.0.2 以降（4.1.0.3 で動作確認済み）。

PHP: 8.0 以降。

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

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

インストール

このダウンロードは、両方の OpenCart バージョン用パッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。中には README.txt、OpenCart 3 用パッケージ wcp_braintree_gateway-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ wcp_braintree_gateway.ocmod.zip が含まれています。ご利用の OpenCart のバージョンに合ったパッケージだけをインストールしてください。ライセンスキーは両バージョンで同じです。

OpenCart 3

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_braintree_gateway-oc3-(version).ocmod.zip を選択します。この拡張機能には OCMOD の変更がないため、Extensions > Modifications を更新する必要はありません。インストーラーを使う代わりに、このパッケージの upload フォルダーの内容をストアのルートフォルダーにコピーすることもできます。

2. Extensions > Extensions に移動し、タイプ Payments を選択して、VibeFox Braintree Gateway を見つけ、Install（緑色の + ボタン）をクリックします。管理者ユーザーには、決済拡張機能の一覧を変更する権限が必要です。

3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（ライセンスキーのセクションを参照してください）。

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

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

OpenCart 4

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_braintree_gateway.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 はファイル名から拡張機能のコードを取得するため、名前を変更したパッケージは動作しません。

2. インストール済み拡張機能の一覧に、同じページでパッケージが表示されます。その横にある Install（緑色の + ボタン）をクリックします。

3. Extensions > Extensions に移動し、種類として Payments を選択します。VibeFox Braintree Gateway を探して、Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆のボタン）をクリックします。

4. ライセンスキーと Braintree の認証情報を入力し、OpenCart 3 の手順 3〜5 と同じようにして決済をテストします。設定ページとそのフィールドは両バージョンで同じです。

新規インストール時は、決済方法がオフ、サンドボックスモードがオンの状態になります。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox Braintree Gateway > Edit。セクションは左側に一覧表示されます。一覧の下にある Save ボタンで、ページ全体が保存されます。決済方法は有効なのに、選択した環境の Merchant ID、公開キー、または秘密キーが欠けている場合、これらが入力されるまで決済方法はチェックアウトで表示されない旨の警告がページに表示されます。サンドボックスモードがオンの間は、Sandbox mode is on: test payments, no real money. が表示されます。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。

保存時、Title は 1 〜 128 文字、Sort Order は整数、Total は 0 以上の数値である必要があります。いずれかの項目にエラーがある場合は、何も保存されず、ページにその項目が示されます。

Braintree

Enable/Disable: Braintree のカード決済をオンまたはオフにします。選択した環境の Merchant ID、公開キー、秘密キーが入力されるまで、決済方法はチェックアウトで表示されません。既定値：オフ。

Title: チェックアウトで顧客に表示される決済方法の名前です。注文にも決済方法名としてこの名前が保存されます。既定値：Credit / debit card。必須、128 文字まで。

Description: Confirm Order のステップで、カードフォームの上に顧客に表示されるテキストです。既定値：Pay securely with your credit or debit card via Braintree.

Sort Order: チェックアウトの決済方法の中で Braintree が表示される位置です。空欄にするか、整数を入力します。

Geo Zone: 選択した地域の支払い先住所に対してのみ Braintree を提供します。既定値：All zones。ジオゾーンは System > Localisation > Geo Zones で設定します。

Total: Braintree を提供するために注文が到達している必要がある、ストアの既定通貨でのチェックアウト合計金額です。空欄にすると、どの金額でも Braintree を提供します。

API 認証情報

Braintree Control Panel（サンドボックスまたは本番。このセクションからリンクされています）にログインし、歯車アイコンをクリックしてから、API と API Keys を開きます。公開キーと秘密キーがそこに一覧表示され、Merchant ID も同じページに表示されます。このページには、選択した環境の認証情報フィールドのみが表示されます。両方のセットは保存されたままになります。

Sandbox mode: Braintree のサンドボックスを使用します（テスト決済、実際の料金は発生しません）。既定値：オン。オフにすると、本番の認証情報で実際の決済を受け付けます。返金、キャプチャ、取り消しは、常に注文が支払われた環境を使用します。オンの間、購入者は Confirm Order のステップで SANDBOX / TEST MODE — no real money is charged. を確認できます。

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

Sandbox Public Key および Live Public Key: そのアカウントの公開キーです。

Sandbox Private Key および Live Private Key: そのアカウントの秘密キーで、入力したとおりに保存されます。保存済みの秘密キーは再表示されません。フィールドは空欄のままで、Saved — leave empty to keep it. と表示されます。変更する場合のみ、新しい値を入力します。保存済みのキーを削除するには、フィールドの下にある Clear the saved key on save にチェックを入れ、Save をクリックします。

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

決済

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

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

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

注文

OpenCart は Confirm Order のステップで、ステータスなし（欠落した注文）として注文を作成します。Braintree がカード決済を受け付けた後にのみ、ステータスを受け取ります。カードが拒否された場合、注文はステータスなしのままで、購入者は確認ステップにとどまります。以下の各項目には、お使いの OpenCart の注文ステータスが一覧表示されます。

Order Status After Payment: 売上がキャプチャされたか、注文タブで承認がキャプチャされた場合の状態です。既定値：処理中。

Authorized Status: 承認のみ：金額は確保されていますが、まだ支払われていません。既定値：支払い待ち。OpenCart には保留のステータスがないためです。注文メモと注文タブに説明があります。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。

On Hold (Review) Status: Braintree が予期しない取引ステータスを返したか、請求された金額または通貨が一致せず、自動取り消しに失敗した場合の状態です。メモに確認すべき内容が記載されます。既定値：支払い待ち。

Voided Status: 注文タブで承認が取り消され、確保されていた金額が解放された場合の状態です。既定値：キャンセル済み。

Refunded Status: 決済が全額返金されたか、清算前に全額返金として取り消された場合の状態です。一部返金ではメモが追加されるだけです。既定値：返金済み。

詳細設定

Debug log: API の呼び出しと決済の手順も、OpenCart のログフォルダー（storage/logs）にある wc_btg_debug.log.php に記録します。このファイルはウェブから開くことはできません。この設定がオフでも、エラーは常に記録されます。ログには API キー、カード情報、顧客データは一切含まれません。既定値：オフ。

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

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

インポート / エクスポート

Export: Download JSON で、設定を JSON ファイルとして保存します。秘密キーはエクスポートされません。

Import: 以前にエクスポートした JSON を貼り付け、Import をクリックして設定を復元します。保存済みの秘密キーは保持されます。

チェックアウト

Payment Method のステップで、顧客は決済方法を選択します（既定では Credit / debit card）。Confirm Order のステップでは、顧客に、ご自身の説明文と、ストアの言語で Braintree から読み込まれた Braintree のカードフォームが表示されます。OpenCart は、このステップでステータスなしの注文を作成します。顧客が Confirm Order をクリックすると、フォームがカードを確認します。3-D Secure がオンの場合、顧客は発行銀行の認証を完了します。注文合計、メールアドレス、請求先住所がフォームに渡されます。店舗に届くのは 1 回限りのトークンだけです。OpenCart 4 では、顧客は Payment method options ウィンドウで、決済方法ブロックの Choose ボタンを使って決済方法を選択します。その後、カードフォームは、チェックアウトページ下部の確認ブロックに、Confirm Order ボタンの上に表示されます。ストアで支払い先住所を求めない場合（OpenCart 4 の既定）、3-D Secure の確認では代わりに配送先住所が使用されます。

その後、拡張機能は、注文の通貨で注文合計について、Braintree API を通じてトークンに対して請求を行います。Braintree での注文 ID には、OpenCart の注文番号が使用されます。請求された金額と通貨は、注文と照合されます。注文が標準的な OpenCart の方法でステータスを受け取るのは、Braintree が決済を受け付けた後のみで、通常の注文メールが送信され、在庫も更新されます。カートは空になり、顧客には OpenCart の注文完了ページが表示されます。

決済に失敗した場合、注文はステータスなしのままとなり、理由を記載したメモが注文に追加されます。顧客は Confirm Order のステップにとどまり、次のようなメッセージが表示されます：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. が表示されます。

注文が二重に請求されることはありません。決済の処理中に再送信すると、This order is already being paid. Please wait a moment and check your e-mail before trying again. が表示されます。支払い済みの注文をもう一度確定すると、そのまま完了ページに進みます。承認済みの決済の場合は、A payment for this order has already been received and is awaiting review. が表示されます。カードは請求されたが、OpenCart が注文のステータスを設定できなかった場合、顧客には Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. が表示されます。同じカートでの次の試行では、再請求せずに、保存された取引からその注文のステータスを設定します。OpenCart 3 では Confirm Order のステップが表示されるたびに新しい注文が作成されるため、1 つのカートに複数の注文が存在することがあります（OpenCart 4 では、チェックアウトで注文を 1 つ保持して更新するため、カードが拒否された後も、顧客は同じ注文で支払います）。そのうち 1 つが支払い済みになると、同じカートの別の注文は請求されず、顧客には This cart has already been paid with order #…. Please check your order history — do not pay again. が表示されます。

OpenCart 4 では、成功ページが表示されるまで注文はチェックアウト内に保持されます。その間にストアによって注文が閉じられた場合（たとえば、キャンセル、取り消し、返金）、または既に支払い済みで、その後カートの内容（商品や数量）が変わっている場合、Confirm Order により顧客はチェックアウトに戻され、カートの新しい注文が独自の決済とともに作成されます。同じカートを 2 回送信しても、再請求されずに成功ページに進みます。

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

注文と返金

注文ステータス

ステータスなし（欠落した注文）：決済が行われていないか、拒否されました。Sales > Orders では、このような注文は Order Status のフィルターを Missing Orders に設定した場合にのみ表示されます。

Order Status After Payment（既定値 Processing）：カードが請求されたか（Sale）、承認がキャプチャされました。メモには金額、Braintree の取引 ID、3-D Secure の結果が表示されます。

Authorized Status（既定値 Pending）：資金は承認されているだけです（Authorize only）。メモには、発送前に注文ページで決済をキャプチャするよう記載されます。

On Hold (Review) Status（既定値 Pending）：Braintree が予期しない取引ステータスを返したか、誤った通貨または金額の請求を自動で取り消せませんでした。メモには、Braintree Control Panel で確認すべき内容が記載されます。

Voided Status（既定値 Canceled）：承認が取り消されました。

Refunded Status（既定値 Refunded）：拡張機能を通じて、決済が全額返金されました。

メモは、顧客には見えない注文の History のエントリーです。

VibeFox Braintree Gateway タブ

Sales > Orders で、Braintree で支払われた注文を開きます。注文ページの下部、History と Additional の隣に、VibeFox Braintree Gateway タブが表示されます。このタブには、サンドボックス決済の場合に Sandbox ラベルが付いた Transaction ID（その環境の Braintree Control Panel 内の取引へのリンク）、取引の Status、Amount と加盟店アカウント、3-D Secure の結果、Charged / refunded の金額、キャプチャ、取り消し、返金のボタン、返金履歴、注文の Braintree notes が表示されます。このタブは、拡張機能にアクセスできるユーザーに表示されます。ボタンを使うには、拡張機能を変更する権限が必要です（System > Users > User Groups で設定します）。

キャプチャと取り消し

承認済みの決済では、注文合計を請求するには Capture Braintree payment をクリックし、確保されている金額を解放して注文をキャンセルするには Void Braintree authorization をクリックします。キャプチャを行うと注文は Order Status After Payment になり、取り消しを行うと Voided Status になります。操作が失敗した場合、エラーはタブに表示され、注文のメモに追加されます。

返金

VibeFox Braintree Gateway タブで Amount を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて Reason (optional) を入力し、Refund via Braintree をクリックします。確認の質問 Refund this amount through Braintree? This cannot be undone. に応答してください。全額返金と一部返金の両方に対応しており、キャプチャ済みの決済にも、審査中の決済にも使用できます。返金は、Braintree が請求した金額と通貨で行われます。Braintree は清算済みの取引のみを返金できます。通常は 24 時間以内です。清算前の全額返金は取り消しとして処理されます。その場合、一部返金は清算を待つようにというメッセージとともに失敗します。返金は決済の環境（サンドボックスまたは本番）に送信されるため、その環境の認証情報が設定されている必要があります。Braintree が返金を受け付けない場合、タブにはエラーが表示され、返金は記録されません。成功した返金は、返金履歴とメモに追加されます。全額返金では注文が Refunded Status になります。一部返金ではステータスは変わりません。タブからのステータス変更は、購入者に通知されず、商品も在庫に戻されません。手動でステータスを変更した場合と同じです。

Sales > Returns での商品返品では、Braintree を通じて返金は行われません。チャージバック、清算時の拒否、Braintree Control Panel で行われた返金は、OpenCart には同期されません。

ライセンスキー

この拡張機能は、vibefox.net から取得した VibeFox ライセンスキーで動作します。License — VibeFox Braintree Gateway のライセンスブロックは、Extensions > Extensions > Payments > VibeFox Braintree Gateway > Edit の最初のブロックで、設定の上にあります。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（例：ライセンスの有効期限日とドメイン）、そして次のボタンが表示されます：ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key。その下には、Product: opencart-payment-braintree の行と、vibefox.net のアカウントを開くリンク Manage licenses and domains in your account があります。キーを変更できるのは、この拡張機能に対する Modify の権限を持つ管理者ユーザーのみです。ブロックのテキストは管理画面の言語に従います（英語とロシア語が含まれています）。

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

1 つのキーは 1 つのドメインで使用できます。このドメインとは、OpenCart の設定にあるストアのアドレスです。ストアからキーを削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。

有効なキーがない場合、チェックアウトで顧客に Braintree は表示されません。それでも決済が開始された場合、顧客には This payment method is not available. Please choose another one. が表示されます。同じブラウザーで管理画面にログインしている管理者ユーザーには、ストアで決済方法が表示され、(unlicensed — visible to admins only) と表示されます。そのため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 では、このプレビューは利用できません。ストアからは管理画面へのログインが確認できないため、有効なキーがない場合、決済方法はすべてのユーザーに対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文には影響しません。すでに開始された決済は引き続き確認され、キャプチャ、取り消し、返金も機能します。

ライセンスの有効期限が切れた後も、拡張機能は動作し続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスが自動的に再確認されます。キーの入力後最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

Braintree がチェックアウトに表示されない：ライセンスが有効であること、Enable/Disable がオンであること、選択した環境に Merchant ID、公開キー、秘密キーがあることを確認してください。キーが欠けている場合、設定ページに警告が表示されます。また、支払い先住所が選択した Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。

カードは請求されたが、注文にステータスが設定されない：カード決済は、ウェブフックを使わずに即座に確定します。注文のメモと、拡張機能ページの Log の項目を確認してください。メモに Braintree からの応答が失われたと書かれている場合は、別の決済を受け付ける前に、Braintree Control Panel でこの注文番号の取引があるか確認してください。請求後にステータスを設定できなかった場合、同じカートでの次の決済試行は、再請求せずにステータスを設定します。

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

顧客に Your session has expired. Please refresh the page and try again. と表示される：フォームが開いている間に、チェックアウトのセッションが変わりました。顧客はチェックアウトページを再読み込みする必要があります。

すべての決済で 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. と表示される：注文合計が 0 です（たとえばクーポンを適用した後など）。このような注文はカードで支払うことができません。

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

タブにボタンがない、または環境に関するメッセージが表示される：ユーザーグループに拡張機能を変更する権限がないか、決済がサンドボックスまたは本番の環境で行われており、その環境の認証情報が設定されていません。認証情報を入力して、もう一度お試しください。

アンインストール

Extensions > Extensions に移動し、タイプ Payments を選択して、VibeFox Braintree Gateway の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は、拡張機能自体の設定を常に削除します：Enable/Disable、Sort Order、Geo Zone、Total、および Orders セクションの注文ステータス。これらは再インストール時に既定値に戻ります。Delete data on uninstall がオンの場合、その他のゲートウェイ設定（タイトル、説明、サンドボックスモード、認証情報、加盟店アカウント、取引タイプ、3-D Secure、デバッグログ）とログが削除されます。オフの場合は、後で再インストールできるように保持されます。Braintree の取引と返金は常に保持されるため、以前に支払われた注文は、再インストール後も返金、キャプチャ、取り消しができます。既存の注文は、決済に関するメモを保持します。

OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧にある VibeFox Braintree Gateway の横の Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードされたパッケージを削除するには Delete（赤いゴミ箱のボタン）をクリックします。

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