VibeFox Helcim for WooCommerce — ヘルプ

要件

WordPress: 5.8 以降。

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

PHP: 8.0 以降。

HTTPS と PCI DSS: カード情報はチェックアウト時に入力され、サーバーから HTTPS 経由で Helcim に送信されます。これらが保存またはログに記録されることはありませんが、貴店のサーバーを通過するため、ストアには SSL 証明書が必要であり、ホスティング環境は PCI DSS（SAQ D）に準拠している必要があります。

Helcim アカウント: カナダまたは米国の Helcim 加盟店アカウント、および取引処理権限を持つ API トークン（設定を参照）。Helcim は CAD と USD を処理します。テスト用の Helcim テスト（開発者）アカウントは任意です。

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

インストール

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

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

3. Helcim で All Tools > Integrations > API Access Configuration を開き、取引処理権限（購入、事前承認、キャプチャ、返金）を持つ API アクセスを作成して、そのトークンをコピーします。

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

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

6. トークンを Live API token に貼り付け、Helcim テストアカウントをお持ちの場合はそのトークンを Test API token に貼り付けます。

7. Transaction type と Account currencies を選択し、Enable / Disable をオンにして保存します。最初にテストを行うには、Test mode をオンにしてテストアカウントで支払いを行い、その後オフにします。

設定

すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > Helcim。ストアの通貨が Account currencies のいずれでもない場合、およびゲートウェイが有効になっているにもかかわらず現在のモードの API トークンが空の場合、フィールドの上部に警告が表示されます。どちらの場合も、チェックアウト時にゲートウェイは非表示になります。決済方法一覧では、現在のモードにトークンが設定されるまで、ゲートウェイには要設定のマークが付けられます。

Enable / Disable: Enable Helcim Gateway は決済方法の有効/無効を切り替えます。既定値: 無効。

Title: チェックアウト時に表示される決済方法のタイトル。既定値: Credit card (Helcim)。

Description: チェックアウト時に表示される決済方法の説明。既定値: Pay securely with your credit card。

API 認証情報

Helcim で All Tools > Integrations > API Access Configuration に進み、API アクセスを作成してトークンをコピーします。購入、事前承認、キャプチャ、返金の取引処理権限を付与してください。Helcim テストアカウントは本番アカウントと同じ API アドレスを使用するため、テストモードでは単に Helcim テストアカウントのトークンを使用します。

Live API token: 本番 Helcim アカウントの API トークン。テストモードがオフのときに使用されます。

Test mode: Use the Test API token (Helcim test account)。支払い、キャプチャ、返金は Helcim テストアカウントに送信され、購入者にはテストモードの通知が表示されます。注文の返金とキャプチャには、その注文の支払いに使用されたモードのトークンが常に使用されます。既定値: 無効。

Test API token: Helcim テスト（開発者）アカウントの API トークン。テストモードがオンのときに使用されます。

支払い

Transaction type: カードへの請求方法。

Account currencies: Helcim アカウントで処理可能な通貨。注文は常に注文通貨で請求されます。その他の通貨では、チェックアウト時にゲートウェイが非表示になります。

詳細設定

Debug log: Log API requests and responses を WooCommerce > Status > Logs（ソース: wcp_helcim_gateway）に記録します。カード番号は下 4 桁に短縮されます。CVC、有効期限、トークン、氏名、住所、メールアドレス、IP アドレスは一切記録されません。既定値: 無効。

Delete data on uninstall: Remove the gateway settings, its own options (wc_hlg_*) and its log files when the plugin is deleted. 既定値: 無効。

チェックアウト

購入者は決済方法（デフォルトでは Credit card (Helcim)）を選択し、チェックアウト画面で Card Number、Expiry (MM/YY)、CVC、Cardholder Name を入力します。タイトルの横には Visa、Mastercard、American Express、Discover のアイコンが表示されます。テストモードでは、フォームに TEST MODE — payments go to a Helcim test account, no real charges are made. と表示されます。送信前に、プラグインはカード番号のチェックサム、有効期限が有効で過去でないこと、CVC が 3 桁または 4 桁であること、氏名が入力されていることを検証します。

注文が行われると、サーバーは注文通貨での注文合計金額に対する購入または事前承認としてカード情報を Helcim に送信します。請求先住所、電話番号、メールアドレスは住所確認のために送信されます。支払いは Helcim 上で、注文番号とショートコードで構成されたインボイス番号とともに表示されます。Helcim は同じリクエスト内で応答します。Helcim が取引を承認し、承認された金額と通貨が注文と一致した場合にのみ注文が支払い完了としてマークされます。その後、購入者は注文完了ページに移動します。

注文ごとに同時に実行される支払い試行は 1 回のみであり、すでに支払われた注文に再度請求されることはありません。すべての試行で冪等性キーが使用されます。Helcim が応答しない場合、注文は支払い待ちのままとなり、5 分以内の再試行ではカードに二重請求する代わりに元の Helcim の結果が返されます。

購入者に表示される可能性のあるメッセージ: Helcim が拒否した場合の Your card was declined. Please check the card details or use another card.、その他の拒否されたリクエストに対する Helcim の理由付き Payment failed:、Helcim が応答しない場合の We could not confirm your payment with the card processor. Please try again in a minute; if the problem persists, contact us before using another card.、API トークンが見つからないか拒否された場合の This payment method is temporarily unavailable. Please choose another payment method.、重複送信時の Your payment is already being processed. Please wait a moment and check your e-mail before trying again.。技術的な詳細は注文メモとログに記録されます。

この決済方法は、クラシックチェックアウト、チェックアウトブロック（同一のカードフィールド）、および Pay for order ページで動作します。WooCommerce 高性能注文ストレージ（HPOS）と互換性があります。

本プラグインは HelcimPay.js や Helcim.js を使用しないため、カード情報は貴店のサーバーを通過します。保存済みカード、定期購入、ACH または銀行振込、Apple Pay、Google Pay、3-D Secure には対応しておらず、Helcim ウェブフックも受信しません。

注文と返金

注文ステータス

Pending payment: 支払いが拒否されたか、まだ確定していません。Helcim が応答しなかった場合、注文メモには購入者に再度請求する前に Helcim のインボイスを確認するよう記載されます。

Processing: 購入が承認されたか、事前承認がキャプチャされました。仮想のダウンロード可能商品のみの注文は、WooCommerce の既定どおり「完了」になります。注文メモには、取引 ID、承認コード、カードの種類、下 4 桁、モードが表示されます。取引 ID は Helcim の取引 ID です。

On hold (pre-authorization): 資金は仮押さえされているだけです。注文アクションでキャプチャするか、全額返金して解除します。

On hold after payment: Helcim は取引を承認しましたが、応答の金額、通貨、または取引 ID が注文と一致しません。メモには Helcim response verification FAILED と表示されます。注文を処理する前に Helcim で取引を確認してください。

キャプチャ

注文（ステータス「保留中」）を開き、注文アクションの Capture Helcim pre-authorization を選択して Update をクリックします。返金額を差し引いた現在の注文合計金額がキャプチャされます。承認された金額を下回ることは可能ですが、上回ることはできません。キャプチャには、注文の支払いに使用されたモードのトークンが使用されます。キャプチャが成功すると、注文は処理中に変わり、取引 ID はキャプチャ取引のものに変更されます。キャプチャが失敗した場合、その理由が表示され、注文メモに追加されます。

返金

注文を開き、Refund をクリックして金額を入力し、Refund via Credit card (Helcim) をクリックします（ボタンには設定した Title が表示されます）。購入またはキャプチャ済みの事前承認の全額返金および一部返金に対応しています。未キャプチャの事前承認は全額返金のみ可能です。仮押さえが解除され、購入者に請求は発生しません。返金は注文の支払いに使用されたモードで送信されるため、そのモードのトークンが設定されている必要があります。Helcim が承認した場合にのみ有効となります。Helcim が拒否した場合、WooCommerce にエラーが表示され、返金は記録されません。返金が成功すると、Helcim の返金取引 ID とともに注文メモに追加されます。タイムアウト後の再試行によって二重に返金されることはありません。

本プラグインは Helcim ウェブフックを受信しません。Helcim ダッシュボードで行われたキャプチャ、返金、取り消しは WooCommerce に反映されないため、WooCommerce から実行してください。

ライセンスキー

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

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

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

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

トラブルシューティング

チェックアウト時に Helcim が表示されない: ライセンスが有効であること、Enable / Disable がオンになっていること、現在のモードに API トークン（本番では Live API token、テストモードでは Test API token）があること、およびカートの通貨が Account currencies のいずれかであることを確認してください。Pay for order ページでは注文通貨が適用されます。どちらの場合も設定ページに警告が表示されます。

Helcim が応答せず、注文が支払い待ちのままになっている: カードに請求されている可能性があります。購入者に再度請求する前に、注文メモを読み、Helcim のインボイスを確認してください。5 分以内の再試行では元の結果が返され、二重請求されることはありません。

購入者に「This payment method is temporarily unavailable」と表示される: 現在のモードの API トークンが空であるか、Helcim によって拒否されました。注文メモには、トークンとその権限を確認するよう記載されています。API アクセスに取引処理権限があることを確認してください。

Helcim の理由により支払いが失敗した: カードや請求先情報などが原因で、Helcim がリクエストを拒否しました。詳細は注文メモに記載されています。

支払い後に注文が「保留中」になっている: 注文メモをお読みください。注文は事前承認されておりキャプチャ待ちであるか、Helcim の応答が注文と一致しませんでした（応答の検証に失敗しました）。

キャプチャができない: キャプチャする金額は 0 より大きく、承認された金額以下である必要があり、注文の支払いに使用されたモードのトークンが設定されている必要があります。

返金が失敗する: メッセージをお読みください。未キャプチャの事前承認は全額返金のみ可能です。モードに関するメッセージは、注文の支払いに使用されたモードのトークンが空であることを意味します。拒否された返金は記録されません。

テスト支払い: テストモードでは、支払い、キャプチャ、返金が Helcim テストアカウントに送信されます。注文は支払われたモードを保持するため、後からモードを切り替えても、そのキャプチャや返金が別のアカウントに移行することはありません。

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

開発者向け: フィルター wc_hlg_supported_currencies は通貨リストを変更し、wc_hlg_card_brands はチェックアウト時のカードアイコンを変更します。

アンインストール

プラグインを無効化してもすべてのデータは保持されます。削除するには、Plugins ページで無効化してから削除します。このプラグインのライセンスキーとライセンスステータスは常に削除されます。ゲートウェイ設定、プラグイン独自のオプション、ログは、Delete data on uninstall がオンになっていた場合にのみ削除されます。それ以外の場合は、将来の再インストールのために残されます。注文データは注文履歴の一部であり、削除されることはありません。既存の注文は支払いメモと取引 ID を保持します。

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