VibeFox Hubtel for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 ～ 9.x。

PHP: cURL 拡張を有効にした 8.0 以降。これらがない場合、モジュールはインストールを拒否します。

通貨: ガーナ・セディ（GHS）のみ。他の通貨では、チェックアウトで決済方法が表示されません。Hubtel は最小単位のペセワ単位で請求するため、GHS 通貨の小数点以下桁数は 2 に設定してください。

Hubtel アカウント: API キー（API ID と API Key）と加盟店アカウント番号（POS Sales ID）を持つ Hubtel ビジネスアカウント。キーは Hubtel のビジネスダッシュボード bo.hubtel.com の Programmable keys にあります。

IP ホワイトリスト: Hubtel は、ホワイトリストに登録されたサーバー IP アドレスからの要求に対してのみ Transaction Status API に応答します。Hubtel（担当のアカウントマネージャーまたは support@hubtel.com）に、Web サーバーのパブリック IP アドレスをホワイトリストに追加するよう依頼してください。それまでは決済を確認できず、注文も作成されません。

テスト環境なし: Hubtel には公開サンドボックスがありません。すべての決済は本番取引です。

Cron: バックグラウンドでの決済確認のため、モジュールの cron URL を 5 分ごとに呼び出すサーバーの cron ジョブを推奨します（設定を参照）。

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

インストール

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

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

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

4. API ID、API Key、加盟店アカウント番号（POS Sales ID）を入力します。

5. Hubtel サポートに、Transaction Status API 用としてサーバーの IP をホワイトリストに追加するよう依頼します。

6. Configure ページに表示される cron URL を、サーバーの cron に追加します。

7. Enable/Disable をオンにして Save をクリックします。コールバック URL はすべての決済とともに Hubtel に送信されるため、Hubtel のダッシュボードで設定する必要はありません。

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

設定

すべての設定はモジュールページにあります: Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。項目の上部には、API ID、API Key、加盟店アカウント番号のいずれかが未入力の場合や、ショップの既定通貨が GHS でない場合に警告が表示されます。どちらの場合も、チェックアウトでは Hubtel が非表示になります。また、GHS 通貨で小数点以下 2 桁を超える場合も警告されます。

Hubtel

Enable/Disable: Enable Hubtel payments で決済方法のオン／オフを切り替えます。既定値: オフ。

Title: チェックアウトで購入者に表示される決済方法の名称。注文にも決済方法名として保存されます。既定値: Mobile Money or card (Hubtel)。必須: 空欄の場合は Enter a title for the payment method. というエラーになります。

Description: チェックアウトで決済方法の下に表示されるテキスト。既定値: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. 決済を完了するため Hubtel にリダイレクトされます。

Hubtel API 認証情報

Hubtel のビジネスダッシュボードから API ID と API Key をコピーします: bo.hubtel.com > Programmable keys。加盟店アカウント番号は、お使いの Hubtel アカウントの POS Sales ID です。このセクションには IP ホワイトリストの注意事項も再度表示されます。

API ID (Client ID): Hubtel のプログラマブルキーの API ID。

API Key (Client Secret): Hubtel のプログラマブルキーの API Key。第三者に漏らさないでください。保存済みのキーは再表示されません。フィールドは空欄のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

Merchant account number (POS Sales ID): 決済はこの Hubtel アカウントに入金され、このアカウントを基準に照合されます。

Clear saved API Key: チェックボックスをオンにして Save をクリックすると、保存済みの API Key を削除します。空欄のままであれば保存済みの値は保持されます。

決済の確認

Callback URL: コールバックは、決済が行われたことをショップに通知します。この URL はすべての決済とともに Hubtel に送信されるため、Hubtel のダッシュボードで設定する必要はありません。フレンドリー URL を使用している場合、https://your-shop/module/wcp_hubtel_pay/callback のような形式になり、言語コードが付くこともあります。インターネットからアクセス可能である必要があります。Hubtel をブロックするパスワード保護やファイアウォールがあってはなりません。コールバックは、ショップがメンテナンスモードの間も機能し、ショップの国別制限によってブロックされることもありません。

Hubtel のコールバックは署名されていません。モジュールはコールバックから決済リファレンスのみを取得します。そのリファレンスは、ショップの決済に属するものである必要があります。ステータス、金額、トランザクション ID は常に Hubtel Transaction Status API から取得されます。注文は、この API が決済とその金額を確認した後にのみ支払い済みとして作成されます。

バックグラウンドでの決済確認（cron）: 秘密トークン付きの cron URL です。サーバーの cron から 5 分ごとに呼び出してください（例: curl を使用）。確認されていない決済は、その後自動的に Hubtel と再照合されます。購入者が Hubtel に送られてから 20 分後、決済がまだ未払いであれば 1 時間後に再度、Hubtel に接続できなかった場合は間隔を徐々に延ばしながら最大 5 回まで再試行されます。URL は非公開にしてください。

詳細設定

Debug log: API 呼び出しとコールバックを、モジュールフォルダ内の logs/hubtel_p_debug.log.php に記録します。このファイルは Web から開くことはできません。キーと購入者データは記録されません。エラーと警告は、このオプションがオフでも常に記録されます。既定値: オフ。

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

Delete data on uninstall: オンの場合、モジュールをアンインストールすると、このモジュールの設定とログが削除されます。注文用に保存された Hubtel データと、注文ステータス Hubtel payment on hold は常に残ります。既定値: オフ。

チェックアウト

決済ステップで購入者は決済方法（既定では Mobile Money or card (Hubtel)）を選択し、確定します。モジュールは、カート合計を GHS 建てとした Hubtel のチェックアウトを作成し、購入者を Hubtel の決済ページへ送ります。決済ページには Cart #、カート番号、ショップ名が表示されます。Hubtel のページで、購入者は MTN MoMo、Telecel Cash、AirtelTigo Money、Visa または Mastercard カード、GhQR で支払います。この時点ではまだ注文は存在しません。決済ステップで確定するたびに、独自のリファレンスを持つ新しい決済試行が作成されます。同じカートの以前の Hubtel ページも支払い可能なままです。

支払い後、購入者はショップに戻ります。注文は、Hubtel が Transaction Status API を通じて確認した後にのみ支払い済みとしてマークされます。確認のタイミングは、コールバック、購入者の帰着時のチェック、バックグラウンドのチェック、または注文ページのボタンのいずれかです。コールバックと帰着が同時に到着した場合は順番に処理されるため、注文が二重に作成されることはありません。その後、購入者には標準の注文確認ページが表示されます。注文が保留された場合、ページには Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed. と表示されます。

購入者が戻った時点で Hubtel がまだ決済を確認していない場合、Payment confirmation ページが表示され、We are waiting for Hubtel to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. というメッセージと、Check again および Back to checkout のボタンが表示されます。Hubtel が決済を確認した時点で注文が作成されます。Hubtel がこの決済試行を失敗と報告している場合、購入者は The Hubtel payment was not completed. You can try again or choose another payment method. とともにチェックアウトに戻ります。カートは保持されます。

購入者が Hubtel ページで Cancel を押した場合、モジュールはまず決済が行われていないかを確認します。行われていなければ、購入者は The Hubtel payment was cancelled. You can try again or choose another payment method. とともにチェックアウトに戻ります。カートは保持されます。キャンセルされた Hubtel ページからの後日の決済も引き続き受け付けられます。

Hubtel が決済を開始できない場合、購入者はチェックアウトに留まり、例えば Could not connect to Hubtel. Please try again in a moment.、Hubtel could not start the payment. Please try again or choose another payment method. のような短いメッセージが表示されます。認証情報が誤っている場合は Hubtel payments are not available at the moment. Please choose another payment method. と表示されます。詳細はログに記録されます。

本モジュールは、PrestaShop からの返金、定期購入、カードの保存、ショップ内での決済チャネルの選択には対応していません。

注文

注文ステータス

No order yet: 購入者は Hubtel に送られたものの未払いである、または Hubtel がまだ決済を確認していない状態です。カートのみが存在します。

Payment accepted: GHS でのカート合計と正確に一致する金額の決済が確認された状態です。決済は Hubtel のトランザクション ID とともに記録され、金額、Hubtel トランザクション、決済方法、リファレンスを示すメモが追加されます。

Hubtel payment on hold: Hubtel が報告した支払い金額がカート合計と異なる場合、またはカートが GHS ではない場合です。注文は支払い済みとしてマークされず、Hubtel が実際に受け取った金額が決済として記録され、不一致を説明するメモが追加されます。Hubtel のダッシュボードで決済を確認し、注文を処理するか、手動で返金してください。同じカートの別の試行が後に正しい金額で支払われた場合、注文は Payment accepted に移行します。

すでに支払い済みの注文に対して別の試行も支払われた場合、注文は変更されません。メモにより、Hubtel のダッシュボードで重複分を返金するよう求められます。キャンセル済みまたは返金済みの注文に対する決済は、メモが追加されるだけで、注文が自動的に再開されることはありません。Hubtel が決済を返金済みと報告した場合、注文にメモが追加されます。

Hubtel 決済ブロック

注文ページには、注文のカートに対するすべての決済試行を表示する Hubtel payment ブロックがあります。内容は、日付、リファレンス、Hubtel チェックアウト、金額、Hubtel ステータス、トランザクション、結果です。試行の下には、注文の Hubtel notes が新しいものから順に表示されます。

Check Hubtel payment status ボタンは、注文の最新の試行（最大 5 件、新しいものから順に、注文が支払い済みになった時点で停止）を確認し、結果を適用して、各試行のステータスを示すメモを追加します。結果はブロック内に表示されます。注文を編集する権限が必要です。Modules ページへのアクセス権は必要ありません。このボタンは注文が存在すれば利用できます。注文のない支払い済みカートは、コールバック、購入者の帰着、または cron によって確認されます。

返金

PrestaShop からの返金はサポートされていません。Hubtel のダッシュボードで決済を返金してから、PrestaShop で返金を記録してください。注文ページの標準の PrestaShop 返金ボタンでは、Hubtel を経由して返金されません。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Hubtel が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、API ID、API Key、加盟店アカウント番号が入力されていること、カートの通貨が GHS であることを確認してください。Payment > Preferences で、モジュールが GHS、購入者の国、購入者のグループに対して許可されているかを確認します。認証情報や通貨が誤っている場合、設定ページに警告が表示されます。

決済は完了したが、注文が作成されなかった: 決済を確認できませんでした。Debug log をオンにして、モジュールページの Log 欄を確認してください。ステータス確認で HTTP 401 または 403 が返される場合は、API キーが誤っているか、サーバー IP が Hubtel によりホワイトリスト登録されていないことを意味します。また、コールバック URL がインターネットからアクセス可能であること、cron URL が呼び出されていることも確認してください。Hubtel が応答するようになれば、次のコールバック、バックグラウンドのチェック、または購入者の帰着によって注文が作成されます。

コールバックが Unknown reference を返す: 決済リファレンスが、このショップの決済に属していません。

コールバックが Payment status unavailable を返す: Transaction Status API に接続できなかったか、要求を拒否されたか、またはそのカートが同時に別の要求によって確認されていました。決済は 5 分後にバックグラウンドで再確認されます。

コールバックが Gateway not configured を返す: API ID、API Key、または加盟店アカウント番号が未入力です。入力してください。決済はバックグラウンドで再確認されます。

コールバックが Invalid request または Invalid ClientReference を返す: 要求に有効な Hubtel コールバックが含まれていませんでした。

コールバック URL をブラウザで開くと Method not allowed と表示される: これは正常です。この URL は Hubtel からの要求のみを受け付けます。

Cron URL が Forbidden を返す: URL 内のトークンが誤っています。設定に表示されている cron URL を正確にコピーしてください。

注文が Hubtel payment on hold の状態: Hubtel payment ブロックのメモを確認し（注文ステータスの項を参照）、Hubtel のダッシュボードで決済を確認して、注文を処理するか手動で返金してください。

購入者が Hubtel を選択するとエラーが表示される: Debug log をオンにして、ログを確認してください。API キーが誤っている場合は Hubtel payments are not available at the moment.、接続の問題がある場合は Could not connect to Hubtel. が表示されます。別の通貨のカートの場合は Hubtel accepts payments in Ghana cedis (GHS) only. Please choose another payment method. が表示されます。

開発者向け: actionWcpHubtelPayIcon フックは決済方法のアイコンを変更し、actionWcpHubtelPayPaymentDescription フックは Hubtel ページ上の決済説明を変更します（100 文字まで）。

アンインストール

Modules > Module Manager に進み、VibeFox Hubtel Pay Gateway の横のメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合、このモジュールの設定とログが削除されます。オフの場合、後で再インストールできるようすべての設定が保持されます。注文用に保存された Hubtel データと注文ステータス Hubtel payment on hold は常に保持されます。既存の注文は、決済メモとトランザクション ID を保持します。

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