VibeFox Viva Wallet for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

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

Viva アカウント: Viva の加盟店アカウント。テストにはデモアカウント（demo.vivapayments.com）、実際の支払いには本番アカウント（www.vivapayments.com）を使用できます。アカウントごとに認証情報が異なります。支払いには Smart Checkout の認証情報（Client ID と Client Secret）と、決済ソースの Source Code が必要です。Merchant ID と API Key は任意です。これらは、Viva によるウェブフック URL の検証に応答するためだけに使用されます。

通貨: EUR、GBP、PLN、RON、BGN、CZK、HUF、DKK、SEK、NOK、CHF のいずれか。その他の通貨では、チェックアウトで支払い方法が表示されません。

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

インストール

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

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

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

4. Viva のデモアカウントまたは本番アカウント（あるいはその両方）の認証情報を入力し、Viva アカウントで決済ソースとウェブフックを設定します（設定を参照）。

5. Enable/Disable を有効にして Save をクリックします。Test Mode がオンの状態で Viva のデモカードを使ってデモ支払いを行い、その後 Test Mode をオフにして本番運用を開始します。

インストール時にモジュールは注文ステータス Viva Wallet payment on hold を作成します。モジュールは、インストール時に有効になっている国に対して提供されます。通貨、国、顧客グループは Payment > Preferences で変更でき、新しい国もそこから後で追加できます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上部には、現在のモードに Client ID、Client Secret、Source Code がない場合（Viva Wallet is hidden at checkout until the Demo Client ID, Client Secret and Source Code are entered.、または本番モードの Live）や、ショップの既定通貨がサポートされていない場合に警告が表示されます。テストモードがオンの間は、Test mode is on: payments go to the Viva demo environment. と表示されます。設定を保存すると、キャッシュされた Viva のアクセストークンが削除されるため、新しい認証情報がすぐに使用されます。

Viva Wallet

Enable/Disable: Enable Viva Wallet payment gateway は支払い方法をオンまたはオフにします。既定値：オフ。

Title: チェックアウトで購入者に表示される支払い方法の名称です。注文に保存される支払い方法名にもなります。既定値：Viva Wallet。必須：空のタイトルは保存されず、ページに Enter a title for the payment method. と表示されます。

Description: チェックアウトで支払い方法の下に表示されるテキストです。既定値：Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

Test Mode: Viva のデモ環境（demo.vivapayments.com）を使用します。新しい支払いと API 呼び出しには、デモアカウントの認証情報が使われます。実際の金額は請求されず、チェックアウトでは購入者に (Test mode: use Viva demo cards, no real money is charged.) と表示されます。既定値：オン。本番アカウントで実際の支払いを受け付けるにはオフにします。既に行われた支払いは、行われた環境で引き続き確認・返金されます。

デモアカウント（テストモード）と本番アカウント

両方のセクションには同じ項目があります。デモアカウント用と本番アカウント用の 2 セットです。Viva アカウントで Settings > API Access を開き、Smart Checkout の認証情報（Client ID、Client Secret）、Merchant ID、API Key をコピーします。Source Code は Sales > Online payments > Websites / apps にあります。

Client ID (Demo) / Client ID (Live): アカウントの Smart Checkout OAuth 2.0 Client ID です。支払いに必須です。

Client Secret (Demo) / Client Secret (Live): アカウントの Smart Checkout OAuth 2.0 Client Secret です。支払いに必須です。

Source Code (Demo) / Source Code (Live): アカウントの決済ソースの 4 桁のコードです。その Success URL と Failure URL は、このショップを指している必要があります（下記参照）。支払いに必須です。

Merchant ID (Demo) / Merchant ID (Live): 任意です。Viva によるウェブフック URL の検証に応答するためだけに使用されます。

API Key (Demo) / API Key (Live): 任意です。Viva によるウェブフック URL の検証に応答するためだけに使用されます。

保存済みの Client Secret と API Key は再表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

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

戻りURLとウェブフック

Addresses for the Viva account: このフィールドには、Viva アカウントに入力するショップの 3 つのアドレスが表示されます。フレンドリー URL が有効な場合は、https://your-shop/module/wcp_viva_gateway/success、https://your-shop/module/wcp_viva_gateway/fail、https://your-shop/module/wcp_viva_gateway/webhook のような形になります（/en/ などの言語コードが付く場合もあります）。設定に表示されているとおりに正確にコピーしてください。

Payment source: 使用する各 Viva アカウントで、Sales > Online payments > Websites / apps からショップのドメイン用の決済ソースを作成します。Success URL と Failure URL には、成功と失敗のアドレスのドメイン以降のパスを入力します。

Webhook: Settings > API Access > Webhooks で、次のイベント用のウェブフックアドレスを追加します：

Viva は保存前に URL を確認します。モジュールはアカウントの検証キーで応答します。現在のモードの Merchant ID と API Key を使ってキーを取得するか、下に入力されたキーを使用します。ウェブフックは、購入者がブラウザを閉じた場合でも支払いを確定させます。Viva のウェブフックには署名がないため、モジュールはウェブフックだけを信頼することはありません。注文を作成する前に、各支払いを Viva API で検証します。ウェブフックがない場合、購入者が支払い後にショップに戻ったときにのみ注文が作成されます。

Webhook Verification Key: 任意です。空のままにすると、現在のモードの Merchant ID と API Key を使ってキーが自動的に取得されます。Viva アカウントの検証キーをここに貼り付けることもできます。

高度な設定

Order Status After Payment: 支払いが成功した後に設定される注文ステータスです。ステータスはすぐに設定され、2 回目のステータス変更は行われません。

Brand Color: Viva の支払いページ用の 6 桁の HEX カラーコード（例：0000ff）です。先頭の # は削除されます。既定の色にする場合は空のままにします。それ以外の値は保存されず、ページに Brand Color must be a 6-digit HEX code (e.g. 0000ff). The previous value was kept. と表示されます。

Debug Logging: API リクエストを、モジュールフォルダ内の logs/viva_wp_debug.log.php に書き込みます。このファイルは Web からは開けません。キー、トークン、購入者データは記録されません。エラーはこの設定がオフでも常に記録されます。既定値：オフ。

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

Delete Data on Uninstall: オンにすると、モジュールをアンインストールしたときに設定とモジュールのログが削除されます。注文と支払いデータ（Viva の支払い試行、返金、注文ステータス）は削除されません。既定値：オフ。

チェックアウト

支払いの段階で購入者は支払い方法（既定では Viva Wallet）を選択し、You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). という注意書きを確認します。確定すると、モジュールはカートの合計金額について、カートの通貨で Viva 決済注文を作成し、購入者を Viva Smart Checkout ページに移動させます。そこで購入者は、Viva アカウントで有効になっている方法のいずれかで支払います。購入者のメールアドレス、氏名、電話番号、国は Viva に渡されます。Viva が対応している場合、ページはカートの言語で開きます。Viva では、支払いは Cart #、カート番号、ショップ名として表示されます。Viva の決済注文は 30 分後に期限切れになります。この時点ではまだ注文は存在しません。

支払い後、購入者はショップに戻ります。注文は Viva が確認した後にのみ支払い済みとしてマークされます。モジュールは、戻りのときとウェブフックのときに、Viva API から取引を再取得します。その後、注文が作成され、購入者には標準の注文確認ページが表示されます。支払いがまだ確認されていない場合は、Payment confirmation ページに We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed. と表示され、Check again と Back to checkout のボタンが表示されます。ウェブフックは、Viva が支払いを確認するとすぐに注文を作成します。

支払いが失敗した場合、または購入者が Viva のページでキャンセルした場合、注文は作成されず、カートは保持されます。購入者は The Viva Wallet payment was not completed. Please try again or choose another payment method. または The Viva Wallet payment was cancelled. You can try again or choose another payment method. と表示されたチェックアウトに戻り、再度支払うことができます。

Viva が支払いを開始できない場合、購入者は Viva Wallet payments are not available at the moment. Please choose another payment method or contact us.（認証情報がない、または誤っている場合）、または We could not connect to Viva Wallet. Please try again in a moment or choose another payment method. と表示されたチェックアウトに残ります。技術的な理由はログに記録されます。

戻りページに注文の確認が表示されるのは、支払いを行った購入者だけです。戻りアドレスを開いた他の人は、注文の詳細を表示されずに注文履歴またはチェックアウトに移動します。

ウェブフックは、ショップがメンテナンスモードの間も動作し、ショップの国の制限にはブロックされません。

モジュールは単発の支払いのみに対応しており、支払いは Viva のページで即座に請求されます。事前承認とキャプチャ、分割払い、保存済みカード、サブスクリプション、Viva Native Checkout（自サイトのページでのカード入力欄）、POS 端末には対応していません。購入者が新しい試行を開始しても、古い未払いの Viva 決済注文はキャンセルされません。Viva が 30 分後に期限切れにします。

注文と返金

注文ステータス

まだ注文はありません: 購入者は Viva に移動しましたが、支払っていない、支払いが失敗またはキャンセルされた、または Viva がまだ支払いを確定していません。カートだけが存在し、購入者は再度支払うことができます。

Payment accepted、Delivered、または Viva Wallet payment on hold: 支払いが確認されました。ステータスは Order Status After Payment に従います。支払いは Viva の取引 ID とともに記録され、メモには金額、取引、Viva の注文コード、環境（デモまたは本番）、確認方法（ウェブフックまたは購入者の戻り）が表示されます。

不一致の後の Viva Wallet payment on hold: Viva が報告した金額または通貨がカートの合計と異なっています。例えば、購入者が支払いを開始した後にカートが変更された場合です。注文は支払い記録なしで作成され、Viva Wallet payment held for review のメモに理由が記載されます。購入者には、Viva の確認が取れたという表示を伴わない標準の注文確認ページが表示されます。Viva ダッシュボードの支払いと注文を照合してから、手動で発送するか返金してください。同じカートに一致する支払いが後から届いた場合、注文は支払い済みのステータスに移動します。

キャンセルまたは返金済みの注文に届いた支払いは、注文ステータスを変更しません。メモが、注文を復元するか、Viva ダッシュボードで支払いを返金するよう求めます。既に支払い済みの注文に 2 件目の支払いが届いた場合、注文は変更されません。メモが、重複分を Viva ダッシュボードで返金するよう求めます。

Viva Wallet payment ブロック

注文ページには、Viva の注文コード、取引 ID、環境と Source Code、Viva のステータス、支払い済み金額と返金済み金額、デモ支払い用の Demo バッジ、返金履歴、カートの支払い試行（複数ある場合）、注文の Viva Wallet notes を含む Viva Wallet payment ブロックが表示されます。

返金

Viva Wallet payment ブロックで金額を入力します（まだ返金されていない金額が自動で入力されます）。必要に応じて理由を入力し、Refund via Viva Wallet をクリックします。Refund this amount via Viva Wallet? This cannot be undone. の確認に同意してください。全額返金と一部返金は、Viva の取引が確認済みの注文でサポートされています。注文を編集する権限が必要です。モジュールへのアクセスは不要です。注文が後から編集された場合でも、Viva が支払いで請求した金額までは返金できます。返金は、支払いが行われたアカウント（デモまたは本番）に、支払いの通貨で送られるため、そのアカウントの Client ID と Client Secret が入力されている必要があります。Viva が返金を受け付けない場合、ブロックにエラーが表示され、返金は記録されません。返金に成功すると、Viva の返金取引とともに返金履歴とメモに追加されます。全額返金を行うと注文は Refunded になります。一部返金ではステータスは変わりません。確認済みの支払いがないまま確認のために保留された注文は、このブロックから返金できません。

本モジュールはクレジットスリップを作成しません。注文ページの標準の PrestaShop の返金ボタンは、Viva を通じて返金を行いません。Viva ダッシュボードで行った返金は取り込まれません。必要に応じて注文を手動で更新してください。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Viva Wallet が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードに Client ID、Client Secret、Source Code が設定されていることを確認してください（テストモードでは Demo の項目、本番モードでは Live の項目）。カートの通貨は EUR、GBP、PLN、RON、BGN、CZK、HUF、DKK、SEK、NOK、CHF のいずれかである必要があります。Payment > Preferences で、カートの通貨、購入者の国、購入者の顧客グループに対してモジュールが許可されているか確認してください。認証情報が不足している場合、設定ページに警告が表示されます。

支払いは完了したが、注文が作成されていない: ウェブフックが機能していません。Viva で、使用しているアカウント（デモまたは本番）にウェブフックが存在すること、その URL が設定に表示されているものと完全に一致していること、Transaction Payment Created が選択されていることを確認してください。その支払いのアカウントの Client ID と Client Secret がまだ入力されていることも確認してください。モジュールが支払いを検証するために必要です。Debug Logging をオンにして、Log フィールドを確認してください。購入者が支払い後にショップに戻った場合にも注文は作成されます。

Viva がウェブフック URL を検証できない: 現在のモードの Merchant ID と API Key を入力し（または検証キーそのものを Webhook Verification Key に入力し）、保存してから Viva で再度検証してください。もう一方のアカウントのウェブフックを検証するには、先に Test Mode を切り替えるか、そのアカウントのキーを入力してください。

ウェブフックがエラーで応答する: Viva はショップの応答を表示し、失敗したウェブフックを再試行します。verification_failed（HTTP 500）は、支払いを検証するために Viva API に到達できなかったか、注文を作成できなかったことを意味します（例：モジュールが無効になっている）。busy（HTTP 503）は、同じ時刻に別のリクエストによって注文が処理中だったことを意味します。transaction_not_found（HTTP 404）は、その支払いのアカウントに取引が存在しないことを意味します（例：認証情報の誤り）。同じ Viva アカウント上の他のショップの支払いに関するイベントには ignored が返されます。

Viva Wallet を選択したときに購入者にエラーが表示される: モジュールページの Log フィールドを確認してください。Client ID または Client Secret が誤っている場合、Viva Wallet の支払いが利用できないというメッセージが表示されます。Viva に接続できない、または支払い注文を拒否する場合（例：Source Code が別のアカウントに属している）、購入者には、ショップが Viva Wallet に接続できなかったというメッセージが表示されます。

購入者が戻ったときに We could not find your order. If you were charged, please contact us. と表示される: 戻りアドレスにある Viva の注文コードは、このショップの支払いではありません。例えば、別のショップの決済ソースがここを指している場合です。決済ソースの Success URL と Failure URL を確認してください。

支払い後に注文が Viva Wallet payment on hold になる: Viva Wallet payment ブロックのメモを確認してから（注文ステータスを参照）、注文を処理するか、支払いを返金してください。

返金が This payment was made in the Viva demo (or live) environment: で失敗する: 支払いが行われたアカウントの Client ID と Client Secret が入力されていません。入力して再試行してください。その他の返金エラーでは、HTTP コードと Viva のメッセージが表示されます。

ブロックに Transaction ID not found. Cannot process refund. と表示される: 注文に確認済みの Viva 支払いがありません。例えば金額の不一致があった場合です。必要に応じて、Viva ダッシュボードで支払いを返金してください。

アンインストール

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

Viva Wallet は、各所有者の商標です。本モジュールは Viva Wallet と提携しておらず、Viva Wallet による推奨も受けていません。