VibeFox Yoco for WooCommerce — ヘルプ

要件

WordPress: 6.2 以降。

WooCommerce: 8.0 以降。インストールされ、有効になっている必要があります。WooCommerce がないとプラグインは有効化できません。

PHP: 8.0 以降。

ストアの通貨: 南アフリカ・ランド（ZAR）。Yoco が受け付けるのは ZAR のみです。それ以外の通貨では、チェックアウトに決済方法が表示されません。注文合計は R2.00 以上である必要があります。

Yoco アカウント: オンライン決済が有効な Yoco アカウント。その秘密キーが必要です。キーは Yoco Business Portal の Selling Online > Payment Gateway にあります。入力するのは秘密キーだけです。ウェブフックはプラグインが登録し、その署名シークレットは自動的に入力されます。

公開サイト: Yoco は貴サイトにウェブフックを送信するため、インターネットから到達可能である必要があります。ウェブフック URL は、リダイレクトなしで POST を受け付ける必要があります。

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

インストール

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

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

3. 設定を開きます: WooCommerce > Settings > Payments > Yoco > Manage。

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

5. テスト用の秘密キー（sk_test_...）を貼り付け、準備ができたら本番用の秘密キー（sk_live_...）を貼り付けます。設定を保存します。キーがあるモードごとにウェブフックが登録されます。

6. Enable/Disable を有効にします。Test mode が有効な間に Yoco のテストカードで試験決済を行い、その後 Test mode のチェックを外して実際の決済を受け付けます。

設定

すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > Yoco。ストアの通貨が ZAR でない場合（その場合、Yoco はチェックアウトで提供されません）や、現在のモードに秘密キーがない場合、ページはフィールドの上で警告します。決済方法の一覧では、現在のモードに秘密キーが設定されるまで、Yoco に設定が必要と表示されます。保存すると、プラグインはキーとウェブフックの署名シークレットを確認し、ウェブフックを登録します。これに関するメッセージはページの上部に表示されます。

一般

Enable/Disable: Enable Yoco で決済方法を有効または無効にします。既定値: off。

Title: チェックアウトで購入者に表示される決済方法の名前。既定値: Card or Instant EFT (Yoco)。

Description: チェックアウトで決済方法の下に表示されるテキスト。既定値: You will be redirected to the secure Yoco page to pay by card or Instant EFT.

API キー

秘密キーは Yoco Business Portal の Selling Online > Payment Gateway からコピーします。Yoco は両方のモードに 1 つの API を提供しており、キーによって決済がテストか実際かが決まります。テストモードはテスト用のキーだけを使用し、本番モードは本番用のキーだけを使用します。

Test mode: Use the test secret key (no real payments)。実際の金額は請求されません。Yoco のテストカードで決済してください。既定値: on。実際の決済を受け付けるにはチェックを外してください。

Test secret key: テストモードの秘密キー。sk_test_ で始まります。

Live secret key: 本番モードの秘密キー。sk_live_ で始まります。

想定されるプレフィックスで始まらないキーは保存されません。ページにエラーが表示され、以前の値が保持されます。ウェブフックの登録中に Yoco がキーは別のモードのものだと報告した場合、ページがその旨を表示します。

ウェブフック

Yoco は、決済と返金の結果を、このセクションに表示されるウェブフック URL に通知します。URL は次の形式です: https://your-site/wc-api/yoco_pay_webhook/。Yoco ポータルでウェブフックを作成する必要はありません。設定を保存すると、プラグインは秘密キーはあるがウェブフックのシークレットがないモードごとに、URL を Yoco に登録し、署名シークレットをそのモードのフィールドに保存します。そのモードの秘密キーまたはウェブフック URL が変更されると、URL を再登録します。URL が変更された場合、古い登録は削除されます。

セクションには、各モードのウェブフックの状態が表示されます:

プラグインは次のイベントを処理します:

有効な署名がないウェブフックは拒否されます。サイトの URL で言語プレフィックスを使用している場合は、設定に表示されたとおりに URL を保持してください。ウェブフックはリダイレクトなしでストアに届く必要があります。

Test webhook secret: ウェブフックの登録時に自動入力されます。ウェブフック URL を自分で登録した場合にのみ、シークレット（whsec_...）を貼り付けてください。

Live webhook secret: ウェブフックの登録時に自動入力されます。フィールドを空にして保存すると、ウェブフックが再登録されます。

ウェブフックシークレットは、whsec_ に続けて base64 のテキストという形式である必要があります。それ以外の値は保存されず、以前の値が保持されます。

詳細設定

Debug log: Log Yoco requests and webhooks は、リクエストとウェブフックを WooCommerce > Status > Logs に書き込みます。ソースは wcp_yoco_pay です。Yoco へのリクエスト失敗や拒否されたウェブフックなどのエラーと警告は、常に記録されます。キー、ウェブフックシークレット、メールアドレスはマスクされます。既定値: off。

Delete data: Delete the settings and logs of this plugin when it is deleted。無効化では何も削除されません。注文データ（Yoco のチェックアウト ID と決済 ID）は、返金に必要なため、常に保持されます。既定値: off。

チェックアウト

購入者は決済方法（既定では Card or Instant EFT (Yoco)）を選び、注文します。テストモードでは、チェックアウトに Test mode — use a Yoco test card; no real money is charged. と表示されます。プラグインは注文合計を銭単位にした Yoco チェックアウトを作成し、購入者を Yoco の決済ページに移動させます。購入者はそこでカードまたは Instant EFT で支払います。

支払い後、購入者はストアに戻ります。注文が支払い済みになるのは、Yoco が確認した後だけです。プラグインは、購入者が戻ったときと、署名付きウェブフックが届いたときに、Yoco にチェックアウトを照会します。Yoco がまだ決済を確認していない場合、注文受付ページには We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again. が表示されます。

購入者が Yoco ページでキャンセルすると、注文は未払いのままになり、購入者は Pay for order ページに移動して、The Yoco payment was cancelled. Your order is saved — you can pay again below or choose another payment method. というメッセージが表示されます。決済に失敗した場合は、The Yoco payment was not successful. Please try again or choose another payment method. と表示され、注文に備考が追加されます。

購入者は、未払いの注文を Pay for order ページから再度支払うことができます。新しい試行の前に、プラグインは以前の試行を Yoco で確認します。すでに支払い済みであれば、新しい決済ページを表示せずに注文が完了します。同じ金額でまだ未完了のままで、30 分以内に作成されたものであれば、購入者には同じ Yoco ページが再び表示されます。

Yoco が決済を開始できない場合、購入者には Yoco could not start the payment. Please try again in a moment or choose another payment method. が表示され、その理由が注文メモに追加されます。注文金額が R2.00 未満の場合は、Yoco requires an order total of at least R2.00. が表示されます。

この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce の高性能注文保存（HPOS）に対応しています。

決済は Yoco のページで直ちに請求されます。プラグインには、保存済みカード、サブスクリプション、定期決済、サイト上のカード入力フォーム、別々の承認とキャプチャはありません。また、ZAR 以外の通貨では動作しません。

注文と返金

注文ステータス

Pending payment: 購入者は Yoco に移動しましたが、まだ支払っていない、Yoco ページでキャンセルした、または Yoco がまだ決済を確認していない状態です。

Processing or Completed: 決済が確認されました。WooCommerce は、ダウンロード可能なバーチャル商品だけの注文には「完了」、それ以外には「処理中」を設定します。注文メモには、金額、Yoco の決済 ID とチェックアウト ID、モード、決済の確認方法（購入者の戻り、ウェブフック、または新しい決済試行前の確認）が表示されます。トランザクション ID は Yoco の決済 ID です。

On hold: Yoco が、注文合計と異なる金額または通貨を報告しました。例えば、決済の開始後に注文が編集された場合です。メモにその理由が記載され、Yoco から戻った購入者には We received your payment and are reviewing it. We will contact you if anything else is needed. が表示されます。発送前に決済を確認してください。

Cancelled or Refunded: そのような注文に届いた決済は、注文を変更しません。メモでは、Yoco ポータルで決済を返金するか、注文を手動で復元するよう求められます。Yoco から戻った購入者には Your payment was received after the order had been cancelled. Please contact us — do not pay again. が表示されます。

すでに支払い済みの注文に 2 回目の決済が届いた場合、注文は再び変更されません。メモでは、Yoco ポータルで返金するよう求められます。

返金

注文を開き、Refund をクリックして金額を入力し、決済方法の名前が付いた Refund via ボタン（既定では Card or Instant EFT (Yoco)）をクリックします。全額返金と一部返金に対応しています。返金は決済が行われたモード（テストまたは本番）で送信されるため、そのモードの秘密キーが設定されている必要があります。応答が失われた後に繰り返された返金は、二重に支払われることはありません。

成功した返金は、Yoco の返金 ID とともに注文メモに追加されます。Yoco が返金を拒否した場合、WooCommerce は理由とともに Yoco refused the refund: を表示し、返金は記録されません。Yoco が返金を保留と報告した場合、WooCommerce はまだ保留中であることを表示し、何も記録しません。繰り返さないでください。Yoco がウェブフックで確認すると、注文に追加されます。

Yoco ポータルで行われた返金は、refund.succeeded ウェブフックで届き、商品の在庫を戻すことなく、自動的に WooCommerce の返金として記録されます。返金可能な残額を超える返金は記録されず、メモで注文の確認が求められます。失敗した返金では、お金が購入者に返金されていないことを示すメモが追加されます。

ライセンスキー

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

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

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

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

トラブルシューティング

Yoco がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable が有効であること、現在のモードに秘密キーがあることを確認してください。テストモードでは Test secret key、本番モードでは Live secret key です。ストアまたは注文の通貨は ZAR、注文合計は R2.00 以上である必要があります。キーがない場合や通貨が ZAR でない場合、設定ページに警告が表示されます。

決済は完了したが、注文が Pending payment のまま: ウェブフックが機能していません。設定の Webhooks セクションを開き、使用しているモードの状態を確認してください。登録されていない場合、または別の URL に登録されている場合は、設定を保存してください。登録に失敗した場合は、ページに理由が表示されます。シークレットを自分で入力した場合は、この URL とモードのウェブフック用であることを確認してください。注文は、購入者が決済後にストアに戻ったときや、再度支払いを試みたときにも確定します。

ウェブフックを登録できない: 購入者がストアに戻ったときには、決済は引き続き確定します。メッセージに表示された理由を修正してください。例えば、サイトが HTTPS でインターネットから到達可能である必要があります。その後、再度保存してください。URL を自分で登録し、署名シークレットを貼り付けることもできます。

ウェブフックが拒否される: 拒否されたウェブフックは、ソース wcp_yoco_pay のログに書き込まれます。webhook secret not configured は、どちらのウェブフックシークレットも設定されていないことを意味します。invalid signature は、シークレットが別の登録またはモードのものであることを意味します。timestamp outside the tolerance は、サーバーの時計が誤っていることを意味します。署名は、サーバー時刻から 5 分以内のものだけが受け付けられます。checkout not completed yet — retry と could not confirm the checkout with Yoco — retry は一時的なもので、Yoco がウェブフックを再送します。

The secret key must start with sk_test_ / sk_live_ error on save: キーが誤ったフィールドに貼り付けられました。テスト用キーは sk_test_ で、本番用キーは sk_live_ で始まります。以前の値は保持されています。

購入者が注文時にエラーを見る: 注文メモか、ソース wcp_yoco_pay の WooCommerce > Status > Logs を確認してください。Yoco is not available at the moment. Please choose another payment method. は、現在のモードに秘密キーがないことを意味します。

購入者に、決済の確認が必要と表示される: 以前の試行が、異なる金額で支払われた、または注文のキャンセル後に支払われたものです。注文メモを読み、注文を処理するか、Yoco ポータルで決済を返金してください。

モードに関するメッセージで返金が失敗する: 決済はテストモードまたは本番モードで行われ、そのモードの秘密キーが設定されていません。キーを入力して、もう一度試してください。

No answer from Yoco で返金が失敗する: WooCommerce には何も記録されていません。Yoco が返金を処理していた場合は、同じ返金を繰り返してください。二重に返金されることはありません。

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

アンインストール

プラグインを無効化しても、すべてのデータは保持されます。削除するには、無効化してから Plugins ページで削除してください。このプラグインのライセンスキーとライセンスステータスは、常に削除されます。ゲートウェイの設定、Yoco 上のウェブフック登録、ローテーションされたログファイルを含むログは、Delete data が有効な場合にのみ削除されます。そうでなければ、後の再インストールのために残ります。既存の注文は、決済の備考とトランザクション ID を保持します。

Yoco は、それぞれの所有者の商標です。このプラグインは Yoco と提携しておらず、Yoco の推奨も受けていません。