VibeFox Helcim for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 ～ 9.x。
PHP: 8.0 以降。モジュールは、それより古い PHP バージョンではインストールを拒否します。
HTTPS と PCI DSS: カード情報はチェックアウトで入力され、貴店のサーバーから HTTPS で Helcim に送信されます。カード情報が保存またはログに記録されることはありませんが、貴店のサーバーを通過するため、ストアには SSL 証明書が必要であり、ホスティングは PCI DSS（SAQ D）に準拠している必要があります。
Helcim アカウント: カナダまたは米国の Helcim 加盟店アカウントと、取引処理の権限を持つ API トークン（「設定」を参照）。Helcim は CAD と USD を処理します。Helcim のテスト（開発者）アカウントはテスト用に任意で使用できます。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインでのみ有効です。
インストール
1. バックオフィスで Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後でモジュール一覧から VibeFox Helcim Gateway を見つけて Configure をクリックすることもできます。
3. Configure ページ上部のライセンスブロックで、VibeFox ライセンスキーを License key に入力し、Activate をクリックします（「ライセンスキー」を参照）。
4. Helcim で All Tools > Integrations > API Access Configuration を開き、取引処理の権限（購入、事前承認、キャプチャ、返金）を持つ API アクセスを作成して、そのトークンをコピーします。
5. トークンを Live API token に貼り付けます。Helcim のテストアカウントがある場合は、そのトークンを Test API token に貼り付けます。
6. Transaction type と Account currencies を選択し、Enable / Disable をオンにして Save をクリックします。最初にテストするには、Test mode をオンにしてテストアカウントで支払いを行います。その後、オフにします。
インストール時に、モジュールは 2 つの注文ステータス Helcim payment authorized と Helcim payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい決済モジュールを有効にします。Payment > Preferences で制限できます。
設定
すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Helcim Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上部では、ストアの既定通貨が Account currencies に含まれていない場合、また決済方法が有効な間に現在のモードの API トークンが空の場合に、ページが警告を表示します。この場合、決済方法はチェックアウトで非表示になります。
Helcim
Enable / Disable: Enable Helcim Gateway で決済方法のオン／オフを切り替えます。既定値：off。
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: Test API token（Helcim テストアカウント）を使用します。支払い、キャプチャ、返金は Helcim テストアカウントに送られ、顧客にはテストモードの通知が表示されます。注文のキャプチャと返金は、注文の支払い時のモードのトークンを常に使用します。既定値：off。
Test API token: Helcim テスト（開発者）アカウントの API トークンです。テストモードがオンのときに使用されます。
保存されたトークンは二度と表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。
Clear saved tokens: トークンにチェックを入れて Save をクリックすると削除されます。フィールドが空の場合は保存された値が維持されます。
支払い
Transaction type: カードへの請求方法です。
Account currencies: Helcim アカウントで処理できる通貨です。注文は常にカートの通貨で請求されます。その他の通貨では、決済方法はチェックアウトで非表示になります。
詳細設定
Debug log: API のリクエストとレスポンスを、モジュールフォルダ内の logs/wc_hlg_debug.log.php に書き込みます。このファイルは Web からは開けません。カード番号は末尾 4 桁に省略されます。CVC、有効期限、トークン、氏名、住所、メールアドレス、IP アドレスは決して記録されません。エラー（拒否された支払いまたは失敗した支払い、API エラー、失敗したキャプチャと返金）は、この設定がオフでも常に記録されます。既定値：off。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックするとログが消去されます。
Delete data on uninstall: オンにすると、モジュールのアンインストール時にゲートウェイの設定とログファイルが削除されます。Helcim の取引、返金、注文ステータスは常に残るため、以前に支払われた注文は再インストール後もキャプチャと返金が可能です。既定値：off。
チェックアウト
支払いステップで、顧客は決済方法（既定ではカードアイコン付きの Credit card (Helcim)）を選択し、その下のフォームに Card Number、Expiry (MM/YY)、CVC、Cardholder Name を入力します。テストモードでは、フォームに TEST MODE — payments go to a Helcim test account, no real charges are made. と表示されます。顧客が注文を確定すると、モジュールはカード番号のチェックサム、有効期限が有効で過去でないこと、CVC が 3 桁または 4 桁であること、氏名が入力されていることを確認します。エラーはチェックアウトに表示され、Helcim には何も送信されません。
その後、貴店のサーバーは、カートの通貨でカートの合計金額について、購入または事前承認としてカードを Helcim に送信します。請求先住所、電話番号、メールアドレスは住所確認のために送信されます。支払いは Helcim 上で、カート番号、-PS、短いコードから成る請求書番号で表示されます。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 トークンがない、または Helcim に拒否された場合は 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.、支払いは承認されたものの注文を自動で完了できなかった場合は Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again.。カートは保持されます。技術的な詳細はログに記録されます。
本モジュールは HelcimPay.js も Helcim.js も使用しないため、カード情報は貴店のサーバーを通過します。保存済みカード、定期購入、ACH または銀行振込、Apple Pay、Google Pay、3-D Secure の機能はなく、Helcim ウェブフックもありません。
注文と返金
注文ステータス
No order: カードが拒否された、Helcim が応答しなかった、または顧客がまだ支払っていない状態です。カートのみが存在します。拒否とエラーはログに記録されます。
Payment accepted: 購入が承認された、または事前承認がキャプチャされた状態です。支払いは Helcim トランザクション ID とともに記録され、メモにはトランザクション ID、承認コード、カード種別、末尾 4 桁、モードが表示されます。
Helcim payment authorized: 事前承認が承認された状態です。資金は仮押さえされているだけです。キャプチャするか、全額返金で解除してください。
Helcim payment on hold: Helcim が取引を承認しましたが、その応答の金額、通貨、またはトランザクション ID がカートと一致しない状態です。たとえば一部承認の後や、支払い中にカートが変更された場合です。メモには Helcim response verification FAILED と表示されます。購入の場合、支払いは Helcim が実際に請求した金額で記録されます。注文を処理する前に、Helcim でトランザクションを確認してください。
Refunded: 支払いがモジュールを通じて全額返金された状態です。
Canceled: キャプチャされていない事前承認が解除された状態です。顧客には請求されていません。
すでに注文があるカートに対して 2 回目の取引が承認された場合、注文は変更されません。メモで、Helcim でその取引を確認し、取り消しまたは返金するよう求められます。
Helcim 支払いブロック
注文画面には Helcim payment ブロックが表示され、トランザクション ID（キャプチャ後は事前承認 ID も）、取引の種類とキャプチャの状態、請求書番号、カードと承認コード、承認された金額、注文合計と返金された金額、テスト支払い用の Test mode バッジ、返金履歴、注文の Helcim notes が表示されます。キャプチャと返金には、注文を編集する権限が必要です。
キャプチャ
Helcim payment authorized の注文では、ブロック内の Capture payment をクリックし、Capture the pre-authorized amount through Helcim? を確認します。返金を差し引いた現在の注文合計がキャプチャされます。事前承認された金額より少なくなることはありますが、多くなることはありません。キャプチャは注文の支払い時のモードのトークンを使用します。キャプチャが成功すると、注文は支払い受付済みになり、支払いはキャプチャのトランザクション ID とともに記録されます。キャプチャが失敗した場合、ブロックに理由が表示され、メモに追加されます。
返金
ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Helcim をクリックします。Refund this amount through Helcim? This cannot be undone. を確認します。購入、またはキャプチャ済みの事前承認に対する全額返金と一部返金に対応しており、返金額は Helcim が実際に請求した金額までです。したがって、一部承認の後では、顧客が支払った金額を超えて返金することはできません。未キャプチャの事前承認の場合、ボタンは Release pre-authorization になります。解除できるのは全額のみで、仮押さえが解除され、注文はキャンセル済みになります。
返金は注文の支払い時のモードで送信されるため、そのモードのトークンが設定されている必要があります。返金は Helcim が承認した場合にのみ有効です。Helcim が返金を拒否した場合、ブロックにエラーが表示され、返金は記録されません。成功した返金は、Helcim の返金トランザクション ID とともに返金履歴とメモに追加されます。全額返金すると注文は Refunded になります。一部返金ではステータスは変わりません。タイムアウト後の再試行では、二重に返金されることはありません。
本モジュールはクレジットメモを作成しません。注文画面にある PrestaShop の標準の返金ボタンでは、Helcim を通じて返金されません。モジュールは Helcim ウェブフックを受信しません。Helcim ダッシュボードで行われたキャプチャ、返金、取り消しは PrestaShop に反映されないため、注文画面から実行してください。
ライセンスキー
本モジュールは vibefox.net の VibeFox ライセンスキーで動作します。モジュールの Configure ページ上部にあるライセンスブロック License — VibeFox Helcim Gateway は、Modules > Module Manager > VibeFox Helcim Gateway > Configure ページで設定の上にある最初のブロックです。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはマスク表示されたキー、ステータス（たとえばライセンスの有効期限日と貴店のドメイン）、および次のボタンが表示されます：ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key。その下には Product: presta-payment-helcim の行と、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 のアカウントで解放してください。
有効なキーがない場合、Helcim はチェックアウトで顧客に表示されません。それでも支払いが開始された場合、顧客には This payment method is not available. Please choose another one. と表示されます。PrestaShop のフロントエンドは、バックオフィスにログインしていることを認識しないため、貴店側でもこの決済方法は非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトで試すことはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。すでに行われた支払いは保持され、キャプチャと返金は引き続き機能します。
ライセンスが期限切れになっても、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業中にステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは不要です。モジュールのアンインストールまたはリセットを行うと、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに Helcim が表示されない: ライセンスが有効であること、Enable / Disable がオンであること、現在のモードに API トークン（Live API token、テストモードでは Test API token）があること、カートの通貨が Account currencies のいずれかであることを確認してください。トークンがない場合やストアの通貨が許可されていない場合、設定ページに警告が表示されます。Payment > Preferences で、モジュールがカートの通貨、顧客の国、顧客のグループに対して許可されているか確認してください。
顧客に「We could not confirm your payment」と表示された: Helcim が応答しなかったため、カードに請求された可能性があります。Log フィールドを確認してください。エラーにはカートと Helcim の請求書が記載されています。顧客に再度請求する前に、その請求書を Helcim で確認してください。5 分以内の再試行では元の結果が返され、二重請求はされません。
顧客に「This payment method is temporarily unavailable」と表示される: 現在のモードの API トークンが空であるか、Helcim に拒否されています。ログには、トークンとその権限を確認するよう記載されています。API アクセスに取引処理の権限があることを確認してください。
Helcim の理由で支払いが失敗した: カードや請求情報などの理由で、Helcim がリクエストを拒否しました。詳細はログにあります。
顧客に「Your payment was received, but the order could not be completed」と表示された: Helcim は支払いを承認しましたが、PrestaShop は注文を作成できませんでした（たとえばモジュールが無効になっていた場合）。理由はログにあります。顧客が同じカートを再送信すると、二重請求なしで、承認済みの支払いから注文が作成されます。
注文が Helcim payment on hold になっている: Helcim ブロックのメモを読んでください。Helcim の応答がカートと一致しませんでした（応答の検証に失敗）。Helcim でトランザクションを確認してから、注文を処理するか、支払いを返金してください。
キャプチャできない: キャプチャする金額は 0 より大きく、事前承認された金額を超えてはならず、注文の支払い時のモードのトークンが設定されている必要があります。
返金に失敗する: メッセージを読んでください。キャプチャされていない事前承認は全額でのみ解除できます。モードに関するメッセージは、注文の支払い時のモードのトークンが空であることを意味します。拒否された返金は記録されません。
テスト支払い: テストモードでは、支払い、キャプチャ、返金は Helcim テストアカウントに送られます。注文は支払い時のモードを保持するため、後でモードを切り替えても、その注文のキャプチャと返金は別のアカウントに移されません。
アンインストール
Modules > Module Manager に移動し、VibeFox Helcim Gateway の横のメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合、ゲートウェイの設定とログが削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。Helcim の取引と返金、および注文ステータス Helcim payment authorized と Helcim payment on hold は常に保持されるため、以前に支払われた注文は再インストール後もキャプチャと返金が可能です。既存の注文は、支払いのメモとトランザクション ID を保持します。
Helcim は各所有者の商標です。本モジュールは Helcim と提携しておらず、Helcim による推奨もされていません。