VibeFox Helcim for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 で動作確認済み）または 4.0.2 以降（4.1.0.3 で動作確認済み）。

PHP: 8.0 以降。

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

通貨: Helcim は CAD と USD で決済を処理します。決済方法は、チェックアウトの通貨が拡張機能で設定された Account currencies のいずれかである場合にのみ表示されます。

Helcim アカウント: カナダまたは米国の Helcim 加盟店アカウントと、トランザクション処理の権限を持つ API トークン（Configuration を参照）。Helcim のテスト（developer）アカウントはテスト用に任意で使用できます。

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

インストール

ダウンロードファイルは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで展開してください。README.txt、OpenCart 3 用パッケージの wcp_helcim_gateway-oc3-(version).ocmod.zip、OpenCart 4 用パッケージの wcp_helcim_gateway.ocmod.zip が含まれています。お使いの OpenCart バージョンのパッケージのみをインストールしてください。ライセンスキーは両方のバージョンで同じです。

OpenCart 3

1. 管理画面で Extensions > Installer を開き、Upload をクリックして wcp_helcim_gateway-oc3-(version).ocmod.zip を選択します。この拡張機能には OCMOD の変更がないため、Extensions > Modifications を更新する必要はありません。インストーラーを使う代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。

2. Extensions > Extensions に移動し、タイプ Payments を選択します。VibeFox Helcim Gateway を見つけて Install（緑色の + ボタン）をクリックします。管理者ユーザーには、支払い拡張機能の一覧を変更する権限が必要です。

3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。ページ上部のライセンスブロックの License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（License key を参照）。

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 をオンにしてテストアカウントで支払いを行い、その後オフにします。

OpenCart 4

1. 管理画面で Extensions > Installer を開き、Upload をクリックして wcp_helcim_gateway.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。

2. パッケージは同じページの、インストール済み拡張機能の一覧に表示されます。その横の Install（緑色の + ボタン）をクリックします。

3. Extensions > Extensions に移動し、タイプ Payments を選択します。VibeFox Helcim Gateway を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックします。

4. ライセンスキー、API トークン、決済設定を、OpenCart 3 の手順 3 から 6 と同じように入力します。設定ページとそのフィールドは、両方のバージョンで同じです。

新規インストール時は、決済方法がオフ、テストモードもオフの状態で始まります。

設定

すべての設定は拡張機能のページにあります: Extensions > Extensions > Payments > VibeFox Helcim Gateway > Edit。セクションは左側に一覧表示され、一覧の下にある Save ボタンでページ全体を保存します。設定の上部では、ストアの既定通貨が Account currencies に含まれていない場合（その場合、Helcim は許可された通貨の注文に対してのみ提供されます）に警告が表示され、決済方法が有効な間に現在のモードの API トークンが空の場合にも警告が表示されます（その場合、決済方法はチェックアウトで非表示になります）。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。

保存時には、Title を空にすることはできず（最大 128 文字）、Sort Order は整数、Total は 0 以上の数値でなければならず、すべての注文ステータスが存在している必要があります。いずれかに誤りがある場合は何も保存されず、ページにエラーが一覧表示されます。

Helcim

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

Title: チェックアウトに表示される決済方法のタイトル。注文に保存される決済方法名にもなります。既定値: Credit card (Helcim)。必須。

Description: Confirm Order のステップで、カードフォームの上に顧客に表示されるテキスト。既定値: Pay securely with your credit card.

Sort Order: チェックアウトにおける決済方法の表示順。空欄のままにするか、整数を入力します。

Geo Zone: 選択した地域（Geo Zone）内の支払い先住所に対してのみカードフォームを提供します。既定値: All zones。Geo Zone は System > Localisation > Geo Zones で設定します。

Total: 決済方法を提供するために注文が達している必要がある、ストアの既定通貨でのチェックアウト金額。空欄にすると、どの金額でも提供されます。

API 認証情報

Helcim で All Tools > Integrations > API Access Configuration に移動し、API アクセスを作成してそのトークンをコピーします。購入、事前承認、キャプチャ、返金に対するトランザクション処理の権限を付与してください。Helcim のテストアカウントは本番アカウントと同じ API アドレスを使用するため、テストモードでは Helcim のテストアカウントのトークンを使うだけで済みます。このセクションには Helcim API ドキュメントへのリンクがあります。

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

Test mode: Test API token（Helcim テストアカウント）を使用します。支払い、キャプチャ、返金は Helcim のテストアカウントに送られ、顧客にはテストモードの通知が表示されます。注文のキャプチャと返金は、常にその注文が支払われたモードのトークンを使用します。既定値: オフ。

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

保存されたトークンは再度表示されることはありません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ新しい値を入力してください。保存済みのトークンを削除するには、フィールドの下にある Clear the saved token on save にチェックを入れ、Save をクリックします。

支払い

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

Account currencies: Helcim アカウントで処理できる通貨。注文は常に注文の通貨で請求されます。その他の通貨の場合、決済方法はチェックアウトで非表示になります。

注文

注文は Confirm Order のステップでステータスなし（注文の欠落）として作成され、Helcim がカードを承認した後にのみステータスを取得します。各フィールドには、OpenCart の注文ステータスが一覧表示されます。

Order Status After Payment: カードに請求された（購入、または事前承認のキャプチャ）。既定値: Processing。

Authorized Status: 事前承認: 資金は確保されているだけで、まだ請求されていません。注文のタブの Capture payment でキャプチャしてください。既定値: Pending。OpenCart に On hold ステータスがないためです。

On Hold (Review) Status: Helcim の応答が注文と一致しない（部分承認、別の通貨、トランザクション ID がない、または注文合計が請求額と異なる）場合。注文を処理する前に Helcim でトランザクションを確認してください。メモに理由が記載されます。既定値: Pending。承認済みの注文と確認が必要な注文を区別するため、System > Localisation > Order Statuses で独自のステータスを作成できます。

Canceled Status: 未キャプチャの事前承認が注文のタブから解除された（顧客には請求されていない）。既定値: Canceled。

Refunded Status: 注文のタブで支払いが全額返金された後に設定されます。既定値: Refunded。

詳細設定

Debug log: API のリクエストとレスポンスを、OpenCart のログフォルダ（storage/logs）にある wc_hlg_debug.log.php に書き込みます。このファイルは Web から開くことはできません。カード番号は下 4 桁に短縮されます。CVC、有効期限、トークン、氏名、住所、メールアドレス、IP アドレスは記録されることはありません。エラー（拒否または失敗した支払い、API エラー、失敗したキャプチャと返金）は、この設定がオフでも常に記録されます。既定値: オフ。

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

Delete data on uninstall: オンの場合、拡張機能をアンインストールするとゲートウェイの設定とログファイルが削除されます。Helcim のトランザクションと返金は常に残るため、以前に支払われた注文は再インストール後もキャプチャや返金が可能です。既定値: オフ。

インポート / エクスポート

Export: Download JSON で設定を JSON ファイルとして保存します。API トークンはエクスポートされません。

Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定を復元します。保存済みの API トークンは保持されます。

チェックアウト

Payment Method のステップで、顧客は決済方法を選択します（既定では Credit card (Helcim)）。Confirm Order のステップでは、顧客にカードアイコン、貴店の説明、そして Card Number、Expiry (MM/YY)、CVC、Cardholder Name を含むフォームが表示されます。テストモードでは、フォームに TEST MODE — payments go to a Helcim test account, no real charges are made. と表示されます。OpenCart はこのステップで注文を作成しますが、まだステータスはありません。顧客が Confirm Order をクリックすると、拡張機能はカード番号のチェックサム、有効期限が有効で過ぎていないこと、CVC が 3 桁または 4 桁であること、氏名が入力されていることを確認します。エラーはフォームの上に表示され、Helcim には何も送信されません。

OpenCart 4 では、顧客は決済方法ブロックの Choose ボタンを押し、Payment method options のウィンドウで決済方法を選択します。その後、カードフォームは、チェックアウトページ下部の注文確認ブロック内、Confirm Order ボタンの上に表示されます。既定では、OpenCart 4 は支払い先住所を尋ねません。そのため、拡張機能は住所確認のために、配送先住所をカード名義人とともに Helcim に送信します。

その後、貴店のサーバーは、注文通貨での注文合計について、カードを購入または事前承認として Helcim に送信します。カード名義人、支払い先住所、電話番号、メールアドレスは、住所確認のために送信されます。支払いは、Helcim では注文番号、-OC、短いコードで構成された請求書番号とともに表示されます。Helcim は同じリクエストで応答します。注文は、Helcim がトランザクションを承認した後にのみステータスを取得します。これは OpenCart の標準的な方法で、通常の注文メールが送信され、在庫も更新されます。カートはすぐに空になり、顧客は OpenCart の注文完了ページに移動します。

カートごとに同時に実行される支払い試行は 1 回だけです。支払い済みのカートは、その間に OpenCart が新しい注文を作成していても再度請求されることはありません（OpenCart 3 では、Confirm Order のステップが表示されるたびに新しい注文が作成されます。OpenCart 4 では、以前の注文や別のブラウザタブが、同じカートを保持している場合があります）。OpenCart 4 はチェックアウト用の注文を 1 つだけ保持して更新するため、カードが拒否された後も、顧客は同じ注文で支払いを行います。その注文がその間に終了されていた場合（例: 貴店が注文をキャンセルした場合）、または既に支払い済みで、カートに新しい商品が入っている場合は、Confirm Order を選択すると、顧客はチェックアウトページに戻され、その上に Your previous order is already closed (cancelled or refunded by the store) or paid for another cart. Please confirm the order again: the cart will be paid with a new order. と表示されます。次の Confirm Order では、カートの新しい注文に対して支払いが行われます。数量の変更を含め、カートを変更すると新しいカートとみなされ、それ専用の支払いが必要になります。すべての試行には冪等性キーが使用されます。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.、支払いは受け付けられたが注文を自動的に完了できなかった場合は Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again.。顧客は同じカートのまま Confirm Order のステップにとどまります。技術的な詳細はログに記録されます。

この拡張機能は HelcimPay.js や Helcim.js を使用しないため、カード情報は貴店のサーバーを経由します。保存済みカード、サブスクリプション、ACH や銀行振込による支払い、Apple Pay、Google Pay、3-D Secure には対応しておらず、Helcim のウェブフックもありません。

注文と返金

注文ステータス

ステータスなし（注文の欠落）: カードが拒否された、Helcim が応答しなかった、または顧客がまだ支払っていない場合。拒否とエラーはログに記録され、メモとして追加されます。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定した場合にのみ表示されます。

Order Status After Payment（既定 Processing）: 購入が承認された、または事前承認がキャプチャされた。メモには、トランザクション ID、承認コード、カードの種類、下 4 桁、モードが表示されます。

Authorized Status（既定 Pending）: 事前承認が承認された。資金は確保されているだけです。キャプチャするか、全額返金で解除してください。

On Hold (Review) Status（既定 Pending）: Helcim がトランザクションを承認したが、その応答の金額、通貨、またはトランザクション ID が注文と一致しない。たとえば部分承認の後や、支払い中に注文合計が変わった場合です。メモには Helcim response verification FAILED と記載されます。注文を処理する前に、Helcim でトランザクションを確認してください。

Refunded Status（既定 Refunded）: 支払いは拡張機能を通じて全額返金されました。

Canceled Status（既定 Canceled）: 未キャプチャの事前承認が解除されました。顧客には請求されていません。

メモは注文の History に記録されるエントリで、顧客には表示されません。

VibeFox Helcim Gateway タブ

Sales > Orders で、Helcim で支払われた注文を開きます。注文ページの下部、History と Additional の隣に表示される VibeFox Helcim Gateway タブには、Transaction ID（キャプチャ後は事前承認 ID も）と、テスト支払いの場合は Test mode ラベル、Transaction type とキャプチャの状態、Invoice、Card と承認コード、Approved / order / refunded の金額、キャプチャボタンと返金フォーム、返金履歴、注文の Helcim notes が表示されます。このタブは拡張機能へのアクセス権を持つユーザーに表示されます。キャプチャと返金には変更権限が必要です（System > Users > User Groups で設定）。

キャプチャ

未キャプチャの事前承認の場合は、タブの Capture payment をクリックし（ボタンに金額が表示されます）、Capture the pre-authorized amount through Helcim? を確認します。返金を差し引いた現在の注文合計がキャプチャされます。これは承認された金額より少なくなることはあっても、多くなることはありません。キャプチャには、その注文が支払われたモードのトークンが使用されます。キャプチャが成功すると、注文は Order Status After Payment になります。キャプチャが失敗した場合、タブには理由が表示され、メモにも追加されます。

返金

タブで Amount を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて Reason (optional) も入力し、Refund via Helcim をクリックします。Refund this amount through Helcim? This cannot be undone. を確認してください。購入またはキャプチャ済みの事前承認について、全額返金と部分返金に対応しており、上限は Helcim が実際に請求した金額です。そのため、部分承認の後に顧客が支払った金額を超えて返金することはできません。未キャプチャの事前承認の場合、ボタンは Release pre-authorization になります。解除できるのは全額のみで、確保は取り消され、注文は Canceled Status になります。

返金は注文が支払われたモードで送信されるため、そのモードのトークンが設定されている必要があります。返金は、Helcim が承認した場合にのみ有効になります。Helcim が拒否した場合は、タブにエラーが表示され、返金は記録されません。成功した返金は、Helcim の返金トランザクション ID とともに返金履歴とメモに追加されます。全額返金すると、注文は顧客に通知されず、商品も在庫に戻されずに Refunded Status になります。これは手動でステータスを変更した場合と同じです。部分返金ではステータスは変わりません。タイムアウト後の再試行で二重に返金されることはありません。

Sales > Returns での商品返品では、Helcim を通じて返金されることはありません。この拡張機能は Helcim のウェブフックを受信しません。Helcim のダッシュボードで行われたキャプチャ、返金、取り消しは OpenCart に反映されないため、注文ページから行ってください。

ライセンスキー

この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Helcim Gateway は、Extensions > Extensions > Payments > VibeFox Helcim Gateway > Edit の最初のブロックで、設定の上にあります。キーを License key に貼り付けて Activate をクリックします。その後、このブロックには、マスクされたキー、ステータス（例: ライセンスの有効期限日と貴店のドメイン）、そして Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には Product: opencart-payment-helcim の行と、vibefox.net のアカウントを開くリンク Manage licenses and domains in your account があります。キーを変更できるのは、この拡張機能に対する Modify 権限を持つ管理者ユーザーだけです。ブロックのテキストは管理画面の言語に従います（英語とロシア語が含まれます）。

キーが受け付けられない場合、ブロックには理由が表示されます。例: Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認されたステータスで動作を続けます。

1 つのキーは 1 つのドメインで使用できます。ドメインとは、OpenCart の設定にあるストアのアドレスのことです。ストアからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがない場合、チェックアウトで顧客に Helcim は表示されません。それでも支払いが開始された場合、顧客には This payment method is not available. Please choose another one. が表示されます。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアでその決済方法が (unlicensed — visible to admins only) と表示された状態で引き続き表示されるため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 では、このプレビューは利用できません。ストアは管理画面へのログイン状態を認識しないため、有効なキーがない場合、決済方法はすべての人に対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文には影響しません。支払い済みの決済は維持され、キャプチャと返金も引き続き機能します。

ライセンスが期限切れになっても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。キーを入力してから最初の 14 日間は 1 日 1 回、その後は 1 週間に 1 回、管理画面の Dashboard または Edit ページを開いたときにステータスが自動的に再確認されます。cron ジョブは必要ありません。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

Helcim がチェックアウトに表示されない: ライセンスが有効であること、Enable / Disable がオンであること、現在のモードに API トークン（Live API token、またはテストモードでは Test API token）が設定されていること、チェックアウトの通貨が Account currencies のいずれかであることを確認してください。トークンがない場合や、ストアの通貨が許可されていない場合は、設定ページに警告が表示されます。また、支払い先住所が選択された Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。

顧客に We could not confirm your payment と表示された: Helcim が応答しなかったため、カードが請求されている可能性があります。注文のメモとログには Helcim の請求書が記載されています。顧客に再び請求する前に、その請求書を Helcim で確認してください。5 分以内に再試行すると元の結果が返され、二重に請求されることはありません。

顧客に This payment method is temporarily unavailable と表示される: Helcim が API トークンを拒否しました。注文のメモには、トークンとその権限を確認するよう記載されています。API アクセスにトランザクション処理の権限があることを確認してください。

顧客に This payment method is not available. Please reload the checkout page. と表示される: チェックアウトのセッションが注文と一致しなくなった、この間に決済方法がオフにされた、またはトークンや通貨が適合しなくなった場合です。顧客はチェックアウトページを再読み込みします。

Helcim が理由で支払いに失敗した: カードや請求情報などの理由で、Helcim がリクエストを拒否しました。注文のメモとログに詳細があります。

顧客に Your payment was received, but the order could not be completed と表示された: Helcim は支払いを承認しましたが、OpenCart は注文ステータスを設定できませんでした。理由はログに記録されています。顧客が同じカートを再送信すると、承認済みの支払いから、二重に請求せずにステータスが設定されます。

注文が確認ステータスになっている: VibeFox Helcim Gateway タブのメモを確認してください。Helcim の応答が注文と一致しませんでした（応答の検証に失敗）。Helcim でトランザクションを確認してから、注文を処理するか、支払いを返金してください。

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

返金に失敗する: メッセージを確認してください。未キャプチャの事前承認は全額でのみ解除できます。モードに関するメッセージは、注文が支払われたモードのトークンが空であることを意味します。拒否された返金は記録されません。You do not have permission to capture or refund (modify this extension). は、ユーザーグループに拡張機能を変更する権限がないことを意味します。

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

アンインストール

Extensions > Extensions に移動し、タイプ Payments を選択して、VibeFox Helcim Gateway の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は、拡張機能自体の設定を常に削除します。具体的には、Enable / Disable、Sort Order、Geo Zone、Total、および Orders セクションの注文ステータスで、これらは再インストール時に既定値に戻ります。OpenCart 4 では、チェックアウトページの上にメッセージを表示する、この拡張機能の OpenCart イベントも削除されます。Delete data on uninstall がオンの場合、その他のゲートウェイ設定（タイトル、説明、API トークン、テストモード、トランザクションの種類、アカウントの通貨、デバッグログのスイッチ）とログも削除されます。オフの場合は、後で再インストールするために保持されます。Helcim のトランザクションと返金は常に残るため、以前に支払われた注文は再インストール後もキャプチャや返金が可能です。既存の注文は支払いメモを保持します。

OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer を開き、インストール済み拡張機能の一覧で VibeFox Helcim Gateway の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードされたパッケージを削除するために Delete（赤いゴミ箱のボタン）をクリックします。

Helcim は、それぞれの所有者の商標です。この拡張機能は Helcim との提携や Helcim による推奨を受けていません。