VibeFox PayPal for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。古い PHP バージョンではモジュールのインストールを拒否します。

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

通貨: 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 つのドメインに対応します。

インストール

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

2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox PayPal Gateway を探し、Configure をクリックすることもできます。

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

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

5. 使用するモードの認証情報を入力し、Capture または Authorize を選択して、Enable/Disable をオンにし、Save をクリックします。

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

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

設定

すべての設定はモジュールのページにあります: Modules > Module Manager > VibeFox PayPal Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体を保存します。項目の上部には、支払い方法が有効になっているのに選択中のモードの Client ID または Secret が空の場合や、PayPal がショップの既定の通貨をサポートしていない場合に警告が表示されます。どちらの場合も、支払い方法はチェックアウトで非表示になります。サンドボックスモードがオンの間は、ページに Sandbox mode is on: payments go to the PayPal sandbox, no real money is moved. と表示されます。設定を保存すると、キャッシュされた PayPal アクセストークンが破棄されるため、新しい認証情報がすぐに使用されます。

General

Enable/Disable: Enable PayPal Gateway で支払い方法のオン／オフを切り替えます。既定値: オフ。

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

Description: チェックアウトで支払い方法の下に表示されるテキストです。既定値: Pay with your PayPal account or a card via PayPal.

API 認証情報

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

Sandbox mode: 支払いはサンドボックスの認証情報を使って PayPal サンドボックスに送られ、実際のお金は動きません。既定値: オン。本番の支払いを受け付けるにはオフにします。キャプチャ、取り消し、返金は、注文が支払われた環境を常に使用します。オンの間、購入者には支払い方法の下に 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 です。

保存された Secret は二度と表示されません。項目は空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

Clear saved secrets: Secret にチェックを入れて Save をクリックすると削除されます。空の項目では保存済みの値が維持されます。

支払い

Payment action: 購入者が支払いを承認したときの動作です。既定値: Capture。

詳細設定

Debug log: API リクエストをモジュールフォルダ内の logs/wc_plg_debug.log.php に記録します。このファイルはウェブから開けません。このスイッチがオフでも、エラーと警告は常に記録されます。認証情報、トークン、購入者のデータは記録されません。既定値: オフ。

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

Delete data on uninstall: オンの場合、モジュールをアンインストールするとゲートウェイ設定、キャッシュされたトークン、ログが削除されます。注文の支払いデータ（注文の PayPal ID、返金）と注文ステータスは常に保持されます。既定値: オフ。

チェックアウト

決済ステップで、購入者は支払い方法（既定では PayPal）を選び、支払いフォームの代わりに PayPal ボタンが表示されます。ボタンをクリックすると、サーバーがカートの通貨で、カート合計を金額とする PayPal 注文を作成します。金額は常にサーバーで計算され、ブラウザ上では計算されません。この時点ではまだ注文は存在しません。

購入者は、PayPal のウィンドウで PayPal アカウントまたは PayPal が提供するその他の支払い元を使って支払いを承認します。その後、チェックアウトに PayPal payment approved. Completing your order… と表示され、注文が作成されます。利用規約にまだ同意していない場合は、PayPal payment approved. Click "Place order" to complete it. と表示されます。購入者が支払いを承認せずに Place order をクリックした場合のメッセージは、Please click the PayPal button and approve the payment first. です。

その後、サーバーは PayPal 注文を読み取り、承認済みであること、このカート用に作成されたこと、他のカートで使用されていないこと、金額と通貨がカートと一致することを確認します。その後にのみ、支払いのキャプチャ（または承認）が行われ、注文が作成され、購入者には標準の注文確認ページが表示されます。

承認後にカート合計が変わった場合、何もキャプチャされません。購入者には 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. と表示されます。承認はページを再読み込みしても保持され、Place order で再利用されます。PayPal が前回の試行を完了していた場合は、その支払いが使用され、新たな承認はキャプチャされません。支払いは行われたものの注文を作成できなかった場合、購入者には Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. と表示されます。次の試行では、保存された支払いから注文が作成され、再度請求されることはありません。

PayPal のスクリプトはチェックアウトページでのみ読み込まれ、独自の名前空間を使用するため、ページ上の別の PayPal モジュールと競合しません。本モジュールは Classic と Hummingbird のテーマで動作します。

本モジュールには、PayPal のウェブフック、Pay Later メッセージ、カード入力欄、Venmo、Apple Pay、Google Pay、Fastlane、保存済みの支払い方法やサブスクリプション、商品ページやカートページのボタンはありません。PayPal からの住所ではなく、PrestaShop のチェックアウトで入力された住所が使用されます。

注文と返金

注文ステータス

No order yet: 購入者が支払いを承認していないか、PayPal が支払いを拒否しました。カートのみが存在します。

Payment accepted: キャプチャが完了しました。注文は、PayPal が確認した後にのみ支払い済みとしてマークされます。支払いは PayPal のキャプチャ ID を取引 ID として記録され、メモには金額、PayPal 注文、キャプチャが表示されます。

PayPal payment authorized: 支払いは承認され、キャプチャを待っています（支払い操作 Authorize）。

Awaiting PayPal payment: キャプチャは PayPal で PENDING の状態です。たとえば、支払いの審査中などです。

PayPal payment on hold: 支払われた金額または通貨が注文と一致しないか、PayPal の応答から支払いを読み取れませんでした。メモに理由が記載されます。PayPal が注文の通貨で請求した場合、実際に支払われた金額が支払いとして記録されます。注文を確認して処理するか、支払いを返金してください。

Canceled: Void PayPal authorization により承認が取り消されました。

Payment error: 保留中のキャプチャが拒否されたか、失敗しました。

Refunded: モジュールを通じて支払いが全額返金されました。

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

PayPal 支払いブロック

注文画面には PayPal payment ブロックが表示され、PayPal 注文 ID と intent、キャプチャ ID（PayPal アカウント内の支払いへのリンク。サンドボックスまたは本番）、承認 ID、支払いステータス、金額、支払い済み金額と返金済み金額、サンドボックス支払い用の Sandbox バッジ、返金履歴、注文の PayPal notes が含まれます。ブロックのボタンには注文を編集する権限が必要ですが、モジュールのページへのアクセス権は必要ありません。各操作の結果はブロックに表示されます。

返金

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

承認のみの支払いは返金できません。代わりに Void PayPal authorization を使用してください。本モジュールはクレジットメモを作成しません。注文画面にある PrestaShop 標準の返金ボタンでは、PayPal を通じて返金されません。PayPal アカウント内で行われた返金、紛争、取り消しは PrestaShop と同期されません。

ライセンスキー

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

有効なキーがない場合、チェックアウトに PayPal は表示されません。支払いが開始された場合、ストアは PayPal 注文の作成を拒否し、購入者には An error occurred during PayPal checkout. Please try again. と表示されます。PrestaShop のストアフロントは、バックオフィスにログインしていることを認識しないため、支払い方法はあなたに対しても非表示になります。購入前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブに通知が表示されます。既存の注文には影響しません。返金と PayPal ブロックの操作は引き続き利用できます。

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

トラブルシューティング

PayPal does not appear at checkout: ライセンスが有効であること、Enable/Disable がオンであること、選択中のモードの Client ID と Secret が入力されていること、カートの通貨が PayPal でサポートされていること、カート合計が 0 より大きいことを確認してください。認証情報または通貨が原因の場合は、設定ページに警告が表示されます。Payment > Preferences で、モジュールがカートの通貨、購入者の国、購入者のグループに対して許可されているか確認してください。www.paypal.com をブロックするブラウザ拡張機能があるとボタンも非表示になります。

The payment went through, but no order was created: モジュールにはウェブフックがないため、支払いはチェックアウト中にのみ確認されます。これは、キャプチャ中に PayPal が応答しなかった場合や、注文を作成できなかった場合に発生します。Debug log をオンにして Log 項目を確認するか、PayPal アカウントで支払いを確認するか、購入者に再試行してもらってください。再試行で二重に請求されることはなく、保存された支払いから注文が作成されます。

PayPal could not be loaded: PayPal のスクリプトがブラウザで読み込まれませんでした。たとえば、ブロッカーやネットワークの問題が原因です。

PayPal is not available right now: 認証情報が誤っているか、別のモードのものです。正しいアプリの Client ID と Secret をコピーし直してください。

Your PayPal approval could not be matched to this checkout: たとえばセッションの有効期限が切れた後などに、このカート用の PayPal 注文が作成されていませんでした。購入者は PayPal ボタンを再度クリックします。

This payment is already being processed: 同じカートが同じ瞬間に 2 回送信されました。購入者は少し待ち、メールを確認してから再度試してください。

The order is on hold after payment: PayPal payment ブロックのメモを確認してください。支払いは承認されています（Capture PayPal payment でキャプチャしてください）。または、キャプチャが PayPal で PENDING です（後で Check PayPal payment status を使用してください）。または、支払われた金額か通貨が注文と一致しませんでした（注文を処理するか、支払われた分を返金してください）。

Capture of an authorization fails: 承認が 29 日より前のものか、すでに取り消されている可能性があります。ブロックとメモに PayPal のエラーが表示されます。

Refund fails: 注文に PayPal のキャプチャがない（承認のみ）、金額が返金可能な残額を超えている、または支払いが行われた環境の認証情報がない、のいずれかです。ブロックにどれが該当するかが示されます。

アンインストール

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

PayPal は、その所有者の商標です。本モジュールは PayPal と提携しておらず、PayPal の承認も受けていません。