VibeFox Hubtel for WooCommerce — ヘルプ

要件

WordPress: 6.2 以降。

WooCommerce: 8.0 以降、インストールおよび有効化済み。本プラグインは WooCommerce なしでは有効化できません。

PHP: 8.0 以降。

通貨: ガーナ・セディ（GHS）のみ。他の通貨の場合、決済方法はチェックアウト時に非表示になります。Hubtel は整数ペセワ単位で請求するため、WooCommerce の小数点以下の桁数は 2 のまま維持してください。

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

IP ホワイトリスト: Hubtel は、ホワイトリストに登録されたサーバー IP アドレスからのみ Transaction Status API に応答します。Web サーバーのパブリック IP アドレスをホワイトリストに登録するよう、Hubtel（アカウントマネージャーまたは support@hubtel.com）に依頼してください。登録が完了するまで決済は確認できず、注文は支払い待ちのままになります。

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

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

インストール

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

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

3. 設定を開きます: WooCommerce > Settings > Payments > Hubtel > Manage を開くか、プラグイン一覧ページでプラグイン名の下にある Settings をクリックします。

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

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

6. Transaction Status API 用にサーバー IP をホワイトリストに登録するよう Hubtel サポートに依頼します。

7. Enable/Disable を有効にします。コールバック URL は決済ごとに Hubtel に送信されるため、Hubtel ダッシュボードでの設定は不要です。

設定

すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > Hubtel。フィールドの上部では、API ID、API Key、または加盟店アカウント番号が不足している場合や、ストア通貨が GHS ではない場合に警告が表示されます。どちらの場合も、チェックアウト時に Hubtel は非表示になります。また、ストアで小数点以下の桁数が 2 を超えている場合にも警告が表示されます。決済方法一覧では、認証情報が入力されるまで要設定としてマークされます。

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

Title: 購入者がチェックアウト時に目にする決済方法の名称。既定値: Mobile Money or card (Hubtel)。

Description: チェックアウト時に決済方法の下に表示される説明文。既定値: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. You will be redirected to Hubtel to complete the payment.

Hubtel API 認証情報

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

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

API Key (Client Secret): Hubtel プログラマブルキーの API Key。厳重に保管してください。

Merchant account number (POS Sales ID): 決済はこの Hubtel アカウントに回収され、このアカウントと照合されます。

支払いの確認

コールバックによって、支払いが完了したことがストアに通知されます。このセクションに表示されるコールバック URL は各決済とともに Hubtel に送信されるため、Hubtel ダッシュボードでの設定は不要です。URL は https://your-site/wc-api/hubtel_pay/ のようになります。インターネットからアクセス可能である必要があります（メンテナンスモード、パスワード保護、Hubtel をブロックするファイアウォールなどがないこと）。

Hubtel のコールバックは署名されていません。プラグインはコールバックから決済リファレンスのみを取得し、そのリファレンスはストアの注文に属している必要があります。ステータス、金額、取引 ID は常に Hubtel の Transaction Status API から取得されます。注文は、この API が支払いとその金額を確認した後にのみ支払い済みとしてマークされます。Hubtel に接続できない場合、支払いはバックグラウンドで自動的に再確認され、注文画面から Order actions > Check Hubtel payment status を使用して手動で確認することも可能です。

詳細設定

Debug log: キーや購入者データを除外し、WooCommerce > Status > Logs（ソース: wcp_hubtel_pay）に Log API calls and callbacks を記録します。エラーは常にログに記録されます。既定値: オフ。

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Hubtel data saved on orders is kept)。既定値: オフ。

チェックアウト

購入者は決済方法（デフォルトでは Mobile Money or card (Hubtel)）を選択し、注文を確定します。プラグインは注文合計の GHS 金額で Hubtel チェックアウトを作成し、購入者を Hubtel 決済ページに転送します。決済は画面上に Order #、注文番号、およびサイト名として表示されます。Hubtel ページで購入者は MTN MoMo、Telecel Cash、AirtelTigo Money、Visa または Mastercard カード、GhQR で支払います。Place order または Pay をクリックするたびに独自のリファレンスを持つ新しい決済試行が作成され、同一注文の以前の Hubtel ページも引き続き支払い可能です。

支払い後、購入者は注文完了ページに戻ります。注文は、Hubtel が Transaction Status API 経由で確認した後にのみ支払い済みとしてマークされます。これは、コールバック、購入者の戻り時のチェック、バックグラウンドチェック、または注文のアクションによって行われます。同時に届いたコールバックと戻り処理は順次処理されるため、注文が二重に完了することはありません。Hubtel がまだ支払いを確定していない場合、ページには 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. と表示されます。注文が保留中になった場合は、Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed. と表示されます。

購入者が Hubtel ページで Cancel を押した場合、プラグインはまず支払いが既に行われていないかを確認します。支払いが行われていない場合、購入者は The Hubtel payment was cancelled. You can try again or choose another payment method. というメッセージとともに Pay for order ページに戻ります。

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.。詳細はログに記録されます。

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

本プラグインは WooCommerce からの返金、定期購入、カードの保存、WooCommerce 内での決済チャネルの選択には対応していません。

注文

注文ステータス

Pending payment: 購入者が Hubtel に転送され、まだ支払っていないか、Hubtel がまだ支払いを確定していません。

Processing: 支払いが確認されました。バーチャルかつダウンロード可能な商品のみを含む注文は、WooCommerce のデフォルト動作として完了になります。注文メモには金額、Hubtel 取引、決済方法、リファレンスが表示されます。取引 ID は Hubtel の取引 ID です。

On hold: Hubtel から注文合計と異なる支払い金額が報告されたか、注文が GHS 建てではない場合（メモ: Hubtel amount/currency mismatch）、またはキャンセル済みの注文に対して支払いがあった場合です。注文は支払い済みとしてマークされません。Hubtel ダッシュボードで支払いを確認し、手動で注文を完了または返金してください。

Failed: 支払い待ちの注文に対する最新の決済試行が失敗したと Hubtel が報告し、Transaction Status API でも未払いであることが確認された場合です。購入者は注文から再度試行できます。コールバックのみによって報告された失敗によって注文が失敗になることはありません。

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

支払いの確認処理

購入者が Hubtel に転送されてから約 20 分後、コールバックが失われ、かつ購入者が戻らなかった場合に備えて、バックグラウンド処理（WooCommerce Action Scheduler）が Hubtel に支払いを照会します。未払いの試行は 1 時間後にもう一度確認されます。Hubtel API に接続できない場合、間隔を広げながら最大 5 回まで確認が再試行されます。

注文のアクション Check Hubtel payment status は、注文の最新の試行（最新のものから最大 5 件）を確認し、結果を適用して各試行のステータスを含むメモを追加します。

返金

WooCommerce からの返金には対応していません。Hubtel ダッシュボードで支払いを返金し、その後 WooCommerce で手動の返金を登録してください。

ライセンスキー

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

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

有効なキーがない場合、チェックアウト時に購入者へ Hubtel は表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。ログイン中のストア管理者には、キーを購入する前にプラグインを設定・テストできるよう、(unlicensed — visible to admins only) と表示された状態で決済方法が引き続き表示されます。プラグイン一覧ページおよび WooCommerce の各ページにリマインダーが表示されます。既存の注文への影響はありません（既に開始されている決済は引き続き確認されます）。

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

トラブルシューティング

Hubtel がチェックアウト時に表示されない: ライセンスが有効であること、Enable/Disable がオンであること、API ID、API Key、加盟店アカウント番号が入力されていること、通貨が GHS であることを確認してください。Pay for order ページでは注文の通貨が基準になります。認証情報や通貨が間違っている場合、設定ページに警告が表示されます。

支払いは完了したが、注文が支払い待ちのままになっている: 支払いが確認できませんでした。WooCommerce > Status > Logs（ソース: wcp_hubtel_pay）を開いてください。ステータス確認時の HTTP 401 または 403 は、API キーが間違っているか、サーバー IP が Hubtel のホワイトリストに登録されていないことを意味します。また、コールバック URL がインターネットからアクセス可能であることも確認してください。修正後、注文を開いて Order actions > Check Hubtel payment status を実行します。Hubtel から応答があれば、バックグラウンドチェックでも注文が確認されます。

コールバックが Unknown reference と応答する: 決済リファレンスがこのストアの注文に属していません。

コールバックが Payment status unavailable と応答する: Transaction Status API に接続できなかったか、リクエストが拒否されました。支払いはバックグラウンドで再確認されます。

注文が金額/通貨の不一致のメモとともに保留中になっている: Hubtel から注文合計と異なる支払い金額が報告されたか、注文が GHS 建てではありません。Hubtel ダッシュボードで支払いを確認し、手動で注文を完了または返金してください。

注文時に購入者にエラーが表示される: Debug log をオンにしてログを確認してください。API キーが間違っていると Hubtel payments are not available at the moment. が表示されます。接続に問題がある場合は Could not connect to Hubtel. が表示されます。

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

開発者向け: hubtel_p_icon フィルターで決済方法アイコンを変更でき、hubtel_p_payment_description で Hubtel ページ上の決済説明（最大 100 文字）を変更できます。

アンインストール

プラグインを無効化してもすべてのデータは保持されます。保留中のバックグラウンド決済確認のみがキャンセルされます。削除するには、Plugins ページで無効化してから削除してください。このプラグインのライセンスキーとライセンスステータスは常に削除されます。ゲートウェイの設定、プラグイン固有のオプション、保留中のバックグラウンドチェック、およびログは、Delete data on uninstall がオンの場合にのみ削除されます。それ以外の場合は、将来の再インストールのために残ります。注文に保存された Hubtel データは支払い履歴であり、常に保持されます。既存の注文は支払いメモと取引 ID を維持します。

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