VibeFox Yoco for PrestaShop — ヘルプ

要件

PrestaShop： 8.0 ～ 9.x。

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

ショップの通貨：南アフリカ・ランド（ZAR）。Yoco は ZAR のみを受け付けます。他の通貨では、チェックアウトで支払い方法が表示されません。注文合計は R2.00 以上である必要があります。

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

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

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

インストール

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

2. アップロードが完了したら Configure をクリックします。後で探す場合は、モジュール一覧から VibeFox Yoco Pay Gateway を見つけて Configure をクリックします。

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

4. テスト用シークレットキー（sk_test_...）を貼り付け、準備ができたら本番用シークレットキー（sk_live_...）を貼り付けます。Save をクリックします。キーがあるモードごとにウェブフックが登録されます。

5. Enable/Disable をオンにして Save をクリックします。Test mode がオンの間に Yoco のテストカードで決済テストを行い、実際の決済を受け付けるには Test mode をオフにします。

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

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Yoco Pay Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上には、ショップの通貨が ZAR でない場合（その場合チェックアウトで Yoco は提供されません）や、現在のモードにシークレットキーがない場合（例：Enter the test secret key to offer Yoco at checkout (test mode).）に警告が表示されます。保存すると、モジュールはキーとウェブフックシークレットを確認し、ウェブフックを登録します。これに関するメッセージはページ上部に表示されます。

Yoco

Enable/Disable：Enable Yoco で支払い方法をオンまたはオフにします。デフォルト：オフ。

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 には両方のモードに共通の API が 1 つあり、キーによって決済がテストか実際かが決まります。テストモードはテスト用キーのみを、本番モードは本番用キーのみを使用します。

Test mode：テスト用シークレットキーを使用します。実際の料金は請求されません。Yoco のテストカードで支払ってください。デフォルト：オン。実際の決済を受け付けるにはオフにします。オンの間は、お客様には支払い方法の下に Test mode — use a Yoco test card; no real money is charged. と表示されます。

Test secret key：テストモードのシークレットキーです。sk_test_ で始まります。

Live secret key：本番モードのシークレットキーです。sk_live_ で始まります。

想定される接頭辞で始まらないキーは保存されません。ページにはエラーが表示されます（例：Yoco: the test secret key must start with sk_test_ — the previous value was kept.）。ウェブフック登録時に、Yoco がキーは別のモードのものだと報告した場合は、その旨がページに表示されます。

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

ウェブフック

Yoco は支払いと返金の確認を、このセクションの Webhook URL に表示された URL に送信します。フレンドリー URL の場合は、https://your-shop/module/wcp_yoco_pay/webhook のような形になり、/en/ のような言語コードが付く場合もあります。Yoco ポータルでウェブフックを作成する必要はありません。設定を保存すると、モジュールは、シークレットキーはあるがウェブフックシークレットがない各モードについて、URL を Yoco に登録し、署名シークレットをそのモードの欄に保存します。そのモードのシークレットキーまたはウェブフック URL が変更されると、再度登録します。URL が変更された場合、古い登録は削除されます。

各モード（Test と Live）について、このセクションにはウェブフックの状態が表示されます：

モジュールは次のイベントを処理します（これらもこのセクションに記載されています）：

有効な署名のないウェブフックは拒否されます。イベントは支払いが行われたモードのシークレットで署名されている必要があるため、テスト用シークレットが本番の支払いを確認することはありません。URL は設定に表示されたとおりに正確にコピーしてください。ウェブフックはリダイレクトなしでショップに届く必要があります。

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

Live webhook secret：ウェブフックの登録時に自動入力されます。クリアして保存すると、ウェブフックが再登録されます。

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

Clear saved secrets：キーまたはシークレットにチェックを入れ、Save をクリックすると削除されます。空のフィールドは保存された値を保持します。ウェブフックシークレットをクリアして保存すると、ウェブフックが再登録されます。

詳細設定

Debug log：Yoco へのリクエストとウェブフックを、モジュールフォルダ内の logs/yoco_p_debug.log.php に書き込みます。このファイルは Web から開くことはできません。Yoco へのリクエスト失敗や拒否されたウェブフックなどのエラーと警告は、常に記録されます。キー、ウェブフックシークレット、メールアドレスはマスクされます。デフォルト：オフ。

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

Delete data：オンの場合、モジュールをアンインストールすると、設定、ログ、およびモジュールが Yoco に登録したウェブフックが削除されます。注文データ（Yoco チェックアウトと支払いの ID、返金）と注文ステータス Yoco payment on hold は、返金に必要なため常に残ります。デフォルト：オフ。

チェックアウト

支払いステップで、お客様は支払い方法（デフォルトは Card or Instant EFT (Yoco)）を選び、確定します。モジュールはカート合計金額をセント単位にした Yoco チェックアウトを作成し、お客様を Yoco の支払いページに移動させます。そこでお客様はカードまたは Instant EFT で支払います。この時点ではまだ注文は存在しません。

支払い後、お客様はショップに戻ります。注文は Yoco が確認した後にのみ支払い済みになります。モジュールは、お客様が戻ったときと、署名付きウェブフックが届いたときに、Yoco にチェックアウトを問い合わせます。その後注文が作成され、お客様には標準の注文確認ページが表示されます（Your payment with Yoco has been received.）。お客様が戻った時点で Yoco がまだ支払いを確認していない場合は、Payment confirmation ページに We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again. と表示され、Check again ボタンが表示されます。ウェブフックが届き次第、注文が作成されます。

お客様が Yoco のページでキャンセルすると、The Yoco payment was cancelled. Your cart is saved — you can pay again or choose another payment method. と表示されてチェックアウトに戻ります。支払いに失敗した場合は、The Yoco payment was not successful. Please try again or choose another payment method. と表示されます。カートは保持されます。

同じカートで新たに支払いを試みる前に、モジュールは前回の支払いを Yoco で確認します。既に支払い済みであれば、支払いページを表示せずに注文が作成されます。同じ金額で未完了のままで、作成から 30 分以内であれば、お客様には同じ Yoco ページが再度表示されます。それ以外の場合は、新しい 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. と表示されます。

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

支払いは Yoco のページで直ちに請求されます。モジュールには、保存済みカード、サブスクリプションや定期支払い、サイト上のカードフォーム、個別の承認とキャプチャはなく、ZAR 以外の通貨では動作しません。

注文と返金

注文ステータス

No order yet：お客様は Yoco に移動しましたが、まだ支払っていない、Yoco のページでキャンセルした、または Yoco がまだ支払いを確認していません。存在するのはカートのみです。

Payment accepted：支払いが確認されました。支払いは Yoco の支払い ID をトランザクション ID として記録され、メモには金額、Yoco の支払い ID とチェックアウト ID、モード、および支払いがどのように確認されたか（お客様の戻り、ウェブフック、または新しい支払い試行前のチェック）が表示されます。

Yoco payment on hold：Yoco から、カート合計と異なる金額または通貨が報告されました。例えば、支払い開始後に別のタブでカートが変更された場合などです。支払いは記録されず、メモに理由が説明され、お客様には We received your payment and are reviewing it. We will contact you if anything else is needed. と表示されます。発送前に支払いを確認してください。お客様が別の試行で正しい金額を支払った場合、注文は Payment accepted に移ります。

Cancelled or Refunded：このような注文に届いた支払いは、注文を変更しません。メモでは、Yoco ポータルで支払いを返金するか、注文を手動で復元するよう求められます。お客様には Your payment was received after the order had been cancelled. Please contact us — do not pay again. と表示されます。

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

Yoco 支払いブロック

注文ページには Yoco payment ブロックが表示されます。Yoco の支払い ID とチェックアウト ID、ステータス、支払額と返金額、テスト支払い用の Test mode バッジ、返金履歴、カートの支払い試行（複数ある場合）、注文の Yoco notes が含まれます。

返金

Yoco payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Yoco をクリックします。Refund this amount through Yoco? This cannot be undone. の確認に応じてください。全額返金と部分返金に対応しています。注文を編集する権限が必要です。返金は Yoco が請求した金額から行われるため、注文が後で編集されていても、お客様が実際に支払った金額までしか返金できません。返金は支払いが行われたモード（テストまたは本番）で送信されるため、そのモードのシークレットキーが設定されている必要があります。応答が届かなかった後に繰り返された返金は、二重に支払われることはありません。

返金が成功すると、Yoco の返金 ID とともに返金履歴とメモに追加されます。全額返金では注文が Refunded になります。部分返金ではステータスは変わりません。Yoco が返金を拒否すると、ブロックに Yoco refused the refund: と理由が表示され、返金は記録されません。Yoco が返金を保留と報告した場合は、ブロックにまだ保留中であると表示されます。繰り返さないでください。Yoco がウェブフックで確認すると記録されます。返金は Yoco のチェックアウトで支払われた注文に対して利用できます。Yoco payment on hold の注文には返金できる支払い済みチェックアウトがないため、Yoco ポータルで返金してください。

モジュールはクレジットスリップを作成しません。注文ページにある PrestaShop の標準返金ボタンでは、Yoco を通じて返金されません。

Yoco ポータルで行われた返金は、refund.succeeded ウェブフックで届き、返金履歴とメモに記録されます。支払額に達すると、注文は Refunded に設定されます。返金可能な残額を超える返金は記録されず、メモで注文を確認するよう求められます。失敗した返金には、お金がお客様に返金されていないことを示すメモが追加されます。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Yoco が表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在のモードにシークレットキーがあることを確認してください。テストモードでは Test secret key、本番モードでは Live secret key です。カートの通貨は ZAR で、注文合計は R2.00 以上である必要があります。キーがない場合やショップの通貨が ZAR でない場合、設定ページに警告が表示されます。Payment > Preferences で、モジュールが ZAR、お客様の国、お客様の顧客グループに対して許可されているか確認してください。

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

ウェブフックを登録できなかった：お客様がショップに戻れば、支払いは引き続き確認されます。メッセージに表示された理由を修正してください。例えば、ショップが HTTPS でインターネットから到達可能である必要があります。その後、もう一度保存してください。URL を自分で登録し、署名シークレットを貼り付けることもできます。

ウェブフックが拒否される：拒否されたウェブフックはログに記録されます。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 はウェブフックを再送します。

ブラウザでウェブフックの URL に POST だけが表示される：これは正常です。この URL は Yoco からのリクエストのみを受け付けます。

保存時に「The secret key must start with sk_test_ / sk_live_」エラーが出る：キーが誤ったフィールドに貼り付けられています。テスト用キーは sk_test_ で、本番用キーは sk_live_ で始まります。前の値は保持されています。

お客様が Yoco を選ぶときにエラーが表示される：モジュールのページの Log フィールドを確認してください。Yoco is not available at the moment. Please choose another payment method. は、現在のモードにシークレットキーがないことを意味します。

お客様に、支払いの確認が必要だと通知される：試行が異なる金額で支払われた、または注文がキャンセルされた後に支払われた場合です。Yoco payment ブロックのメモを確認し、注文を処理するか、Yoco ポータルで支払いを返金してください。

モードに関するメッセージで返金が失敗する：支払いはテストまたは本番モードで行われ、そのモードのシークレットキーが設定されていません。キーを入力して再試行してください。

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

開発者向け：フック actionYocoPCheckoutPayload を使うと、他のモジュールが Yoco チェックアウトを作成するリクエストを変更できます。

アンインストール

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

Yoco は、それぞれの所有者の商標です。本モジュールは Yoco と提携しておらず、Yoco の推奨も受けていません。