VibeFox Tranzila for PrestaShop — ヘルプ

要件

PrestaShop：8.0 から 9.x。

PHP：8.0 以降。古い PHP バージョンではモジュールのインストールができません。

ストアの通貨：ILS、USD、EUR、GBP のいずれか。それ以外のカート通貨の場合、チェックアウトで支払い方法は表示されません。

Tranzila 端末：端末名が必要です。端末パスワード（TranzilaPW）は、handshake と注文ページからの返金に必要です。端末によっては、返金用に別途クレジットパスワード（CreditPass）が必要な場合もあります。端末名とパスワードは Tranzila から提供されます。端末の設定を確認するか、Tranzila のサポートにお問い合わせください。Tranzila には公開のサンドボックスはありません。テスト用には、Tranzila から別のテスト端末が提供されます。その名前を端末名として入力してください。

訪問者の実際の IP アドレス：支払い通知は、Tranzila サーバーの IP アドレスに基づいて検証されます。貴店が Cloudflare などのプロキシや CDN の背後にある場合、Web サーバーは訪問者の実際の IP アドレスを PHP に渡す必要があります（REMOTE_ADDR）。

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

インストール

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

2. アップロードが完了したら Configure をクリックします。後で探す場合は、モジュール一覧から VibeFox Tranzila Payment Gateway を見つけて Configure をクリックします。

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

4. handshake または返金を使用する場合は、Terminal name (supplier) と Terminal password (TranzilaPW) を入力します。

5. Notifications をオンのままにし、Trusted IP を確認します。ここには、Tranzila が通知を送信する IP アドレスを記載する必要があります。このリストは Tranzila のサポートで確認してください。

6. 推奨：Tranzila の端末で handshake を有効にし、そこで貴サーバーの IP アドレスを許可してから、モジュールで Handshake をオンにします。

7. Enable/Disable をオンにし、Save をクリックして、Tranzila のテスト端末で支払いをテストします。

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

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Tranzila Payment Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上部では、端末名が空の場合（その場合、チェックアウトで支払い方法が非表示になります）、通知が無効な場合、または Trusted IP が空の場合（支払い済みの注文は手動確認のために保留されます）、端末パスワードなしで handshake がオンの場合（決済ページを開けません）、ストアの既定の通貨がサポートされていない場合に、ページが警告を表示します。保存時に、無効な端末名、Trusted IP の無効な項目、または整数ではない数値フィールドは保存されません。ページにエラーが表示され、以前の値が保持されます。許容範囲外の数値は、最も近い許容値として保存され、ページにその旨が表示されます。

Tranzila

Enable/Disable：Enable Tranzila Payment Gateway で、支払い方法のオン／オフを切り替えます。既定値：オフ。

Title：チェックアウトで購入者に表示される支払い方法の名前で、決済ページのタイトルにもなります。注文に保存される支払い方法名でもあります。既定値：Credit Card (Tranzila)。

Description：チェックアウトで支払い方法の下に表示されるテキストです。既定値：Pay securely with your credit card on the Tranzila payment page.

端末

Terminal name (supplier)：Tranzila の端末名です（例：myshop）。使用できるのは英字、数字、「-」、「_」のみです。入力されるまで、チェックアウトで支払い方法は表示されません。テストの場合は、Tranzila のテスト端末の名前を入力してください。

Terminal password (TranzilaPW)：端末の API パスワードです。handshake と注文ページからの返金に必要です。

Refund password (CreditPass)：端末がクレジット（返金）取引に対して別のパスワードを要求する場合のみ使用します。それ以外の場合は空欄のままにします。

保存されたパスワードは再表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更したい場合のみ、新しい値を入力してください。

Clear saved passwords：パスワードにチェックを入れて Save をクリックすると削除されます。空欄の場合は、保存済みの値が保持されます。

決済ページ

Payment page version：iframe に表示される Tranzila のページです。

Payment page language：Tranzila ページの言語：Site language、ヘブライ語、英語、ロシア語、スペイン語、ドイツ語、フランス語、日本語。既定値：ヘブライ語。Site language は、購入者のカートの言語がこれらのいずれかである場合にその言語を使用し、それ以外の場合は英語を使用します。

iFrame width (px)：300 から 1200。既定値：600。小さな画面では、フレームがページより広くなることはありません。

iFrame height (px)：400 から 1500。既定値：650。

Max installments：購入者が決済ページで選択できる分割回数（tashlumim）の上限で、最大 36 です。0 または 1 は分割なしを意味します。既定値：0。端末で分割払いの処理が許可されている必要があります。

Handshake：handshake トークンで金額をロックします（推奨）。決済ページを開く前に、ストアは金額に紐付けられた使い捨てトークンを Tranzila に要求するため、ブラウザ上で金額を変更できません。端末パスワード、Tranzila の端末で handshake が有効であること、そしてそこで貴サーバーの IP アドレスが許可されていることが必要です。既定値：オフ。

支払いの確認

Tranzila の通知には署名がありません。注文は、通知が Trusted IP から届き、その決済ページのトークン、カート、端末、金額、通貨が決済ページと一致した場合にのみ、支払い済みとして作成されます。handshake を使用する場合は、トークンも決済ページと一致する必要があります。購入者が決済ページから戻っただけでは、注文が支払い済みになることはありません。

Notifications：Tranzila の通知（notify URL）で支払いを自動的に確定します。既定値：オン。通知がオフの場合、支払いが成功した決済ページから戻った購入者によって注文が Tranzila payment on hold として作成されます。Tranzila の端末を確認した後、手動で支払いを確定してください。

Notification URL：参考情報として表示されます。フレンドリー URL の場合は、https://your-shop/module/wcp_tranzila_payment_gateway/notify のような形式になり、言語コードが付くこともあります。この URL は支払いのたびに Tranzila に送信されるため、Tranzila の端末に入力する必要はありません。

Trusted IP：通知を送信する Tranzila サーバーの IP アドレスまたは CIDR 範囲を、カンマで区切って指定します。既定値：80.244.170.7。現在のリストは Tranzila のサポートで確認してください。それ以外のアドレスからの通知は拒否されます。このフィールドが空の場合、通知を検証できません。成功として報告された支払いは、手動確認のために Tranzila payment on hold として注文を作成し、拒否として報告された支払いは何も変更しません。

詳細設定

Debug log：決済ページ、通知、返金のイベントを、モジュールのフォルダ内の logs/tranzila_p_debug.log.php に記録します。このファイルは Web から開くことはできません。このオプションがオフでも、警告とエラーは常に記録されます。パスワード、トークン、購入者データは書き込まれません。既定値：オフ。

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

Delete data on uninstall：オンの場合、モジュールをアンインストールすると設定とログが削除されます。Tranzila の取引と返金、および注文ステータス Tranzila payment on hold は、古い注文がそれらを必要とするため、常に保持されます。既定値：オフ。

チェックアウト

支払いの段階で、購入者は支払い方法（既定では Credit Card (Tranzila)）を選択し、説明と、After you confirm, you will enter your card details on the secure Tranzila payment page. The order is created once Tranzila confirms the payment. という注記を確認します。確認すると、購入者は貴店の決済ページに移動します。そこでは、カートの通貨による合計金額、請求情報、商品の簡単な一覧とともに、iframe 内に Tranzila の決済ページが開きます。ページには Enter your card details on the secure Tranzila payment page below. If it does not load, click "Proceed to payment". と表示されます。フレームの下には Choose another payment method のリンクがあります。分割払いが許可されている場合、購入者は Tranzila のページで分割回数を選択します。この時点ではまだ注文は存在しません。

支払いが成功すると、Tranzila が購入者を戻し、ウィンドウ全体が次に進みます。注文は、Tranzila が通知によって確認した後にのみ支払い済みとしてマークされます。通知がすでに届いている場合、購入者には標準の注文確認ページが表示され、Your payment with Tranzila has been received. と表示されます。注文が確認のために保留されている場合、ページには Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed. と表示されます。通知がまだ届いていない場合は、Payment confirmation ページに Your payment is being confirmed by Tranzila. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. と表示され、Check again ボタンが表示されます。

支払いが拒否またはキャンセルされた場合、購入者は The payment was not completed. You have not been charged — please try again or choose another payment method. というメッセージとともにチェックアウトに戻ります。Tranzila が応答コードを報告した場合は、理由とコードが追加されます（例：カードの有効期限切れ）。カートは保持され、注文は作成されません。決済ページを開くたびに、独自のトークンを持つ新しい決済ページになります。

handshake の失敗など、決済ページを開けない場合、購入者には Could not connect to Tranzila. Please try again in a moment. のような短いメッセージと、Choose another payment method ボタンが表示されます。技術的な理由はログに記録されます。

通知は、ストアがメンテナンスモードの間も機能し、貴店の国別制限によってブロックされることはありません。同じ決済ページは、Classic と Hummingbird のテーマで使用されます。

モジュールは、Tranzila のページでの単発のカード決済のみに対応しています。保存済みカードやトークン、サブスクリプション、オーソリと売上確定の分離（J5）、独自の Bit、Apple Pay、Google Pay ボタン（Tranzila の決済ページが提供するものは、すべて iframe 内に表示されます）、Tranzila の請求書には対応していません。

注文と返金

注文ステータス

No order yet：購入者は決済ページに送られたものの、支払いをしていない、支払いが拒否された、または Tranzila の通知がまだ届いていない状態です。カートのみが存在します。

Payment accepted：支払いは検証済みの通知によって確認されています。支払いは、Tranzila の取引インデックスを取引 ID として記録され、メモには金額、取引、承認番号、そして分割回数（ある場合）が表示されます。

Tranzila payment on hold：支払いは報告されたものの、自動的には受け付けられていません。金額、通貨、または handshake トークンが一致しなかった、Trusted IP が空のため通知を検証できなかった、または通知がオフの状態で購入者が支払いが成功した決済ページから戻った、のいずれかです。メモに理由が記載されます。Tranzila の端末で支払いを確認し、手動でステータスを変更してください。

Refunded：モジュールを通じて支払いが全額返金されました。

キャンセルされた注文に対して支払いが届いた場合、その注文は再び Payment accepted に設定され、発送前に在庫を確認するよう求めるメモが付きます。すでに支払い済みまたは返金済みの注文に対して 2 回目の支払いが届いた場合、注文は変更されません。メモで確認し、Tranzila の端末で重複分を返金するよう求められます。同じ取引の繰り返しの通知は無視されます。

Tranzila 支払いブロック

注文ページには、Tranzila payment ブロックが表示されます。このブロックには、取引インデックス、承認番号、端末、ステータス、支払い済み金額と返金済み金額、分割回数、返金履歴、結果付きのすべての Payment pages of the cart、そして注文の Tranzila notes が含まれます。

返金

Tranzila payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Tranzila をクリックします。Refund this amount via Tranzila? This cannot be undone. の確認に同意してください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。モジュールのページへのアクセスは必要ありません。返金は、元の支払いの Tranzila クレジット取引として、支払いを受け付けた端末で、Tranzila が実際に請求した金額と通貨で行われます。そのため、金額または通貨の不一致が発生した後も、注文合計ではなく、購入者が実際に支払った金額まで返金できます。

フォームは、端末パスワードが設定されていて、注文に承認番号付きの確定済み Tranzila 取引がある場合に利用できます。それ以外の場合、ブロックにはその理由が表示されます（例：Refunds need the terminal password (TranzilaPW) in the gateway settings.）。現在の設定とは異なる端末（テスト端末など）で支払われた注文は、注文ページから返金できません。その Tranzila 端末で返金してください。

Tranzila が返金を受け付けない場合、ブロックにはエラーが表示されます（例：コードとその意味付きの Tranzila declined the refund）。返金は記録されません。返金が成功した場合は、Tranzila のクレジット取引とともに返金履歴とメモに追加されます。全額返金を行うと、注文は Refunded に設定されます。一部返金ではステータスは変わりません。

モジュールはクレジットスリップ（credit slips）を作成しません。注文ページの標準の PrestaShop 返金ボタンは、Tranzila を経由して金銭を返金しません。Tranzila の端末で行われた返金はストアに通知されません。必要に応じて注文を手動で更新してください。

ライセンスキー

モジュールは、vibefox.net で入手した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Tranzila Payment Gateway は、Modules > Module Manager > VibeFox Tranzila Payment Gateway > Configure の設定の上にある最初のブロックです。キーを License key に入力し、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（ライセンスの有効期限日や貴社のドメインなど）、そして次のボタンが表示されます：Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このショップからキーを削除）。その下には Product: presta-payment-tranzila の行と、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 のアカウントで枠を解放してください。

有効なキーがない場合、チェックアウトで Tranzila は購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、バックオフィスにログインしていることを認識しないため、お客様にも支払い方法が非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文は影響を受けません。開始済みの支払いは、Tranzila の通知とショップへの戻りによって引き続き確認され、返金も機能します。

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

トラブルシューティング

チェックアウトに Tranzila が表示されない：ライセンスが有効であること、Enable/Disable がオンであること、Terminal name (supplier) が入力されていること、そしてカートの通貨が ILS、USD、EUR、GBP のいずれかであることを確認してください。端末名がない場合や既定の通貨がサポートされていない場合は、設定ページに警告が表示されます。Payment > Preferences で、モジュールがカートの通貨、購入者の国、購入者のグループに対して許可されているかを確認してください。

支払いは完了したが、注文が作成されなかった：通知が届かなかったか、拒否されました。Notifications がオンであること、そして Trusted IP に Tranzila が通知を送信する IP アドレスが記載されていることを確認してください。エラーは常にログに記録されます。モジュールのページの Log 欄を確認してください。IP が Trusted IP リストにないというメッセージは、Trusted IP の設定またはプロキシの構成を修正する必要があることを意味します。プロキシや CDN の背後では、Web サーバーが訪問者の実際の IP アドレスを PHP に渡す必要があります。信頼できるリバースプロキシの背後にストアがある開発者は、actionTranzilaPRemoteIp フックで IP を設定できます。

通知が Forbidden で応答する：Trusted IP にない IP アドレスから送信されました。

通知が Bad request または Not found で応答する：通知内のカート、決済ページのトークン、端末、または取引インデックスが、このストアのどの決済ページとも一致しません。

通知が Accepted for manual review で応答する：Trusted IP が空のため、通知を検証できませんでした。成功した支払いは、保留状態で注文を作成します。支払いを自動的に確定するには、Trusted IP に入力してください。

通知が Busy, retry で応答する：同じタイミングで別のリクエストがカートを処理していたか、注文を作成できませんでした（例：モジュールが無効）。ログに理由が表示されます。Tranzila の端末で支払いを確認してください。そこで承認されていて注文が作成されていない場合は、購入者に連絡するか、注文を手動で作成してください。

一部の注文が Tranzila payment on hold になっている：Tranzila payment ブロックのメモを読んでください。金額、通貨、または handshake トークンが一致しなかったか、通知を検証できませんでした（Trusted IP が空、または通知が無効）。Tranzila の端末で支払いを確認し、手動でステータスを変更してください。

handshake がオンのときに決済ページが開かない：端末名と端末パスワードを確認し、Tranzila の端末で handshake が有効であること、そしてそこで貴サーバーの IP アドレスが許可されていることを確認してください。ログに理由が表示されます。

返金が失敗する：返金には Terminal password (TranzilaPW) が必要です。一部の端末では、別のクレジットパスワードも必要です。それを Refund password (CreditPass) に入力してください。別の端末で支払われた注文は、その端末で返金する必要があります。Tranzila の応答が想定外の場合、ブロックには返金が確認されなかったことが表示されます。再試行する前に、Tranzila の端末を確認してください。

その他の通貨：モジュールは ILS、USD、EUR、GBP のみに対応しています。

アンインストール

Modules > Module Manager に移動し、VibeFox Tranzila Payment Gateway の横にあるメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合は、設定とログが削除されます。オフの場合は、後で再インストールするためにすべての設定が保持されます。Tranzila の取引と返金、および注文ステータス Tranzila payment on hold は常に保持されるため、以前に支払われた注文は再インストール後も返金できます。既存の注文は、支払いメモと取引 ID を保持します。

Tranzila は、それぞれの所有者の商標です。本モジュールは Tranzila と提携しておらず、Tranzila による推奨もされていません。