VibeFox Barion for OpenCart — ヘルプ

要件

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

PHP: 8.0 以降。

Barion ストア: ストアの POSKey（秘密鍵）と、決済を受け取る Barion ウォレットのメールアドレスが必要です。どちらも Barion ポータルにあります。本番環境は secure.barion.com、テスト環境は secure.test.barion.com で、My stores とご自身のストアから確認できます。テストと本番では認証情報が異なります。

通貨: 注文の通貨は HUF、EUR、USD、CZK のいずれかである必要があります。その他の通貨の場合、チェックアウトで決済方法は表示されません。

アクセス可能なストア: Barion は決済のたびにストアを呼び出すため、サイトはファイアウォールや基本認証を設けず、インターネットから到達できる必要があります。メンテナンスモードでもコールバックはブロックされません。OpenCart 3 は決済拡張機能のリクエストを通過させ、OpenCart 4 では拡張機能がそのためのスタートアップアクションを追加します。

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

インストール

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

OpenCart 3

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

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

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

4. テスト用の POSKey とテストウォレットのメールアドレスを入力し、Test Mode をオンのままにして、Enable/Disable をオンにし、Save をクリックします。テスト注文を行います。

5. すべて正常に動作したら、本番の認証情報を入力し、Test Mode をオフにします。

OpenCart 4

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

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

3. Extensions > Extensions に移動し、タイプ Payments を選択します。VibeFox Barion Gateway を見つけて Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆のボタン）をクリックします。

4. ライセンスキーと Barion の認証情報を入力し、OpenCart 3 の手順 3 〜 5 と同じように決済をテストします。設定ページとそのフィールドは両バージョンで同じです。コールバック URL だけが異なります（コールバック URL を参照してください）。

コールバック URL は、決済のたびに自動的に Barion へ送信されます。Barion ポータルでの設定は不要です。新規インストール時は、決済方法がオフ、テストモードがオンの状態になります。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox Barion Gateway > Edit。セクションは左側に一覧表示されます。一覧の下にある Save ボタンで、ページ全体が保存されます。設定の上には、現在のモードに POSKey または受取人メールアドレスがない場合（その場合、決済方法はチェックアウトで表示されません）、またはストアの既定の通貨が Barion でサポートされていない場合に、警告が表示されます。サポートされている通貨の一覧も表示されます。テストモードがオンの間は、Test mode is on: payments go to the Barion sandbox (api.test.barion.com), no real money is charged. が表示されます。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。

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

Barion

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

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

Description: Confirm Order のステップで、確認ボタンの上に顧客に表示されるテキストです。既定値：Pay securely with Barion — card, Barion Wallet, Apple Pay or Google Pay.

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

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

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

Barion ストアの認証情報

POSKey とウォレットのメールアドレスは Barion ポータルで取得してください：secure.barion.com（本番）または secure.test.barion.com（テスト）、My stores、ご自身のストア（このセクションからポータルへのリンクがあります）。テストモードではテストの認証情報のみ、本番モードでは本番の認証情報のみを使用します。

Test Mode: 下に入力するテスト用の認証情報と Barion サンドボックス（api.test.barion.com）を使用します。実際の料金は請求されません。既定値：オン。実際の決済を受け付けるにはオフにします。オンの間、顧客は Confirm Order のステップで Test mode: no real payment is taken. を確認できます。

Test POSKey: Barion テストシステム（secure.test.barion.com、My stores）におけるストアの秘密鍵（POSKey）です。

Test Payee Email: テスト決済を受け取る Barion テストウォレットのメールアドレスです。

Live POSKey: Barion 本番システム（secure.barion.com、My stores）におけるストアの秘密鍵（POSKey）です。

Live Payee Email: 決済を受け取る Barion ウォレットのメールアドレスです。

保存済みの POSKey は再表示されません。項目は空欄のままで、Saved — leave empty to keep it. と表示されます。変更する場合のみ、新しい値を入力します。保存済みの POSKey を削除するには、項目の下にある Clear the saved POSKey on save にチェックを入れ、Save をクリックします。

Callback URL: 決済のたびに Barion が呼び出すアドレスです。OpenCart 3 では https://your-store/index.php?route=extension/payment/wcp_barion_gateway/callback のような形式、OpenCart 4 では https://your-store/index.php?route=extension/wcp_barion_gateway/payment/wcp_barion_gateway.callback のような形式で、OpenCart インストールのストアアドレスから生成されます。決済のたびに Barion へ送信されるため、設定は不要です。インターネットから到達できればよいです。

注文

OpenCart は Confirm Order のステップで、ステータスなし（欠落した注文）として注文を作成します。Barion が決済を報告した後（コールバックまたは顧客の戻り時）にのみ、ステータスが設定されます。ステータスは常に Barion から読み取られます。以下の各項目には、お使いの OpenCart の注文ステータスが一覧表示されます。

Order Status After Payment: 決済が成功し、検証された後に設定されるステータスです。既定値：処理中。

Awaiting Barion Payment Status: 顧客は Barion のページで手続きを終えましたが、Barion がまだ決済を処理しています。既定値：支払い待ち。

Barion Payment On Hold Status: 決済は完了しましたが、金額または通貨が注文と一致しません。メモに理由が記載されるので、決済を手動で確認してください。既定値：支払い待ち。OpenCart には保留のステータスがないためです。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。

Payment Failed Status: Barion 決済が失敗した、支払い待ちの注文です。既定値：失敗。

Payment Canceled Status: Barion 決済がキャンセルされたか、期限切れになった、支払い待ちの注文です。既定値：キャンセル済み。

Refunded Status: 注文ページから決済が全額返金された後に設定されます。既定値：返金済み。

詳細設定

Logging: Barion のリクエストとコールバックを、OpenCart のログフォルダー（storage/logs）にある barion_p_debug.log.php に書き込みます。このファイルはウェブから開くことはできません。秘密鍵とウォレットのメールアドレスはログに記録されません。既定値：オフ。オフの間は、エラーを含め何も書き込まれません。

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

Delete Data on Uninstall: オンにすると、拡張機能のアンインストール時にゲートウェイの設定とログが削除されます。注文と Barion の決済データは常に保持されます。既定値：オフ。

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

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

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

チェックアウト

Payment Method のステップで、顧客は決済方法を選択します（既定では Barion）。Confirm Order のステップでは、顧客に、ご自身の説明文と You will be redirected to the secure Barion payment page. という注記が表示されます。OpenCart は、このステップでステータスなしの注文を作成します。顧客が Confirm Order をクリックすると、拡張機能は注文の通貨で注文合計金額の Barion 決済を開始し、顧客を Barion の決済ページへ移動させます。商品、配送料、その他の注文手数料、税金が決済に記載されます。OpenCart の注文番号が注文番号として渡され、顧客のメールアドレスがヒントとして渡されます。Barion が対応している場合、ページの言語は顧客の言語に従います（ハンガリー語、ドイツ語、フランス語、スペイン語、チェコ語、スロバキア語、スロベニア語、ギリシャ語。それ以外は英語）。OpenCart 4 では、購入者は支払い方法ブロックの Choose ボタンを使って、Payment method options ウィンドウで支払い方法を選択し、チェックアウトページ下部の Confirm Order をクリックします。

決済後、顧客はストアに戻り、Barion もコールバック URL を呼び出します。これらのリクエストは、それだけでは支払い済みとして扱われません。拡張機能は、決済を開始したモードの POSKey を使って、Barion に決済状態を問い合わせます。注文が支払い済みとしてマークされるのは、Barion が確認し、かつ金額と通貨が注文と一致する場合のみです。戻りリンクには決済試行のランダムなトークンが含まれ、その注文のために開始された決済のみが確認されます。その後、注文は通常の OpenCart の方法でステータスを受け取り、通常の注文メールが送られ、在庫が更新されます。OpenCart 4 では、Barion が購入者を戻すときにブラウザーがストアのセッションを送信しないため、拡張機能はまず短いページを表示し、ストアから同じ戻り先アドレスを開き直します。これにより、購入者はカートとログイン状態を維持できます。

決済が成功すると、顧客には OpenCart の注文完了ページが表示されます。決済が Barion でまだ処理中の場合、注文には Awaiting Barion Payment Status が設定され、成功ページに Your payment is being confirmed by Barion. You will receive an e-mail as soon as it is confirmed. が表示されます。顧客が戻ったときに Barion に接続できない場合、または決済は行われたがまだ反映されていない場合は、同じ文言と Check again ボタンを表示する Payment confirmation ページが表示されます。Barion が決済を確認すると、コールバックが注文ステータスを設定します。

決済が完了しなかった場合（キャンセル、期限切れ、または失敗）、注文はステータスなしのままで、カートは保持され、顧客は Payment was not completed. Please try again. のメッセージとともにチェックアウトに戻ります。戻りリンクが注文と一致しない場合、メッセージは Payment verification failed. です。OpenCart 4 では、これらのメッセージはチェックアウトページの上部に表示されます。新たに試行するたびに、OpenCart 3 では新しい OpenCart 注文が作成されます。OpenCart 4 はチェックアウトの注文を 1 つ保持して更新するため、新しい試行は同じ注文に対する新しい Barion 決済になります。Barion は開始済みの決済をキャンセルできないため、新しい決済の前に、拡張機能はカートの以前の未完了の決済を Barion で確認します。そのいずれかが支払い済みまたは処理中であれば、その注文が確認され、顧客は再度支払うことなく成功ページに移動します。同じカートの別の注文（同じ訪問での同じ商品）がすでに支払い済みの場合も、顧客は新たに支払うことなく成功ページに移動します。完了した購入の後の新しい購入は、新しいカートです。同じ注文の以前の試行の遅延した決済は、引き続きその注文を確認します。期限切れになった以前の試行は、注文をキャンセルしません。顧客が同じカートの 2 件の注文（2 つのタブ）を支払った場合、2 回目の決済ではその注文は確認されません。支払い済みの注文には、同じカートに対する 2 回目の決済を受け取ったことを示すメモが付き、Barion ポータルで返金できます。

OpenCart 4 では、成功ページが表示されるまで注文はチェックアウトに保持されます。その間に決済なしで注文が閉じられた場合（たとえば、Barion で支払い待ちがキャンセルされた場合や、ご自身で注文をキャンセルした場合）、次の Confirm Order で購入者は Payment was not completed. Please try again. とともにチェックアウトに戻され、チェックアウトはカートの新しい注文を作成します。注文にすでにステータスがあり、その後カートが変更されている場合（別の商品や数量）、注文はチェックアウトから外れ、変更されたカートには新しい注文と独自の決済が割り当てられます。

決済を開始できない場合、顧客は Confirm Order のステップに留まり、ボタンの上に短いメッセージが表示されます：The Barion payment could not be started. Please try again or choose another payment method.、Barion does not support payments in 注文の通貨、Barion payment is not available at the moment. Please choose another payment method.、または Barion cannot process an order with a zero total. 詳細は、Logging がオンの場合にログに記録されます。

この拡張機能が扱うのは即時決済のみです。予約決済や遅延キャプチャ決済、サブスクリプションや定期決済、保存済みカード、Barion Pixel、追加の 3-D Secure データには対応していません。3-D Secure は Barion がその決済ページで処理します。

注文と返金

注文ステータス

ステータスなし（欠落した注文）：顧客は Barion に送られましたが、決済をしていないか、決済が完了していないか、Barion がまだ決済を確認していません。Sales > Orders では、このような注文は Order Status のフィルターを Missing Orders に設定した場合にのみ表示されます。

Awaiting Barion Payment Status（既定値 Pending）：Barion は決済がまだ処理中であると報告しています。メモには Barion PaymentId、金額、テストモードの場合は (test mode) が表示されます。Barion が決済を確認すると、注文は支払い済みのステータスに移ります。

Order Status After Payment（既定値 Processing）：Barion が決済を確認しました。メモには金額、PaymentId、Barion の取引が表示されます。

Barion Payment On Hold Status（既定値 Pending）：Barion が注文合計と異なる金額または通貨を報告しました。メモには両方の金額が表示されます。Barion ポータルで決済を確認してから、注文を処理するか、Barion ポータルで決済を返金してください。

Payment Canceled Status（既定値 Canceled）：支払い待ちの注文の最新の決済試行が、Barion でキャンセルされたか、期限切れになりました。

Payment Failed Status（既定値 Failed）：支払い待ちの注文の最新の決済試行が失敗しました。

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

注文がキャンセルまたは失敗した後も注文の決済が成功した場合、注文は支払い済みになります。支払い済みまたは返金済みの注文は、後のコールバックによって変更されることはありません。すでに支払い済みの注文に対して別の決済が成功した場合、メモで Barion ポータルでの確認と、重複であれば返金を求められます。メモは注文の History にあるエントリーで、顧客からは見えません。

VibeFox Barion Gateway タブ

Sales > Orders で、Barion で支払われた注文を開きます。注文ページの下部、History と Additional の隣に、VibeFox Barion Gateway タブが表示されます。このタブには、テスト決済の場合に Test mode ラベルが付いた PaymentId、Barion の Transaction、決済の Status、Paid / refunded の金額、返金フォーム、返金履歴、注文の Barion notes が表示されます。このタブは、拡張機能にアクセスできるユーザーに表示されます。

返金

VibeFox Barion Gateway タブで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて Reason (optional) を入力し、Refund via Barion をクリックします。確認の質問 Refund this amount through Barion? This cannot be undone. に応答してください。全額返金と一部返金に対応しています。拡張機能を変更する権限が必要です（System > Users > User Groups で設定します）。理由はコメントとして Barion に送信されます。HUF の返金は整数の金額である必要があります。返金は決済時のモード（テストまたは本番）で送信されるため、そのモードの POSKey が設定されている必要があります。Barion が返金を受け付けない、または確認しない場合、タブにはエラーが表示され、返金は記録されません。成功した返金は、Barion の取引とステータスとともに、返金履歴とメモに追加されます。全額返金では、顧客に通知せず、また商品を在庫に戻さずに、手動でのステータス変更と同様に注文が Refunded Status に設定されます。一部返金ではステータスは変わりません。

返金は、Barion が決済を確認し、その決済で注文が支払い済みになった後に利用できます。金額または通貨が一致しない決済は OpenCart から返金できません。Barion ポータルで返金してください。Sales > Returns での商品返品では、Barion を通じて返金は行われません。

ライセンスキー

この拡張機能は、vibefox.net から取得した VibeFox ライセンスキーで動作します。License — VibeFox Barion Gateway のライセンスブロックは、Extensions > Extensions > Payments > VibeFox Barion Gateway > Edit の最初のブロックで、設定の上にあります。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（例：ライセンスの有効期限日とドメイン）、そして次のボタンが表示されます：ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key。その下には、Product: opencart-payment-barion の行と、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 のアカウントで解放してください。

有効なキーがない場合、チェックアウトで顧客に Barion は表示されません。それでも決済が開始された場合、顧客には 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 ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

Barion がチェックアウトに表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在のモードに POSKey と受取人メールアドレスがあること（欠けている場合は設定ページに警告が表示されます）、注文の通貨が HUF、EUR、USD、CZK のいずれかであることを確認してください。また、支払い先住所が選択した Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。

決済は完了したのに、注文にステータスが設定されない：注文は、Barion がコールバック URL を呼び出したとき、または顧客がストアに戻ったときにステータスを受け取ります。サイトがインターネットから到達可能であることを確認してください（コールバック URL の前にファイアウォールや基本認証を設けないでください）。決済時のモードの POSKey が正しいことを確認してください。拡張機能はそれを使って Barion に決済状態を問い合わせます。コールバックを確認するには、Logging をオンにしてください。

コールバックが Busy, retry を返す：顧客の戻りと同時に注文が処理されていたか、注文ステータスを設定できませんでした。Barion は再度呼び出します。理由を確認するには、Logging をオンにしてください。

コールバックが API error を返す：ストアが Barion から決済状態を読み取れなかったか、決済時のモードの POSKey が設定されていません。その POSKey を確認してください。

コールバックが Order not found を返す：この PaymentId はこのストアで開始されたものではありません。他のストアやテストシステム向けの Barion の呼び出しは無視されます。

顧客に Payment verification failed. が表示される：戻りリンクが注文と一致しません。たとえば、編集された可能性があります。決済状態はコールバックによって引き続き確認されます。

顧客が Confirm Order の後にエラーを見る：Logging をオンにし、拡張機能のページにある Log の項目を確認してください。POSKey または受取人メールアドレスが誤っていると、The Barion payment could not be started. が表示されます。This payment method is not available. Please reload the checkout page. は、チェックアウトのセッションが注文と一致しなくなったこと、またはその間に決済方法がオフにされたことを意味します。顧客はチェックアウトを再読み込みする必要があります。

注文が保留ステータスになっている：VibeFox Barion Gateway タブの不一致メモを確認し、Barion ポータルで決済を確認してから、注文を処理するか、Barion ポータルで返金してください。

10.50 HUF を返金できない理由：Barion は HUF を小数点なしで処理します。整数の金額を入力してください。

タブに返金フォームがない：タブに理由が表示されます。決済がまだ確認されていない、全額返金されている、ユーザーグループに拡張機能を変更する権限がない、または決済のモードの POSKey が設定されていない、のいずれかです。

開発者向け：この拡張機能は OpenCart のイベント wcp_barion_supported_currencies（通貨の一覧）と wcp_barion_payment_request（決済リクエストと注文。Barion に送信される前）をトリガーします。

アンインストール

Extensions > Extensions に移動し、タイプ Payments を選択して、VibeFox Barion Gateway の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は、拡張機能自体の設定を常に削除します：Enable/Disable、Sort Order、Geo Zone、Total、および Orders セクションの注文ステータス。これらは再インストール時に既定値に戻ります。拡張機能の OpenCart イベントも削除されます（OpenCart 4 では、そのイベントに加えて、メンテナンスモードでもコールバックを通すスタートアップアクションも削除されます）。Delete Data on Uninstall がオンの場合、その他のゲートウェイ設定（タイトル、説明、テストモード、POSKey、受取人メールアドレス、ログ記録）とログが削除されます。オフの場合は、後で再インストールできるように保持されます。Barion の決済と返金の記録は常に保持されるため、以前に支払われた注文は、再インストール後も返金できます。既存の注文は、決済に関するメモを保持します。

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

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