VibeFox Paysera for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 で検証済み）または 4.0.2 以降（4.1.0.3 で検証済み）。

PHP: 8.0 以降。

Paysera プロジェクト：Paysera プロジェクトのプロジェクト ID とプロジェクトパスワード（署名キー）が必要です。購入者に表示される支払い方法は、このプロジェクトで有効になっているものです。コールバックのために Paysera 側で設定すべきことはありません。コールバックの URL は支払いリクエストごとに送信されます。

到達可能なストア：注文のステータスは Paysera のコールバックから設定されるため、ストアはインターネットからアクセス可能である必要があります。ログインや基本認証、ファイアウォールの背後にあってはいけません。コールバックは、ストアがメンテナンスモードの間も機能します。

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

インストール

このファイルは、OpenCart の両方のバージョン向けのパッケージを含む 1 つの zip ファイルです。お使いのコンピュータで解凍してください。README.txt、OpenCart 3 用パッケージ wcp_paysera_payment-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ wcp_paysera_payment.ocmod.zip が含まれています。お使いの OpenCart のバージョンに対応するパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。

OpenCart 3

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

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

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

4. Paysera アカウントの Project ID と Project password を入力します（設定の項目を参照）。

5. 任意：Paysera プロジェクトで Allow test payments を、本拡張機能で Test payments を有効にすると、料金を請求せずに流れを試せます。販売を始める前に無効にしてください。

6. Enable/Disable を有効にして Save をクリックします。

OpenCart 4

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

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

3. Extensions > Extensions に移動し、種類として Payments を選択します。VibeFox Paysera Payment を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。

4. ライセンスキー、プロジェクト ID とパスワード、テスト設定は、OpenCart 3 の手順 3 〜 6 と同じように入力します。設定ページとそのフィールドは両方のバージョンで同じです。コールバック URL だけが異なります（Paysera プロジェクトの項目を参照）。

新規インストール時は、支払い方法が無効、テスト支払いが無効、環境が Production の状態で始まります。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox Paysera Payment > Edit。セクションは左側に並んでおり、一覧の下にある Save ボタンでページ全体を保存します。設定の上部には、Project ID と Project password のいずれかが未入力の間は Paysera is hidden at checkout until the project ID and the project password are entered. と表示されます。テスト支払いまたはサンドボックスが有効な間は、Test mode is on: customers are not charged. Turn off "Test payments" and select "Production" before accepting real orders. と表示されます。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。

保存時には、Title は 1 〜 128 文字、Project ID は数字のみ、Sort Order は整数、Total は 0 以上の数値であり、注文ステータスが存在している必要があります。いずれかのチェックに失敗した場合は何も保存されず、ページにエラーが表示されます。

Paysera

Enable/Disable：Enable Paysera Payment で支払い方法の有効・無効を切り替えます。既定値：無効。

Title：チェックアウトで購入者に表示される支払い方法の名前です。注文にも、この支払い方法の名前として保存されます。既定値：Paysera。必須、128 文字以内。

Description：Confirm Order の手順で、確認ボタンの上に購入者へ表示されるテキストです。既定値：Pay securely via Paysera。

Sort Order：チェックアウトの支払い方法の中で Paysera が表示される位置です。空欄のままにするか、整数を入力してください。

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

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

Paysera プロジェクト

プロジェクト ID とプロジェクトパスワードは、Paysera アカウントの Projects and activities、対象のプロジェクト、General project settings にあります。このセクションには Paysera アカウントへのリンクがあります。

Callback URL：Paysera が支払いを確認するために使用するアドレスです。OpenCart 3 では https://your-store/index.php?route=extension/payment/wcp_paysera_payment/callback、OpenCart 4 では https://your-store/index.php?route=extension/wcp_paysera_payment/payment/wcp_paysera_payment.callback のような形式で、OpenCart をインストールしたストアのアドレスから作成されます。支払いごとに自動的に送信されるため、Paysera 側で設定する必要はありませんが、インターネットからアクセス可能である必要があります。注文のステータスは、この署名付きまたは暗号化されたコールバックからのみ設定されます。

Project ID：Paysera プロジェクトの数値 ID です。数字のみ受け付けます。それ以外の値を入力すると Project ID must contain digits only: the numeric ID of your Paysera project. というエラーになり、何も保存されません。

Project password：プロジェクトパスワード（署名キー）です。支払いリクエストに署名し、Paysera からのコールバックを検証します。保存されたパスワードは再表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ新しい値を入力してください。保存済みのパスワードを削除するには、フィールドの下にある Clear saved password (tick and save; an empty field keeps the saved value) にチェックを入れ、Save をクリックします。

テスト

Test payments：テストモードで支払いを送信するため、料金は請求されません。Paysera は、購入者に請求せずに成功したテスト支払いを返します。まず Paysera プロジェクトの設定で Allow test payments を有効にしてください。このオプションが有効な間、テスト支払いは注文を支払い済みにします。無効な場合、テスト支払いは注文を On hold にします。既定値：無効。有効な間、購入者は Confirm Order の手順で TEST MODE — no money will be charged. を見ます。

Environment：購入者が移動する先の環境です。通常の Paysera プロジェクトでは、テスト支払いを含めて Production のままにしてください。既定値：Production。

注文

OpenCart は Confirm Order の手順で、ステータスのない注文（欠落注文）を作成します。注文にステータスが付くのは Paysera のコールバックからだけです。キャンセルされた、または実行されなかった支払いでは注文はステータスなしのままとなり、購入者は再度支払うことができます。以下の各フィールドには、お使いの OpenCart の注文ステータスが一覧表示されます。

Order Status After Payment：Paysera が予定どおりの金額と通貨で支払いを確認した後に設定されるステータスです。既定値：Processing。

Awaiting Payment Status：銀行は支払い指示を受け付けましたが、まだ実行していません。Paysera が支払いを確認すると、注文は支払い済みとしてマークされます。既定値：Pending。

On Hold Status：Test payments が無効な間に届いた TEST 支払い、金額や通貨の不一致、または購入者がキャンセルした後の支払いです。注文は支払い済みとしてマークされず、メモに理由が記載されます。既定値：Pending。OpenCart には On hold ステータスがないためです。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。

Cancelled Order Status：本拡張機能はこのステータスを設定せず、読み取るだけです。このステータスの注文に届いた支払いは注文を再度開くことはなく、メモが追加されるだけです。既定値：Canceled。

詳細設定

Debug log：支払いイベントを、OpenCart のログフォルダ（storage/logs）にある wc_psr_debug.log.php に書き込みます。このファイルは Web から開くことはできません。エラーと警告は常に書き込まれ、その他の手順はこのオプションが有効な間だけ書き込まれます。パスワードや購入者データは書き込まれません。既定値：無効。

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

Delete data：有効にすると、拡張機能をアンインストールしたときに、拡張機能の設定とログが削除されます。注文データ（注文、Paysera の支払い記録）は常に保持されます。既定値：無効。

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

Export：Download JSON で、設定を JSON ファイルとして保存します。プロジェクトパスワードはエクスポートされません。

Import：以前にエクスポートした JSON を貼り付け、Import をクリックして設定を復元します。保存済みのプロジェクトパスワードは保持されます。

チェックアウト

Payment Method の手順で、購入者は支払い方法を選択します（既定では Paysera）。Confirm Order の手順では、購入者にあなたの説明文と、You will be redirected to the Paysera payment window (bank links, cards and other Paysera methods) to complete the payment. の案内が表示されます。OpenCart はこの手順で、まだステータスのない注文を作成します。OpenCart 4 では、購入者は Payment method options ウィンドウの支払い方法ブロックにある Choose ボタンで支払い方法を選択し、チェックアウトページの下部にある Confirm Order をクリックします。購入者が Confirm Order をクリックすると、拡張機能は署名付きの支払いリクエストを作成します。このリクエストには、注文番号、注文通貨の最小単位での注文合計、購入者の氏名・メールアドレス・請求先住所、そしてストアページの言語（リトアニア語、ラトビア語、エストニア語、ロシア語、ドイツ語、ポーランド語。それ以外は英語）が含まれます。購入者は Paysera の決済ウィンドウに移動し、そこで銀行、カード、またはその他の方法を選択します。

Paysera は、サーバー間のコールバックによって支払いを確認します。注文が支払い済みとしてマークされるのは、Paysera が署名付きコールバックで確認した後だけです。購入者がストアに戻っても注文が支払い済みになることはありません。その後、注文は OpenCart の標準的な方法でステータスを受け取り、通常の注文メールと在庫の更新が行われます。購入者がコールバックの後に戻ると、OpenCart の注文完了ページが表示されます。銀行が支払い指示を受け付けたものの、まだ実行していない場合、注文には Awaiting Payment Status が付き、ページには Paysera is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. と表示されます。保留中の注文の場合、ページには Your payment is being reviewed. We will contact you if anything else is needed. と表示されます。

購入者がコールバックの前に戻った場合は、Payment confirmation ページが表示されます。このページでは、Paysera が支払いを確認し次第注文が確定することが説明され、Check again と Back to checkout のボタンが表示されます。

購入者が Paysera のウィンドウでキャンセルすると、The Paysera payment was cancelled. You can try again or choose another payment method. というメッセージとともにチェックアウトに戻ります。Paysera が支払いは実行されなかったと報告した場合のメッセージは The payment was not completed. You can try again or choose another payment method. です。どちらの場合もカートは保持されます。OpenCart 4 では、これらのメッセージはチェックアウトページの上部に表示されます。OpenCart 3 は Confirm Order の手順が表示されるたびに新しい注文を作成し、OpenCart 4 はチェックアウトの注文を更新します（新しい試行は同じ注文を支払います）。同じカートの別の注文がすでに支払い済み、支払い待ち、または On hold の場合、新しい試行は二回目の支払いではなく、直接成功ページに進みます。カートの変更（数量の変更を含む）は、独自の支払いが必要な新しいカートとして扱われます。

OpenCart 4 では、成功ページが表示されるまで注文はチェックアウトに保持されます。その間に注文が閉じられた場合（たとえば銀行の支払いを待っていた注文をキャンセルした場合）、購入者は Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order. というメッセージとともにチェックアウトに戻されます。次の Confirm Order では新しい注文が支払われます。その注文が以前のカートですでに支払い済みで、その後カートが変更された場合、購入者はチェックアウトに戻され、次の Confirm Order では現在のカートの新しい注文が支払われます。閉じられた注文が支払い済みとして表示されることはありません。

支払いを開始できない場合、購入者は Confirm Order の手順に留まり、Paysera payments are temporarily unavailable. Please choose another payment method. が表示されます。注文合計が無効な場合は、This order cannot be paid via Paysera. が表示されます。理由はログに記録されます。

コールバックは、ストアがメンテナンスモードの間も機能します。OpenCart が決済拡張機能のリクエストを通過させるためです（OpenCart 4 では、拡張機能がこのための独自の起動アクションを追加しており、これにより購入者が Paysera から戻ることもできます）。

本拡張機能には、管理画面からの返金、チェックアウトページでの銀行や支払い方法の選択、定期購入、保存済みカード、Paysera の配送サービスや宅配サービスはありません。

注文

注文ステータス

ステータスなし（欠落注文）：購入者は Paysera に移動したものの、コールバックがまだ届いていない、購入者がキャンセルした、または支払いが実行されなかったことを示します。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定した場合にのみ表示されます。

Order Status After Payment（既定値 Processing）：Paysera が、一致する金額と通貨で支払いを確認しました。メモにはリクエストと支払い方法が表示され、テスト支払いの場合は (TEST — no money charged) と表示されます。

Awaiting Payment Status（既定値 Pending）：Paysera は支払い指示を受け付けましたが、銀行はまだ実行していません。Paysera が支払いを確認すると、注文は Order Status After Payment に移行します。

On Hold Status（既定値 Pending）：支払いには手動での確認が必要です。支払われた金額または通貨が注文合計と異なる、Test payments が無効な間に TEST 支払いが届いた（料金は請求されていません）、または購入者がキャンセルした後に支払いが確認された、のいずれかです。メモには理由が記載され、注文のタブには、Paysera アカウントで支払いを確認した上で、注文を支払い済みのステータスに設定するか、注文をキャンセルして Paysera で返金するよう示されます。同じ注文に対して後から正しい支払いが届くと、支払い済みとしてマークされます。

Cancelled Order Status（既定値 Canceled）：キャンセルされた注文に対して後から確認された支払いでは、注文のステータスは変わりません。メモには、注文を復元する（支払い済みのステータスに設定する）か、Paysera で支払いを返金するよう記載されます。注文の支払い方法がもう Paysera でない場合、確認された支払いはメモを追加するだけです。

すでに支払い済みの注文、または支払い済みのカートの別の注文に対して、別の成功した支払いが届いた場合、支払い済みの注文は変更されず、Paysera アカウントで重複分を返金するよう求めるメモが追加されます。その他の Paysera ステータス（支払い未実行、追加情報）は、メモを追加するだけです。メモは、購入者には表示されない注文の History のエントリです。

VibeFox Paysera Payment タブ

Sales > Orders で、Paysera で支払われた注文を開きます。注文ページの下部、History と Additional の隣にある VibeFox Paysera Payment タブには、Paysera order ID（注文番号と試行回数）、Paysera request ID、Environment と TEST payment マーク、支払いの Status、Requested / paid の金額、Payment method、そして本拡張機能の Notes が表示されます。On hold の注文の場合は、確認すべき内容が表示されます。このタブは情報を表示するだけで、拡張機能にアクセス権を持つユーザーに表示されます。

返金

管理画面からの返金には対応していません。Paysera の決済ウィンドウのプロトコルには返金 API がないためです。返金は Paysera アカウントで行ってください。Paysera が返金を報告すると、返金額を記載したメモが注文に追加され、注文のステータスは変わりません。必要に応じて、OpenCart で返金を手動で記録してください。Sales > Returns での商品返品では、Paysera を通じて返金は行われません。

ライセンスキー

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

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

トラブルシューティング

チェックアウトに Paysera が表示されない：ライセンスが有効であること、Enable/Disable が有効であること、Project ID と Project password の両方が入力されていることを確認してください。どちらかが未入力の間、設定ページには警告が表示されます。また、支払い先住所が選択した Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。

支払いは完了したが、注文にステータスが付かない：注文のステータスは Paysera のコールバックから設定されるもので、購入者の戻りからではありません。設定に表示されている Callback URL がインターネットからアクセス可能か確認してください（ログイン、基本認証、ファイアウォールの背後にないこと）。また、拡張機能のページにある Log フィールドを確認してください。

コールバックの応答が Invalid signature になる：Project password がプロジェクトと一致していないか、コールバックが Paysera からのものではありません。プロジェクトパスワードを再度コピーしてください。プロジェクトやパスワードを変更した場合、変更前に開始された支払いは検証できなくなります。

コールバックの応答が Project ID mismatch になる：設定の Project ID が、支払いを行ったプロジェクトと異なります。

コールバックの応答が Order not found になる：コールバックの注文には、このストアでの Paysera の支払いがありません。たとえば、同じプロジェクトを使う別のストアで支払いが開始されたことが原因です。

コールバックの応答が Gateway not configured、Busy、または Temporary error になる：プロジェクト ID またはパスワードが空である、同じカートに対する別のコールバックがまだ実行中である、または注文ステータスを設定できなかったことが原因です。Paysera はコールバックを再試行します。原因を確認するには Debug log を有効にしてください。

Paysera が決済ウィンドウを拒否する、またはプロジェクトが存在しないと表示される：Environment を確認してください。通常の Paysera プロジェクトは Production でのみ動作します。Sandbox には、Paysera のサンドボックス環境で作成されたプロジェクトが必要です。

テスト支払いで注文が支払い済みにならない：TEST 支払いは、Test payments が有効な間だけ注文を支払い済みにします。それ以外の場合、注文は料金が請求されなかったというメモとともに On hold になります。また、Paysera プロジェクトで Allow test payments も有効にしてください。

注文が金額または通貨の不一致に関するメモ付きで On hold になっている：Paysera は、金額または通貨が注文合計と異なる支払いを確認しました。Paysera アカウントで支払いを照合し、注文を承認するか、支払いを手動で返金してください。

購入者に Paysera payments are temporarily unavailable と表示される：Log フィールドを確認してください。プロジェクト ID またはパスワードが空である可能性があり、または Paysera に送信されるストアのアドレスのいずれかが 255 文字を超えている可能性があります。

購入者に This payment method is not available. Please reload the checkout page. と表示される：チェックアウトのセッションが注文と一致しなくなったか、その間に支払い方法が無効になりました。購入者はチェックアウトを再読み込みします。

アンインストール

Extensions > Extensions に移動し、種類として Payments を選択して、VibeFox Paysera Payment の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスのステータスは常に削除されます。OpenCart は、拡張機能自体の設定を常に削除します。Enable/Disable、Sort Order、Geo Zone、Total、および Orders セクションの注文ステータスです。これらは再インストール時に既定値に戻ります。拡張機能の OpenCart イベントも削除されます（OpenCart 4 では、そのイベントと、メンテナンスモード中にコールバックと購入者の戻りを通過させる起動アクションも削除されます）。Delete data が有効な場合は、その他の設定（タイトル、説明、プロジェクト ID とパスワード、テスト、ログ）とログが削除されます。無効な場合は、後で再インストールする際のために保持されます。Paysera の支払い記録は常に保持されます。既存の注文は、支払いメモを保持します。

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

Paysera は、それぞれの所有者の商標です。本拡張機能は Paysera と提携しておらず、Paysera による推奨もありません。