VibeFox PayPal for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 でテスト済み）または 4.0.2 以降（4.1.0.3 でテスト済み）。

PHP: 8.0 以降。

PayPal アカウント: PayPal Developer Dashboard で REST API アプリを作成した PayPal Business アカウント。アプリの Client ID と Secret が必要です。サンドボックス用と本番用のアプリでは認証情報が異なります。Webhook は不要です。購入者がチェックアウトにいる間に、拡張機能がサーバー上で各支払いを確認します。

通貨: PayPal が対応する通貨のいずれか: AUD、BRL、CAD、CHF、CNY、CZK、DKK、EUR、GBP、HKD、HUF、ILS、JPY、MXN、MYR、NOK、NZD、PHP、PLN、SEK、SGD、THB、TWD、USD。

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

インストール

ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。内容は README.txt、OpenCart 3 用パッケージ wcp_paypal_gateway-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ wcp_paypal_gateway.ocmod.zip です。お使いの OpenCart バージョンのパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで同じです。

OpenCart 3

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

2. Extensions > Extensions に移動し、種類 Payments を選択します。VibeFox PayPal Gateway を探して、Install（緑色の + ボタン）をクリックします。管理者ユーザーには、支払い拡張機能の一覧を変更する権限が必要です。

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

4. PayPal Developer Dashboard で REST API アプリ（サンドボックスまたは本番、あるいは両方）を作成し、その Client ID と Secret を API credentials セクションにコピーします。

5. Capture または Authorize を選択し、Enable/Disable をオンにして、Save をクリックします。

6. PayPal のサンドボックス購入者アカウントでテストし、Sandbox mode をオフにして本番の認証情報を入力します。

OpenCart 4

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

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

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

4. OpenCart 3 の手順 3 から 6 と同じように、ライセンスキー、PayPal の認証情報、支払いアクションを入力します。設定ページとそのフィールドは両方のバージョンで同じです。この拡張機能は、OpenCart 4 に付属する PayPal 拡張機能には影響しません。両方を同じストアにインストールできます。

新規インストールでは、支払い方法がオフ、サンドボックスモードがオンの状態で始まります。

設定

すべての設定は拡張機能のページにあります: Extensions > Extensions > Payments > VibeFox PayPal Gateway > Edit。セクションは左側に並んでいます。一覧の下にある Save ボタンで、ページ全体を保存します。設定の上部には、支払い方法がオンなのに選択したモードの Client ID または Secret が空の場合、および PayPal がストアの既定通貨に対応していない場合に警告が表示されます。どちらの場合も、チェックアウトでは支払い方法が非表示になります。サンドボックスモードがオンの間は、Sandbox mode is on: payments go to the PayPal sandbox, no real money is moved. と表示されます。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。

保存時、Title は空にできず（128 文字まで）、Sort Order は整数である必要があり（負の数は可）、Total は 0 以上の数値で、注文ステータスは存在している必要があります。いずれかのチェックに失敗した場合、何も保存されず、ページにエラーが一覧表示されます。設定を保存すると、キャッシュされた PayPal のアクセストークンが破棄されるため、新しい認証情報がすぐに使用されます。

一般

Enable/Disable: Enable PayPal Gateway は支払い方法をオンまたはオフにします。既定値: オフ。

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

Description: Confirm Order の段階で、PayPal ボタンの上に購入者に表示されるテキストです。既定値: Pay with your PayPal account or a card via PayPal.

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

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

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

API credentials

PayPal Developer Dashboard で REST API アプリを作成し、その Client ID と Secret をコピーしてください。このセクションには、サンドボックスアプリと本番アプリへのリンクがあります。選択したモードのフィールドのみが表示され、両方のモードの認証情報は保存されたままになります。

Sandbox mode: 支払いはサンドボックスの認証情報を使って PayPal サンドボックスに送られ、実際のお金は動きません。既定値: オン。実際の支払いを受け付けるにはオフにしてください。キャプチャ、取り消し、返金は、注文が支払われた環境を常に使用します。オンの間、購入者は Confirm Order の段階で Sandbox mode: pay with a PayPal sandbox buyer account — no real money is charged. と表示されます。

Sandbox Client ID: サンドボックス用 REST API アプリの Client ID です。

Sandbox Secret: サンドボックス用 REST API アプリの Secret です。

Live Client ID: 本番用 REST API アプリの Client ID です。

Live Secret: 本番用 REST API アプリの Secret です。

保存されたシークレットは二度と表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ新しい値を入力してください。保存されたシークレットを削除するには、フィールドの下にある Clear the saved secret on save をオンにして、Save をクリックします。

支払い

Payment action: 購入者が支払いを承認したときに行われる処理です。既定値: Capture。

注文

OpenCart は Confirm Order の段階で、ステータスのない注文（欠落注文）を作成します。注文は、PayPal がサーバー上でキャプチャまたはオーソリに応答した後にのみステータスを得ます。拒否された支払いでは注文はステータスなしのままになり、購入者は Confirm Order の段階に留まります。以下の各フィールドには、OpenCart の注文ステータスが表示されます。

Order Status After Payment: キャプチャが完了したときの状態です。オーソリがキャプチャされた場合や、注文タブで保留中のキャプチャが完了した場合も含みます。既定値: Processing。

Awaiting Payment Status: キャプチャが PayPal で PENDING の状態です（支払いの審査中、資金はまだ確定していません）。既定値: Pending。

Authorized Status: 支払いアクション Authorize の場合: 資金は確保されていますが、まだ支払われていません。既定値: Pending。

On Hold (Review) Status: PayPal は資金を受け取りましたが、支払いを読み取れなかったか、金額または通貨が注文と一致しません。メモに確認すべき内容が記載されます。既定値: Pending。OpenCart には On hold ステータスがないためです。独自のステータスは System > Localisation > Order Statuses で作成し、ここで選択できます。

Voided Status: 注文タブでオーソリが取り消され、確保されていた資金が解放された状態です。既定値: Canceled。

Refunded Status: 支払いが全額返金された状態です。一部返金はメモを追加するだけです。既定値: Refunded。

Failed Status: 保留中のキャプチャが PayPal によって拒否された状態です。既定値: Failed。

詳細設定

Debug log: API リクエストを、OpenCart のログフォルダ（storage/logs）にある wc_plg_debug.log.php に記録します。このファイルは Web から開くことはできず、5 MB に達すると wc_plg_debug.old.log.php に移動されます。エラーと警告は、このスイッチがオフでも常に記録されます。認証情報、トークン、購入者データは記録されません。既定値: オフ。

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

Delete data on uninstall: オンにすると、拡張機能をアンインストールしたときにゲートウェイの設定とログが削除されます。キャッシュされたトークンは常に削除されます。注文の支払いデータ（注文の PayPal ID、返金）は常に保持されるため、以前に支払われた注文は、再インストール後も返金、キャプチャ、取り消しができます。既定値: オフ。

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

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

Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定が復元されます。保存されているシークレットは保持されます。

チェックアウト

Payment Method の段階で、購入者は支払い方法を選択します（既定では PayPal）。OpenCart は Confirm Order の段階で注文を作成しますが、まだステータスはありません。購入者はそこで、あなたの説明文と PayPal ボタンを目にします。ボタンをクリックすると、サーバー上で、注文通貨による注文合計の PayPal 注文が作成されます。金額は常にサーバーで計算され、ブラウザで計算されることはありません。OpenCart 4 では、購入者は支払い方法のブロックにある Choose ボタンで、Payment method options ウィンドウから支払い方法を選択します。その後、説明文と PayPal ボタンがチェックアウトページ下部の確認ブロックに、Confirm Order ボタンとともに表示されます。

購入者は PayPal のウィンドウで、PayPal アカウントまたは PayPal が提供するその他の決済元を使って支払いを承認します。その後、チェックアウトには PayPal payment approved. Completing your order… と表示され、注文は自動的に完了します。購入者が支払いを承認せずに Confirm Order をクリックした場合のメッセージは、Please click the PayPal button and approve the payment first. です。

その後、サーバーは PayPal 注文を読み取り、承認されていること、このチェックアウトで作成されたこと、別の注文に属していないこと、金額と通貨が注文と一致することを確認します。それから初めて支払いがキャプチャ（またはオーソリ）されます。注文は、PayPal が確認した後にのみ支払い済みとしてマークされます。その後、注文は通常の OpenCart の方法でステータスを得て、通常の注文メールと在庫の更新が行われ、カートは空になり、購入者は OpenCart の注文完了ページを目にします。

承認後に注文合計が変わった場合、何もキャプチャされません。購入者には The order total changed after you approved the payment in PayPal. Please click the PayPal button again to approve the new total. と表示されます。PayPal が支払いを拒否した場合、注文はステータスなしのままになり、購入者は PayPal ボタンを再度クリックするか、別の支払い方法を選ぶよう求められます。購入者が PayPal のウィンドウを閉じた場合、チェックアウトには You cancelled the PayPal payment. と表示されます。

キャプチャ中に PayPal が応答しない場合、購入者には We could not confirm your PayPal payment yet. Please try again in a moment — you will not be charged twice. と表示されます。承認はこのカートのために保持され、ページを再読み込みした後も維持されます。チェックアウトには PayPal payment approved. Click "Confirm Order" to complete it. と表示され、Confirm Order はその承認を再び使用します。PayPal が以前の試行を完了していた場合は、その支払いが使用され、新しい承認はキャプチャされません。支払いは行われたものの注文のステータスを設定できなかった場合、購入者には Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. と表示されます。次の試行では、保存された支払いからステータスを設定し、再度請求することはありません。

OpenCart 3 は Confirm Order の段階が表示されるたびに新しい注文を作成し、OpenCart 4 はチェックアウトの注文を更新するため、支払いはカートに紐づきます。同じカートの以前の注文に対して行われた承認は、合計が同じであれば現在の注文の支払いになります。また、支払い済みのカートが再び請求されることはありません。カートの変更（新しい数量を含む）は、独自の支払いが必要な新しいカートとみなされます。PayPal スクリプトは Confirm Order の段階でのみ PayPal から読み込まれ、独自の名前空間で動作するため、ページ上の別の PayPal 拡張機能と競合しません。

OpenCart 4 では、成功ページが表示されるまで、注文はチェックアウトに保持されます。その注文がその間に閉じられた場合（たとえば取り消した場合や、保留中のキャプチャが拒否された場合）、または以前のカートですでに支払い済みの場合、購入者には Your previous order of this checkout is already closed or paid. Please refresh the page and confirm the order again — a new order will be created. と表示されます。ページを再読み込みすると、次の支払いで新しい注文の支払いが行われます。支払い済みの注文が、別のカートの支払い済みとして表示されることはありません。

この拡張機能には、PayPal の Webhook、Pay Later のメッセージ、カード入力欄、Venmo、Apple Pay、Google Pay、Fastlane、保存された支払い方法やサブスクリプション、商品ページやカートページのボタンはありません。使用されるのは、OpenCart のチェックアウトで入力された住所であり、PayPal から取得された住所ではありません。

注文と返金

注文ステータス

ステータスなし（欠落注文）: 購入者が支払いを承認していないか、PayPal が支払いを拒否しました。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定した場合にのみ表示されます。

支払い後の注文ステータス（既定は Processing）: キャプチャが完了しました。メモには、金額、PayPal 注文、キャプチャが表示されます。

Authorized Status（既定は Pending）: 支払いがオーソリされ、キャプチャを待っている状態です（支払いアクション Authorize）。

Awaiting Payment Status（既定は Pending）: キャプチャが PayPal で PENDING の状態です。たとえば支払いの審査中などです。

On Hold (Review) Status（既定は Pending）: 支払われた金額または通貨が注文と異なるか、PayPal の応答から支払いを読み取れませんでした。メモに理由が記載されます。注文を確認して処理するか、支払いを返金してください。

Voided Status（既定は Canceled）: Void PayPal authorization でオーソリが取り消されました。

Failed Status（既定は Failed）: 保留中のキャプチャが拒否されたか、失敗しました。

Refunded Status（既定は Refunded）: 支払いが拡張機能を通じて全額返金されました。

すでに支払い済みのカートに 2 回目の支払いが届いた場合、支払い済みの注文は変更されません。メモは、PayPal アカウントで確認して返金するよう求めます。

メモは、購入者には表示されない注文の History のエントリです。注文タブで行われたステータスの変更（キャプチャ、取り消し、ステータス確認、返金）は、購入者に通知されず、在庫も変更されずに、直接書き込まれます。

VibeFox PayPal Gateway タブ

Sales > Orders で、PayPal で支払われた注文を開きます。注文ページの下部、History と Additional の横に、VibeFox PayPal Gateway タブが表示されます。このタブには、PayPal order ID と intent（サンドボックスの支払いには Sandbox ラベル付き）、Capture ID（PayPal アカウント内の支払いへのリンク、サンドボックスまたは本番）、Authorization ID、支払いの Status、Amount、Paid / refunded の金額、返金履歴、注文の PayPal notes が表示されます。このタブは、拡張機能にアクセスできるユーザーに表示されます。そのボタンは、拡張機能を変更する権限（System > Users > User Groups で設定）が必要です。各アクションの結果はタブに表示されます。

返金

VibeFox PayPal Gateway タブで金額を入力します（まだ返金されていない金額が自動で入ります）。必要に応じて Reason (optional, sent to the buyer) も入力し、Refund via PayPal をクリックします。Refund this amount through PayPal? This cannot be undone. の確認に応じてください。全額返金と一部返金に対応しています。理由は、購入者へのメモとして PayPal に渡されます。返金は、PayPal が実際に請求した金額と通貨で行われます。そのため、金額または通貨の不一致の後は、注文合計ではなく、購入者が実際に支払った金額までしか返金できません。返金は、支払いが行われた PayPal 環境（サンドボックスまたは本番）に送信されるため、その環境の認証情報が設定されている必要があります。PayPal が返金を受け付けない場合、タブにエラーが表示され、返金は記録されません。返金に成功すると、PayPal の返金 ID とステータスとともに、返金履歴とメモに追加されます。PENDING の返金は、後で PayPal が完了させます。全額返金を行うと、注文は Refunded Status になります。一部返金ではステータスは変わりません。

オーソリのみの支払いは返金できません。代わりに Void PayPal authorization を使用してください。Sales > Returns での商品返品は、PayPal を通じて返金されません。PayPal アカウントで行われた返金、紛争、チャージバックは、OpenCart には同期されません。

ライセンスキー

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

有効なキーがない場合、チェックアウトで PayPal は購入者に表示されません。それでも支払いが開始された場合、ストアは PayPal 注文の作成を拒否し、購入者には An error occurred during PayPal checkout. Please try again. と表示されます。同じブラウザで管理画面にログインしている管理者ユーザーには、支払い方法が (unlicensed — visible to admins only) と表示された状態で引き続きストアに表示されるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 ではこのプレビューは利用できません。ストアは管理者のログインを認識しないため、有効なキーがない場合は支払い方法がすべてのユーザーに対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文には影響しません。返金と注文タブの操作は引き続き機能します。

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

トラブルシューティング

チェックアウトに PayPal が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、選択したモードの Client ID と Secret が入力されていること、注文の通貨が PayPal に対応していること、注文合計が 0 より大きいことを確認してください。認証情報またはストアの通貨が問題の場合は、設定ページに警告が表示されます。また、支払い先住所が選択した Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。

支払いは完了したが、注文がステータスなしのまま: 拡張機能には Webhook がないため、支払いはチェックアウト中にのみ確認されます。これは、キャプチャ中に PayPal が応答しなかった場合や、注文のステータスを設定できなかった場合に起こります。Debug log をオンにして Log フィールドを確認するか、PayPal アカウントで支払いを確認するか、購入者に再試行してもらってください。再試行で二重に請求されることはなく、保存された支払いからステータスが設定されます。

PayPal を読み込めませんでした: ブラウザで PayPal のスクリプトが読み込まれませんでした。たとえば、ブラウザの拡張機能が www.paypal.com をブロックしている場合や、ネットワークの問題がある場合です。

PayPal は現在利用できません: 認証情報が誤っているか、別のモードのものです。正しいアプリの Client ID と Secret をもう一度コピーしてください。

PayPal の承認をこのチェックアウトと照合できませんでした: 例えばセッションの有効期限が切れたあとなど、この チェックアウトで PayPal 注文が作成されていません。購入者は PayPal ボタンを再度クリックしてください。

セッションの有効期限が切れました。ページを更新してから再度お試しください: チェックアウトページが長時間開かれたままでした。購入者はページを再読み込みしてください。

この支払いは処理中です: 同じカートが同じ瞬間に 2 回送信されました。購入者は少し待ち、再試行する前にメールを確認してください。

支払い後に注文が審査中または保留ステータスになっている: VibeFox PayPal Gateway タブのメモを読んでください。支払いがオーソリされている場合は Capture PayPal payment でキャプチャしてください。キャプチャが PayPal で PENDING の場合は、後で Check PayPal payment status を使ってください。支払われた金額または通貨が注文と一致しなかった場合は、注文を処理するか、支払った分を返金してください。

オーソリのキャプチャに失敗する: オーソリが 29 日を超えているか、すでに取り消されている可能性があります。タブとメモに PayPal のエラーが表示されます。

タブにボタンがない: タブに理由が表示されます。あなたのユーザーグループに拡張機能を変更する権限がない、支払いが全額返金されている、または支払いが行われた環境の Client ID と Secret が設定されていない、などです。

返金に失敗する: 注文に PayPal のキャプチャがない（オーソリのみ）、金額が返金可能残高を超えている、または支払いが行われた環境の認証情報がない、などです。どれに該当するかはタブに表示されます。

アンインストール

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

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

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