VibeFox Pin Payments for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 ～ 9.x。
PHP: 8.0 以降。古いバージョンの PHP ではモジュールのインストールを拒否します。
Pin Payments アカウント: Pin Payments の加盟店アカウント（オーストラリアまたはニュージーランドの企業向け。購入者はどこからでも支払うことができます）。本番用の公開キーと秘密キーに加え、テスト用には、テスト環境の公開キーと秘密キーが必要です。Webhook のシークレットは不要です。モジュールは Webhook を使用しません。カード情報は購入者のブラウザから Pin.js によって直接 Pin Payments に送信され、ショップには届かないため、ショップは PCI SAQ A-EP の対象となります。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. 管理画面で Modules > Module Manager に移動し、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックするか、後でモジュール一覧から VibeFox Pin Payments Gateway を見つけて Configure をクリックします。
3. Configure ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを入力し、Activate をクリックします（ライセンスキーを参照）。
4. Pin Payments のダッシュボードで Account > API Keys を開き、テスト用キーを Test publishable key と Test secret key にコピーします。Test mode をオンのままにし、Enable/Disable をオンにして、Save をクリックします。
5. Pin Payments のテストカードでテスト注文をしてください。すべて正常に動作したら、本番用キーを入力し、Test mode をオフにして保存します。
インストール時にモジュールは注文ステータス Pin Payments payment on hold を作成します。PrestaShop は、インストール時点で有効な通貨、顧客グループ、国に対して新しい決済モジュールを提供します。これは Payment > Preferences で変更できます。後から有効にした国は、そこでチェックを入れる必要があります。
設定
すべての設定はモジュールのページにあります: Modules > Module Manager > VibeFox Pin Payments Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上には、テストモードがオンの間は警告、現在のモードの公開キーまたは秘密キーが空の場合はエラー、Pin Payments がショップの既定通貨をサポートしていない場合はエラー（サポートされている通貨の一覧付き）が表示されます。現在のモードの両方のキーがない場合、支払い方法はチェックアウトで非表示になります。Title が空の場合は保存されません。ページには Enter a title for the payment method. と表示されます。
Pin Payments
Enable/Disable: Enable Pin Payments で支払い方法のオン/オフを切り替えます。デフォルト: オフ。
Title: チェックアウトで購入者に表示される支払い方法の名前です。注文にも支払い方法の名前として保存されます。デフォルト: Credit card (Pin Payments)。必須。
Description: チェックアウトで支払い方法の下に表示されるテキストです。デフォルト: Pay with your credit card via Pin Payments.
API キー
キーは Pin Payments のダッシュボードの Account > API Keys にあります。テスト用キーはテスト API でのみ、本番用キーは本番 API でのみ動作します。公開キーは購入者のブラウザで Pin.js が使用します。秘密キーがサーバーの外に出ることはありません。
Test mode: Pin Payments のテスト環境（test-api.pinpayments.com）とテスト用キーを使用します。実際の請求は行われず、購入者には支払い方法の下に TEST MODE — no real charges will be made. と表示されます。オフの場合は、本番 API と本番用キーが使用されます。デフォルト: オン。
Test publishable key: Pin Payments テストアカウントの公開キーです。
Test secret key: Pin Payments テストアカウントの秘密キーです。
Live publishable key: Pin Payments 本番アカウントの公開キーです。
Live secret key: Pin Payments 本番アカウントの秘密キーです。
キーの前後の空白は削除されます。保存済みの秘密キーは再び表示されません。フィールドは空のままになり、Saved — leave empty to keep it. と表示されます。値を変更する場合にのみ新しい値を入力してください。
Clear saved secrets: 秘密キーにチェックを入れて Save をクリックすると削除されます。フィールドが空の場合は、保存済みの値が維持されます。
詳細設定
Debug log: モジュールフォルダー内の logs/wc_ppg_debug.log.php に書き込みます。このファイルは Web から開くことはできません。エラーは常に記録されます。すべての API 呼び出しも記録する場合はオンにしてください。カード情報、API キー、購入者の個人データは記録されません。デフォルト: オフ。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックするとログが空になります。
Delete data on uninstall: オンの場合、モジュールをアンインストールするとゲートウェイの設定とログが削除されます。注文の支払いデータ（請求と返金）と注文ステータス Pin Payments payment on hold は常に保持されます。デフォルト: オフ。
チェックアウト
支払い方法は、有効になっている場合、現在のモードの両方のキーが設定されている場合、カートの通貨が 14 のサポート対象通貨（AUD、USD、NZD、SGD、EUR、GBP、CAD、HKD、JPY、MYR、THB、PHP、ZAR、IDR）のいずれかである場合、そして Payment > Preferences でそのカートにモジュールが許可されている場合に表示されます。
支払いステップで、購入者は支払い方法を選択し（デフォルトは Credit card (Pin Payments)、Visa、Mastercard、American Express のアイコン付き）、Card number、Expiry (MM / YY)、CVC、Name on card に入力します。送信前に、フォームはカード番号の桁数、有効期限の月と年、3 桁または 4 桁の CVC、および名義を確認します。
購入者が注文を確定すると、Pin.js はカード情報とカートの請求先住所をブラウザから Pin Payments に直接送信し、1 回限りのカードトークンを受け取ります。ショップに送信されるのはこのトークンだけです。次に、モジュールはカートの通貨で、カートの合計金額に対するキャプチャ済みの請求を作成します。購入者のメールアドレスと説明 <shop name> - Cart <cart number> が付きます。Pin Payments は同じリクエストで応答します。この応答の前には注文は存在しません。
請求が成功すると注文が作成され、購入者には標準の注文確認ページが表示されます。Your card payment has been received. 注文が Pin Payments payment on hold になった場合、ページには Your card payment has been received and is being reviewed. We will update your order as soon as the review is complete. と表示されます。
Pin Payments が応答しない場合（タイムアウト、サーバーエラー、読み取れない応答）、それでも請求が作成されている可能性があります。その場合、注文は支払いなしで Pin Payments payment on hold として作成され、確認ページには We could not confirm your payment with Pin Payments. Please check your e-mail and card statement before paying again, or contact us. と表示されます。同じカートを再度送信しても、2 回目の請求が作成されることはありません。
カートごとに同時に実行される支払い試行は 1 件だけです。2 回目の送信には This order is already being paid. Please wait a moment and check your e-mail before trying again. と表示されます。すでに注文があるカート、または金額を請求した（または請求した可能性がある）以前の試行は再請求されず、代わりにその試行から注文が作成されます。カードトークンは 1 回しか使用できません。試行が失敗した後、または購入者がカード情報を変更した場合は、新しいトークンが作成されます。
支払いが失敗した場合、注文は作成されません。購入者は支払いステップにとどまり、カートは保持され、次のいずれかのメッセージが表示されます。Your card was declined. Please use another card or contact your bank.、Your card has insufficient funds. Please use another card.、Your card has expired. Please use another card.、The card security code (CVC) is incorrect.、This card type is not accepted. Please use Visa, Mastercard or American Express.、Payment failed: 拒否された情報について Pin Payments が示した理由付き、Your card details have expired. Please enter them again and retry.（トークンを使用できない場合）、The secure card form could not be loaded. Please reload the page or choose another payment method.（Pin.js が読み込まれない場合）、Card payments are temporarily unavailable. Please try again later or choose another payment method.（Pin Payments が秘密キーを拒否した場合）、Your payment could not be processed. Please try again or choose another payment method.（その他のエラーの場合）。技術的な理由はログに記録されます。
モジュールには 3-D Secure の処理フローはありません。Pin Payments アカウントで 3-D Secure が必須の場合、請求は保留のままになり、注文は作成されず、購入者には Your card payment could not be completed (additional verification is required). Please try another card or another payment method. と表示されます。後からキャプチャする承認のみのモード、保存済みカード、定期購読、Apple Pay、Google Pay はなく、ウェブフックもありません。
注文と返金
注文ステータス
No order yet: カードが拒否された、請求に 3-D Secure が必要だった、または購入者が支払っていない場合です。カートのみが存在します。
Payment accepted: Pin Payments が、カートの金額と通貨にぴったり一致する、成功してキャプチャ済みの請求を報告しました。支払いは Pin Payments の請求トークンをトランザクション ID として記録され、備考には金額と請求トークンが表示されます（テスト支払いの場合は TEST MODE も表示されます）。
Pin Payments payment on hold: 請求には確認が必要です。備考には理由が記載されます。Pin Payments がカートと異なる金額または通貨を請求した（請求された金額の支払いが記録されます）、支払い中にカートが変更された、請求は承認済みだがキャプチャされていない（Pin Payments のダッシュボードでキャプチャしたうえで、注文を支払い受付に設定してください）、または Pin Payments から明確な応答がなかった（支払いは記録されません。注文を発送する前に、Pin Payments のダッシュボードで請求の説明を検索してください）。
Refunded: 請求は、モジュールを通じて全額返金されました。
すでに注文があるカートに対して 2 回目の請求が行われた場合、注文は変更されません。備考で確認し、Pin Payments のダッシュボードから返金するよう求められます。
Pin Payments ブロック
注文ページには Pin Payments ブロックが表示されます。テスト支払いには Test mode バッジが付き、請求トークン、ステータス、カードブランドと下 4 桁、請求金額、注文合計と返金額、Description at Pin Payments、返金履歴、注文の Pin Payments notes が含まれます。
返金
Pin Payments ブロックで金額を入力し（まだ返金されていない金額が自動入力されます）、必要に応じて理由を入力して、Refund via Pin Payments をクリックします。確認の質問 Refund this amount through Pin Payments? This cannot be undone. に同意してください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。返金は、Pin Payments が実際に請求した金額と通貨に限定されます。そのため、金額または通貨の不一致の後は、注文合計ではなく、購入者が支払った金額まで返金できます。返金は注文が支払われた環境（テストまたは本番）に送信されるため、そのモードの秘密キーが設定されている必要があります。Pin Payments は返金を非同期で処理するため、ステータスは通常、保留中になります。成功したリクエストは、Pin Payments の返金トークンとそのステータスとともに返金履歴と備考に追加されます。全額返金は注文を Refunded に設定します。一部返金ではステータスは変わりません。Pin Payments が返金を拒否した場合、または応答がない場合、ブロックにエラーが表示され、返金は記録されません。
注文に記録された請求がない場合（Pin Payments から明確な応答がなかった場合）、ブロックには返金フォームは表示されず、Pin Payments のダッシュボードで検索すべき説明が示されます。
モジュールはクレジットスリップを作成しません。注文ページ標準の PrestaShop の返金ボタンは、Pin Payments を通じて返金しません。Pin Payments のダッシュボードで行った返金は PrestaShop に同期されないため、注文ページから返金してください。
ライセンスキー
モジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Pin Payments Gateway は、Modules > Module Manager > VibeFox Pin Payments Gateway > Configure のページで設定より上にある最初のブロックです。License key にキーを入力し、Activate をクリックしてください。その後、ブロックにはキーがマスクされた状態で表示され、ステータス（ライセンスの有効期限日や貴店のドメインなど）と、Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）のボタンが表示されます。その下には Product: presta-payment-pinpayments の行と、Manage licenses and domains in your account のリンク（vibefox.net のアカウントを開きます）があります。キーを変更できるのは、このモジュールの Configure 権限を持つ従業員だけです。ブロックの文言は管理画面の言語に従います（英語とロシア語が含まれます）。
キーが受け付けられない場合、ブロックに理由が表示されます。例：Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ショップのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認されたステータスで動作を続けます。
1 つのキーは 1 つのドメインで動作します。マルチストア構成の場合も、メインショップのドメインが対象です。ショップからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、チェックアウトで Pin Payments は購入者に表示されません。決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のフロントエンドは、管理画面にログインしていることを認識しないため、支払い方法はご自身にも表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響せず、返金は引き続き機能します。
ライセンスの有効期限が切れた後も、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、管理画面での作業中に自動的に再確認されます。キー入力後の最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは必ず削除されます。
トラブルシューティング
チェックアウトに Pin Payments が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの両方のキーが入力されていること（テストモードでは Test publishable key と Test secret key、それ以外の場合は本番用キー）、カートの通貨が 14 のサポート対象通貨のいずれかであることを確認してください。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループに対してモジュールが許可されているか確認してください。設定ページには、キーの欠落と、サポートされていないショップ通貨に対するエラーが表示されます。
支払いは完了したが、注文が Pin Payments payment on hold になっている: Pin Payments ブロックの備考を確認してください（注文ステータスを参照）。Pin Payments から明確な応答がなかった場合は、ダッシュボードで説明 <shop name> - Cart <cart number> の請求を探し、その後、注文を発送するか、ダッシュボードで請求を返金してください。
購入者に Your payment was received, but the order could not be completed automatically: と表示される: カードには請求されましたが、PrestaShop は注文を作成できませんでした（たとえば、その間にモジュールが無効化された場合）。理由はログにあります。購入者には再度支払わないよう案内されます。同じカートを再送信すると、新しい請求なしで注文が作成されます。
購入者に Card payments are temporarily unavailable と表示される: Pin Payments が秘密キーを拒否したか、現在のモードのキーがありません。テスト用キーはテストモードでのみ、本番用キーは本番モードでのみ機能します。ログに理由が表示されます。
注文が additional verification is required で失敗する: Pin Payments アカウントで、モジュールが対応していない 3-D Secure が必須になっています。Pin Payments に、必須の 3-D Secure をオフにするよう依頼してください。
安全なカードフォームを読み込めなかった: Pin Payments の CDN からの Pin.js がブラウザで読み込まれませんでした。たとえば、スクリプトブロッカーや、スクリプトを結合または変更するモジュールが原因の場合があります。チェックアウトをそのような最適化から除外してください。
Pin Payments が応答しなかった: ブラウザで 30 秒以内にカードトークンが作成されませんでした。購入者は接続を確認して再試行できます。請求はされていません。
Pin Payments の理由で支払いに失敗した: Pin Payments が請求情報を拒否しました。たとえば、その通貨の最低請求額を下回る金額です。購入者には理由が表示され、ログにはエラーコードがあります。
返金に失敗する: ブロックのメッセージを読んでください。TEST または LIVE モードに関するメッセージは、注文が支払われたモードの秘密キーが空であることを意味します。Pin Payments did not confirm the refund は応答がなかったことを意味します。再試行する前に、Pin Payments のダッシュボードで請求を確認してください。at most は、請求から返金できる残りの金額を示します。
テスト支払い: テストモードでは、テスト環境とテスト用キーを使用します。Pin Payments の開発者向けドキュメントにあるテストカード（たとえば成功する 4200 0000 0000 0000、拒否される 4100 0000 0000 0001）を、将来の任意の有効期限と任意の CVC で使用してください。注文は支払われたモードを保持するため、モードを切り替えた後も返金は正しい環境に送信されます。
エラーの確認場所: エラーは常にログに書き込まれます。モジュールのページの Log フィールドを確認してください。すべての API 呼び出しを確認するには、Debug log をオンにしてください。
アンインストール
Modules > Module Manager に移動し、VibeFox Pin Payments Gateway の横にあるメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは、常に削除されます。Delete data on uninstall がオンの場合、ゲートウェイの設定とログが削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。Pin Payments の請求と返金、および注文ステータス Pin Payments payment on hold は常に保持されるため、以前に支払われた注文は再インストール後も返金できます。既存の注文は、支払いの備考とトランザクション ID を保持します。
Pin Payments は各権利者の商標です。本モジュールは Pin Payments と提携しておらず、Pin Payments による支持もありません。