VibeFox Tap for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x まで。

PHP: 8.0 以降。古い PHP バージョンではモジュールをインストールできません。

ショップ通貨: AED、BHD、EGP、EUR、GBP、JOD、KWD、OMR、QAR、SAR、USD のいずれか。これ以外の通貨のカートでは、注文手続き時にこの決済手段が表示されません。

ショップへのインターネット接続: Tap は決済結果をショップ上のウェブフックに送信するため、サイトがインターネットから到達可能である必要があります。ウェブフック URL はすべての決済で送信されるため、Tap 管理画面での設定は不要です。

Tap アカウント: Tap 管理画面（goSell、API 認証情報）で取得した API キーが必要です。テストキーは pk_test_ / sk_test_ で始まり、本番キーは pk_live_ / sk_live_ で始まります。シークレットキーは常に必要です。公開可能キーはポップアップの場合のみ必要です。提供する決済手段（mada、KNET、Benefit など）と Apple Pay のドメイン確認は、Tap アカウントで設定します。

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

インストール

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

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

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

4. Tap のテストキーと本番キーを入力し、決済アクション、注文手続きの方式、Tap ページの言語を選択します（「設定」を参照）。

5. Enable / Disable をオンにして Save をクリックします。Tap のテストカードで動作を確認してから、Test mode をオフにします。

インストール時にモジュールは 2 つの注文ステータスを作成します。Tap payment authorized と Tap payment on hold です。PrestaShop は、すべての通貨、国、顧客グループに対して新しい決済モジュールを有効にします。Payment > Preferences で制限できます。

設定

すべての設定はモジュールのページにあります: Modules > Module Manager > VibeFox Tap Payments > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。フィールドの上には、Test mode is on: payments use your Tap test keys and no real money is charged. または Live mode: real payments are accepted. と表示されます。現在のモードのキーがない場合（この場合、注文手続きに決済手段は表示されません）や、ショップの既定通貨が Tap で提供されていない場合にも警告が表示されます。

保存時、フィールドに対して接頭辞が誤っているキーは保存されません。以前の値が保持され、その他の設定は保存され、Test secret key was not saved: a Tap key for this field starts with "sk_test_". のようなメッセージが表示されます。たとえば、テスト用フィールドに本番キーを入力すると拒否されます。空の Title は受け付けられません。ページに Enter a title for the payment method. と表示され、何も保存されません。

Tap Payments

セクションの見出しには、現在のモードの TEST または LIVE も表示されます。

Enable / Disable: Enable Tap Payments は決済手段をオンまたはオフにします。既定値: オフ。

Title: 注文手続きで表示される決済手段名です。注文にも決済手段名として保存されます。既定値: Tap Payments。必須。

Description: 注文手続きで決済手段の下に表示されるテキストです。既定値: Pay with Visa, Mastercard, mada, KNET, Benefit, Apple Pay or Google Pay.

Tap API キー

キーは Tap 管理画面（goSell、API 認証情報）にあります。テストキーは pk_test_ / sk_test_ で、本番キーは pk_live_ / sk_live_ で始まります。

Test mode: テストキーを使用し、実際の料金は請求されません。決済、ステータス確認、キャプチャ、返金は、常に決済が行われたモードのキーを使用します。そのため、本番に切り替えた後でもテスト決済はテストキーで確認・返金されます。既定値: オン。オンの間、顧客には決済手段の下に Test mode: no real payment will be made. と表示されます。

Test publishable key: pk_test_ で始まります。ポップアップに必要です。

Test secret key: sk_test_ で始まります。

Live publishable key: pk_live_ で始まります。ポップアップに必要です。

Live secret key: sk_live_ で始まります。

Merchant ID: 任意です。Tap のマーチャント ID です。Tap から特定のマーチャントアカウントへ決済をルーティングするよう求められた場合にのみ必要です。

保存済みのシークレットキーは二度と表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。公開可能キーは公開情報のため、引き続き表示されます。

Clear saved secrets: シークレットキーにチェックを入れて Save をクリックすると削除されます。フィールドが空の場合は、保存済みの値が保持されます。

支払い

Payment action: 顧客が支払ったときに、お金がどう扱われるかを決めます。

Checkout type: 顧客が支払う場所です。

Tap page language: English（既定）または Arabic。

決済通知（ウェブフック）

Tap は、このセクションの Webhook URL に表示された URL に決済結果を送信します。フレンドリー URL を使用している場合は https://your-shop/module/wcp_tap_payment_gateway/webhook のような形式になり、/en/ のような言語コードが付くこともあります。この URL はすべての決済で送信されるため、Tap 管理画面で設定する必要はありません。インターネットから到達可能であることだけ確認してください（ファイアウォールや HTTP 認証でブロックされていないこと）。各通知は hashstring 署名（HMAC-SHA256、決済が行われたモードのシークレットキーを使用）で検証されます。有効な署名のないウェブフックは拒否されます。署名された通知であっても、それだけで信頼されるわけではありません。モジュールは注文を作成または変更する前に、Tap API から決済を再度読み取ります。ウェブフックが機能していない場合、注文は顧客が支払い後にショップへ戻ったときにのみ作成されます。

詳細設定

Debug log: 決済イベントを、モジュールフォルダ内の logs/tap_p_debug.log.php に記録します。このファイルは Web から読み取ることはできません。エラーと警告は常に記録されます。すべての決済イベントも記録するには、このオプションをオンにします。ログにキー、カード情報、顧客データが含まれることはありません。既定値: オフ。

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

Delete data on uninstall: オンの場合、モジュールをアンインストールすると、ゲートウェイ設定とログが削除されます。注文の決済記録は保持されます。既定値: オフ。

注文手続き

支払いの手順で、顧客は決済手段（既定では Tap Payments）を選び、注文を確定します。この時点ではまだ注文は存在しません。

Tap payment page: モジュールは、カートの通貨でカート合計金額について Tap の請求（Authorize only モードの場合は承認）を作成し、説明に Cart # とカート番号を設定して、顧客を Tap の決済ページへ移動させます。顧客の氏名、メールアドレス、電話番号は Tap に渡されます。顧客は Tap のページでカード、mada、KNET、Benefit、Apple Pay、Google Pay のいずれか（Tap アカウントで有効なもの）を選び、支払います。Tap が決済を開始できない場合、顧客は注文手続きページに留まり、The Tap payment could not be started. Please try again or choose another payment method. が表示されます。理由はログに記録されます。

Tap checkout popup: 顧客はモジュールの Tap payment ページに移動し、そこで Tap の決済フォームが開きます。ページには Pay on the Tap payment page instead というリンクも表示されます。ウィンドウを閉じた場合は Pay now ボタンで再度開けます。フォームを読み込めない場合は、顧客に Tap の決済ページを使うよう案内されます。ページを再読み込みしても、同じ決済の試行が再利用されます。

支払い後、顧客はショップに戻ります。注文は Tap が確認した後にのみ支払い済みになります。モジュールは、決済のモードのキーを使って Tap API から決済を読み取り、その決済がこのカートに関連し、そのチェックアウトから開始されたことを確認したうえで、金額と通貨をカートと比較します。戻り先アドレスにある Tap ID だけでは、注文は作成されません。ウェブフックも、バックグラウンドで同じ確認を行います。その後、注文が作成され、顧客には標準の注文確認ページが表示されます。承認された決済の場合、ページには Your payment has been authorized. We will process the order as soon as the payment is captured. が表示されます。保留中の注文の場合は Your payment is being reviewed. We will contact you if anything else is needed. が表示されます。

顧客が戻った時点で Tap がまだ決済を確認していない場合、Payment confirmation ページに We have not received the payment confirmation from Tap yet. If you completed the payment, the order will be updated automatically in a few minutes — there is no need to pay again. が表示され、Check again と Back to checkout のボタンが表示されます。ウェブフックが届き次第、注文が作成されます。

決済が拒否された場合、中止された場合、またはキャンセルされた場合、注文は作成されません。顧客は Your payment was not completed. Please try again or choose another payment method. と共に注文手続きに戻ります（Tap が理由を示した場合は、その理由も表示されます）。完了していない決済には The payment was not completed. You can try again or choose another payment method. と表示されます。カートは保持され、再度支払うことができます。

注文手続きのその他のメッセージ: カートの通貨がサポートされていない場合は通貨コードに続けて Tap does not accept payments in と表示されます。また The order total must be greater than zero to pay with Tap. も表示されます。

ウェブフックは、ショップがメンテナンスモードの間も機能し、ショップの国別制限の影響は受けません。

このモジュールには、保存済みカードやトークン化、サブスクリプション、注文手続きページに組み込まれたカード入力欄はありません。Capture Tap payment は常に注文合計額をキャプチャします。部分キャプチャには対応していません。

注文と返金

注文ステータス

注文はまだありません: 顧客は Tap に移動したものの支払っていない、または Tap がまだ決済を確認していない状態です。存在するのはカートだけです。

Payment accepted: Tap がキャプチャ済みの決済を確認しました。決済は Tap の請求 ID（chg_...）をトランザクション ID として記録され、メモには金額、請求 ID、決済手段、そして（テストモードの場合）テスト決済であることが表示されます。

Tap payment authorized: 決済は承認のみされており、キャプチャまたは取り消しを待っています。

Tap payment on hold: 支払われた金額または通貨がカートと異なっていた（Tap: amount/currency mismatch — manual review required.）、または注文がキャンセルされた後に決済が届きました。メモに理由が記されます。注文を確認して処理するか、決済を返金してください。

Canceled: 承認は Void Tap authorization によって取り消され、予約されていた資金は解放されました。

Refunded: 決済はモジュールを通じて全額返金されました。

失敗した試行が、支払い済み、承認済み、またはキャンセル済みの注文を変更することはありません。すでに支払い済みの注文に対して 2 回目の決済が成功した場合、注文は変更されません。メモで重複決済であることが示され、Tap 管理画面で返金するよう求められます。カートに関連しているものの、そのチェックアウトから開始されていない決済は、メモに記録されるだけです。

Tap 決済ブロック

注文画面には Tap payment ブロックが表示され、Tap の ID、承認と請求、モード（テスト決済には Test mode バッジ）、決済ステータスと決済手段、Charged / refunded、返金履歴、カートの決済試行、注文の Payment notes が含まれます。ブロックのボタンは注文画面で直接動作します。必要なのは注文を編集する権限であり、モジュール設定へのアクセス権ではありません。

キャプチャとキャンセル

Authorize only モードでは、Tap payment authorized の状態の注文を開きます。Capture Tap payment（ボタンに注文合計額が表示されます）は、Capture the reserved funds of this order through Tap? の確認の後に注文合計額をキャプチャします。その後、注文は Payment accepted になります。Void Tap authorization は Release the reserved funds? The order will be canceled. を確認し、資金を解放して注文を Canceled に設定します。Tap が操作を拒否した場合、ブロックにエラーが表示され、メモにも追加されます。承認が Tap 管理画面で直接キャプチャされた場合、ウェブフックが注文を支払い済みとして記録します。この決済の返金は Tap 管理画面で行う必要があります。

返金

Tap payment ブロックで金額を入力し（まだ返金されていない金額が自動入力されます）、必要に応じて理由を入力して、Refund via Tap をクリックします。Refund this amount through Tap? This cannot be undone. を確認してください。キャプチャ済みの Tap 請求に対して、全額返金と一部返金に対応しています。注文が後から編集されていても、Tap が実際に請求した金額と通貨までを返金できます。返金は、決済が行われたモードのシークレットキーで送信されるため、そのモードのキーが設定されている必要があります。Tap が受け付けた返金は、Tap の返金 ID とステータスとともに返金履歴とメモに追加されます。Tap が拒否した場合、ブロックにエラーが表示され、返金は記録されません。全額返金の場合、注文は Refunded になります。一部返金の場合、ステータスは変わりません。承認済みの注文の場合、返金は承認がキャプチャされた後に利用できます。金額または通貨の不一致により保留になった注文は、Tap 管理画面で返金します。

モジュールは貸方伝票を作成しません。注文画面にある PrestaShop の標準の返金ボタンでは、Tap を通じて返金されません。Tap 管理画面で行った返金は、PrestaShop には表示されません。

ライセンスキー

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

有効なキーがない場合、チェックアウトで購入者に Tap Payments は表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、あなたにも決済方法は非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。すでに開始された決済は引き続き確認され、返金、キャプチャ、キャンセルも機能します。

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

トラブルシューティング

Tap Payments が注文手続きに表示されない: ライセンスが有効であること、Enable / Disable がオンであること、現在のモードにシークレットキーがあること（Checkout type がポップアップの場合は公開可能キーも）を確認してください。カートの通貨が AED、BHD、EGP、EUR、GBP、JOD、KWD、OMR、QAR、SAR、USD のいずれかであることを確認してください。Payment > Preferences で、カートの通貨、顧客の国、顧客グループに対してモジュールが許可されていることを確認してください。設定ページには、キーの不足とサポートされていないショップ通貨に関する警告が表示されます。

決済は完了したが注文が作成されない: ウェブフックがショップに到達できていません。Webhook URL に表示された URL がインターネットから到達可能であること（ファイアウォールや HTTP 認証がないこと）を確認し、Log フィールドで応答を確認するために Debug log をオンにしてください。顧客が Tap から戻った場合にも注文は作成されます。

Webhook answers invalid signature: 通知が、決済のモードのシークレットキーで署名されていません。設定のシークレットキーを確認してください。

Webhook answers gateway not configured: 決済のモード（テストまたは本番）のシークレットキーが空です。入力してください。

Webhook answers verification failed: 決済を確認するための Tap API に接続できませんでした。Tap は後でウェブフックを再試行します。

Webhook answers order not found: 通知が、このショップに Tap の決済試行がないカートを指定しています。

Webhook answers busy, retry later or order could not be updated, retry later: 注文が同時に別のリクエストによって確認されていた、または注文を作成できなかった（たとえばモジュールが無効になっている）ためです。Tap はウェブフックを再試行します。理由は Log フィールドで確認してください。

キーが保存されない: キーは、そのフィールドの接頭辞で始まる必要があります: pk_test_、sk_test_、pk_live_、sk_live_。

顧客に The Tap payment could not be started と表示される: モジュールページの Log フィールドを確認してください。誤ったキーや拒否されたリクエストがそこに記録されています。

顧客に We could not match this payment to an order と表示される: その決済はこのカートに属していない、またはそのチェックアウトから開始されたものではありません。お金が引き落とされている場合は、Tap 管理画面で決済を確認してください。

注文が Tap payment on hold である: Tap payment ブロックのメモを確認してください。支払われた金額または通貨がカートと一致しなかった、または注文がキャンセルされた後に決済が届いたためです。

返金がモードに関するメッセージで失敗する: 決済はテストモードまたは本番モードで行われましたが、そのモードのシークレットキーが設定されていません。キーを入力して、もう一度お試しください。ブロックに、キャプチャ済みの Tap 請求が見つからないと表示される場合は、Tap 管理画面で決済を返金してください。

開発者向けフック: actionWcpTapChargePayload、actionWcpTapSupportedCurrencies、actionWcpTapCurrencyDecimals のフックを使うと、開発者は決済リクエスト、サポートされる通貨、通貨の小数点以下桁数を変更できます。

アンインストール

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

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