VibeFox Viva Wallet for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

WooCommerce: 7.0 以降がインストールされ、有効になっていること。WooCommerce がない場合、プラグインは有効化されません。

PHP: 8.0 以降。

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。それ以外の通貨では、チェックアウトで決済方法が表示されません。

公開 HTTPS サイト: ウェブフックのため、サイトはインターネットから HTTPS でアクセスできる必要があります。

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

インストール

1. WordPress で Plugins > Add New > Upload Plugin に移動し、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_viva_gateway フォルダを /wp-content/plugins/ にアップロードすることもできます。

2. Activate をクリックします。

3. 設定を開きます：WooCommerce > Settings > Payments > Viva Wallet > Manage。または、Plugins ページでプラグイン名の下にある Settings をクリックします。

4. ページ上部のライセンスブロックに VibeFox ライセンスキーを入力し、Activate をクリックします。

5. デモアカウントや本番アカウントの Viva 認証情報を入力し、決済ソースとウェブフックを設定します（設定を参照）。

6. Enable/Disable をオンにします。Test Mode がオンの状態で、Viva のデモカードを使ってデモ決済を行い、その後 Test Mode のチェックを外して本番運用を開始します。

設定

すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > Viva Wallet。現在のモードに 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. と表示されます。決済方法の一覧では、現在のモードにこの 3 つの値が揃うまで、Viva Wallet は設定が必要な状態として表示されます。

General

Enable/Disable: Enable Viva Wallet payment gateway で決済方法のオン・オフを切り替えます。デフォルト：オフ。

Title: 購入者がチェックアウトで目にする決済方法の名称。デフォルト：Viva Wallet。

Description: チェックアウトで決済方法の下に表示されるテキスト。デフォルト：Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

Test Mode: Use the Viva demo environment (demo.vivapayments.com)。新しい決済と API 呼び出しは、デモアカウントの認証情報を使用します。実際の料金は請求されず、チェックアウトでは説明文が (Test mode: use Viva demo cards, no real money is charged.) で終わります。デフォルト：オン。実際の決済を本番アカウントで受け付けるにはオフにします。すでに行われた決済は、行われた環境で引き続き確認・返金されます。

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

どちらのセクションも同じ項目があります。デモアカウント用と本番アカウント用に 1 セットずつです。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 の検証に応答する場合にのみ使用されます。

戻り URL とウェブフック

Payment source: 使用する各アカウントで、Sales > Online payments > Websites / apps から、ストアのドメイン用の決済ソースを作成します。Success URL と Failure URL には、設定画面に表示される 2 つのアドレスのドメイン以降のパスを入力します。アドレスは次のような形式です：https://your-site/wc-api/viva_payment_success/ と https://your-site/wc-api/viva_payment_fail/。

Webhook: Settings > API Access > Webhooks で、設定画面に表示される URL を追加します。URL は次のような形式です：https://your-site/wp-json/wc-viva-gateway/v1/webhook。対象イベントは次のとおりです：

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）。先頭の # は削除されます。空欄にするとデフォルトの色になります。それ以外の値は保存時に拒否され、以前の値が保持されます。

Debug Logging: Enable logging を有効にすると、API リクエストが WooCommerce > Status > Logs に記録されます（ソース：wcp_viva_gateway）。キーと購入者データは記録されません。エラーは、この設定がオフの場合でも常に記録されます。デフォルト：オフ。

Delete Data on Uninstall: Remove all plugin data when the plugin is deleted。オンの場合、プラグインを削除すると、設定、決済試行のテーブル、プラグインのログが削除されます。注文メモと注文データは残ります。デフォルト：オフ。

チェックアウト

購入者は決済方法（デフォルトは Viva Wallet）を選択して注文します。プラグインは、注文の合計金額について注文通貨で Viva 決済注文を作成し、購入者を Viva Smart Checkout ページに移動させます。購入者は、Viva アカウントで有効になっている方法（カード、Apple Pay、Google Pay など）のいずれかで支払います。購入者のメールアドレス、氏名、電話番号、国は Viva に渡されます。ページは、Viva がサポートしている場合はストアの言語で、サポートしていない場合は英語で表示されます。Viva の画面では、決済は WooCommerce # と注文番号として表示されます。Viva の決済注文は 30 分後に期限切れになります。

支払い後、購入者はストアの注文受付ページに戻ります。注文が支払い済みになるのは、Viva が確認した後だけです。プラグインは、戻り時とウェブフックの際に、Viva API から取引を再取得します。決済がまだ確認されていない場合、ページには We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed. と表示されます。

決済が失敗した場合、または購入者が Viva のページでキャンセルした場合、注文ステータスは変わりません。購入者は Pay for order ページに移動し、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. と表示されます。技術的な理由はログに記録されます。

この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで利用できます。Pay for order ページでは、その注文の通貨が確認されます。WooCommerce High-Performance Order Storage（HPOS）に対応しています。

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

注文と返金

Order statuses

Pending payment: 購入者は Viva に移動されたものの、まだ支払っていない、決済がまだ確認されていない、または決済が失敗もしくはキャンセルされた状態です。メモには Viva 決済注文と環境（デモまたは本番）が表示されます。失敗した試行とキャンセルされた試行は注文メモに追加され、購入者は再度支払うことができます。

Processing, Completed or On Hold: 決済が確認されました。ステータスは Order Status After Payment に従います。注文メモには、金額、Viva 取引 ID、環境、確認方法（ウェブフックまたは購入者の戻り）が表示されます。

On hold for review: 注文の合計金額と異なる金額または通貨を Viva が報告しました。たとえば、購入者が支払いを始めた後に注文が編集された場合です。Viva Wallet payment held for review メモに理由が記載されます。Viva ダッシュボードで決済と注文を照合し、注文を完了するか、決済を手動で返金してください。

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

返金

注文を開き、Refund をクリックして金額を入力し、Refund via Viva Wallet をクリックします。Viva 取引が確認済みの注文では、全額返金と一部返金に対応しています。返金は、決済が行われたアカウント（デモまたは本番）に、決済の通貨で送信されます。そのため、そのアカウントの Client ID と Client Secret を入力しておく必要があります。Viva が返金を受け付けない場合、WooCommerce にエラーが表示され、返金は記録されません。返金が成功すると、Viva の返金取引とともに注文メモに追加されます。

Viva ダッシュボードで行われた返金は取り込まれません。必要な場合は、Refund via Viva Wallet を使わずに、WooCommerce で手動の返金を作成してください。

ライセンスキー

プラグインは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロックは WooCommerce > Settings > Payments > Viva Wallet の上部にあります。キーを License key に貼り付け、Activate をクリックします。ブロックには、ステータス（たとえばライセンスの有効期限の日付）と、お使いのドメインが表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除します。Manage licenses and domains in your account のリンクから、vibefox.net のアカウントを開けます。

1 つのキーは 1 つのドメインでのみ使用できます。サイトからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがない場合、Viva Wallet はチェックアウトで購入者に表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。ログイン中のストア管理者には、決済方法が (unlicensed — visible to admins only) と表示された状態で引き続き表示されるため、キーを購入する前にプラグインを設定してテストできます。プラグインのページと WooCommerce のページには、リマインダーが表示されます。既存の注文は影響を受けません。すでに開始された決済は引き続き確認され、返金も機能します。

ライセンスの期限が切れた場合も、プラグインは動作を続けますが、アップデートとサポートには更新が必要です。ステータスはバックグラウンドで自動的に再確認されます。

トラブルシューティング

Viva Wallet がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードに Client ID、Client Secret、Source Code があることを確認してください（テストモードでは Demo の項目、本番モードでは Live の項目）。ストアの通貨（Pay for order ページでは注文の通貨）は、EUR、GBP、PLN、RON、BGN、CZK、HUF、DKK、SEK、NOK、CHF のいずれかである必要があります。何かが不足している場合、設定ページに警告が表示されます。

決済は完了したが、注文が Pending payment のまま: ウェブフックが機能していません。Viva で、使用しているアカウント（デモまたは本番）にウェブフックが存在すること、その URL が設定画面に表示されているものと完全に一致すること、Transaction Payment Created が選択されていることを確認してください。その決済のアカウントの Client ID と Client Secret がまだ入力されていることも確認してください。プラグインはこれを使って決済を確認します。詳細は WooCommerce > Status > Logs（ソース：wcp_viva_gateway）にあります。

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 が返されます。

購入者が注文時にエラーを見る: Debug Logging をオンにし、WooCommerce > Status > Logs（ソース：wcp_viva_gateway）を確認してください。Client ID または Client Secret が誤っている、または Source Code がない場合、Viva Wallet の決済が利用できないというメッセージが表示されます。Viva に接続できない場合や、決済注文を拒否された場合（たとえば Source Code が別のアカウントのものである場合）、購入者にはストアが Viva Wallet に接続できなかったというメッセージが表示されます。

決済後に注文が On hold になる: 注文メモを確認してください。支払われた金額または通貨が注文と異なっていました。注文を完了するか、決済を返金してください。

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

ライセンスブロックにエラーが表示される: ブロックのメッセージに従ってください。たとえば、キーが別のドメインですでに使われている場合は、vibefox.net のアカウントで枠を解放し、Check now をクリックします。サイトのアドレスが変わった場合は、Check now をクリックして、新しいドメインでキーを有効にします。ライセンスサーバーに接続できない場合、プラグインは最後に確認できたステータスで動作を続けます。

開発者向け: フィルター viva_wp_supported_currencies は、Viva アカウントでサポートされている追加の通貨を有効にします。viva_wp_create_order_payload は決済注文のリクエストを変更します（金額、通貨、Source Code は維持する必要があります）。viva_wp_icon はチェックアウトのアイコンを変更します。

アンインストール

プラグインを無効化してもすべてのデータは保持されます。削除されるのはキャッシュされた Viva アクセストークンのみです。完全に削除するには、プラグインを無効化してから Plugins ページで削除してください。このプラグインのライセンスキーとライセンスステータス、キャッシュされたトークン、ウェブフックキーは、常に削除されます。設定、決済試行のテーブル、プラグインのログ（ローテーションされたログファイルとデータベースのログエントリーを含む）は、Delete Data on Uninstall がオンの場合にのみ削除されます。それ以外の場合は、再インストールのために残ります。既存の注文は、決済メモと取引 ID を保持します。

Viva Wallet は、各所有者の商標です。本プラグインは Viva Wallet と提携しておらず、Viva Wallet による推奨も受けていません。