VibeFox Transbank for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 ～ 9.x。

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

通貨: チリ・ペソ（CLP）。Webpay Plus は整数のペソのみを請求するため、International > Localization > Currencies で CLP 通貨の小数点以下桁数を 0 に設定してください。他の通貨のカートでは、この支払い方法は表示されません。

Transbank アカウント: 本番決済には、本番用の Commerce Code と API Key Secret を持つ標準の Webpay Plus コマース（即時キャプチャ）が必要です。Transbank は加盟店申請が承認されると Commerce Code を、インテグレーション検証プロセスの後に API Key Secret を発行します（Transbank の開発者向けドキュメントを参照）。テストには認証情報は不要です。Webpay Plus Mall、Oneclick、遅延キャプチャのコマースコードはサポートされていません。

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

インストール

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

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

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

4. Enable / Disable をオンにして Save をクリックします。Integration (test) mode をオンにした状態で、Transbank の開発者向けドキュメントにあるテストカードを使って支払いをテストします。

5. 本番運用を開始するには、Production Commerce Code と Production API Key Secret を入力し、Integration (test) mode をオフにして Save をクリックします。

Transbank 側で戻り URL やウェブフックを設定する必要はありません。モジュールは各トランザクションで戻り URL を送信します。

インストール時に、モジュールは注文ステータス Transbank payment on hold を作成します。PrestaShop は、新しい支払いモジュールをすべての通貨、国、顧客グループで有効にします。これらは Payment > Preferences で制限できます。ただし、CLP 通貨はモジュールで許可されたままにしてください。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Transbank Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。項目の上部には、本番モードが選択されているのに本番用の Commerce Code または API Key が未入力または無効な場合（その場合、Webpay はチェックアウトで非表示になります）、ショップの既定通貨が CLP でない場合（他の通貨では支払い方法が非表示になります）、CLP に小数点がある場合（合計は整数のペソに丸められます）に警告が表示されます。インテグレーションモードがオンの間は、支払いが公開テスト用コマースコードを使用して Transbank のインテグレーション環境に送られること、実際の料金は請求されないことが表示されます。

Transbank Webpay Plus

Enable / Disable: Enable Transbank Webpay Plus payments で、この支払い方法のオン／オフを切り替えます。既定値：オフ。

Title: 購入者がチェックアウトで見る支払い方法の名前です。注文に保存される支払い方法の名前でもあります。既定値：Webpay Plus。必須：空のタイトルで保存すると Enter a title for the payment method. と表示されます。

Description: チェックアウトで支払い方法の下に表示されるテキストです。既定値：Pay with credit, debit or prepaid card via Webpay.

環境と認証情報

このセクションのテキストは Transbank の開発者向けドキュメントへのリンクを含み、本番用認証情報が Transbank からいつ提供されるかを説明しています。

Integration (test) mode: 支払いは、自動入力される Transbank の公開テスト用コマースコード（597055555532）を使用して Transbank のインテグレーション環境に送られます。以下の本番用認証情報は使用されず、実際の料金は請求されません。既定値：オン。本番運用を開始するにはオフにします。オンの間、購入者には支払い方法の説明の上に TEST MODE: インテグレーション環境。実際の請求はありません。と表示されます。

Production Commerce Code: 本番用のコマースコード（Tbk-Api-Key-Id）：5970 で始まる 12 桁。8 桁の場合はそのまま入力してください。保存時にモジュールが 5970 の接頭辞を追加します。スペースやその他の文字は削除されます。Transbank の公開テスト用コマースコードは本番では使用できません。

Production API Key Secret: 本番用コマースの Tbk-Api-Key-Secret です。秘密にしてください。保存時にスペースは削除されます。保存済みのキーは再表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ新しい値を入力してください。

Clear saved API key: Production API Key Secret にチェックを入れて Save をクリックすると、保存済みのキーが削除されます。フィールドが空の場合は、保存済みの値が維持されます。

戻り URL

Return from Webpay: Transbank が購入者を戻す先のアドレスで、参考用に表示されます。Transbank 側で設定する必要はありません。モジュールが各トランザクションでこの URL を送信します。購入者がアクセスできる必要があります。メンテナンスモードでもブロックされません。

詳細設定

Debug log: API リクエストと戻りを、モジュールフォルダー内の logs/wc_tbk_debug.log.php に記録します。このファイルは Web から開くことはできません。このオプションがオフでも、エラーと警告は常に記録されます。カード情報、API キー、トークン全体は記録されません。既定値：オフ。

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

Delete data on uninstall: オンの場合、モジュールをアンインストールすると、ゲートウェイの設定とログが削除されます。注文データは保持されます。既定値：オフ。

テストと本番

Integration (test) mode は、新しい支払いの送信先を決定します。各支払いは自身の環境を記憶します。支払いの確定と返金は、後でモードを切り替えても、必ずその支払いが作成された環境（インテグレーションまたは本番）と認証情報で行われます。

チェックアウト

支払いステップで、購入者は支払い方法（既定では Webpay のロゴが付いた Webpay Plus）を選択して確定します。モジュールは、カート合計金額を整数のペソとして Transbank トランザクションを作成し（小数点を含む合計は最も近いペソに丸められます）、購入者を Redirecting to Webpay. Please wait... という短いページに移動させます。このページから Webpay フォームに転送されます。JavaScript が無効の場合、購入者は Proceed to Webpay をクリックします。Webpay では、購入者がクレジットカード、デビットカード、プリペイドカードで支払います。この時点では、まだ注文は存在しません。

購入者が戻ると、モジュールはサーバー間通信で Transbank とのトランザクションを確定（commit）します。注文が支払い済みとしてマークされるのは、Transbank が確定した後だけです。レスポンスが承認されており、金額、buy order、セッションがこの試行でショップが送信した内容と一致している必要があります。その後、注文が作成され、購入者には標準の注文確認ページと Your Webpay payment has been received. が表示されます。保留中の注文の場合、ページには Your Webpay payment was received and is being reviewed by the shop. と表示されます。

確定の呼び出しが失敗した場合（タイムアウトなど）、モジュールは Transbank にトランザクションの状態を問い合わせます。状態が依然として不明な場合、注文は作成されず、購入者には We could not confirm your Webpay payment with Transbank. Please try again in a moment; if your card was charged, contact us before paying again. と表示されます。同じカートを確定中の別のリクエストがある場合、または Transbank が支払いを承認したものの注文をまだ作成できない場合、購入者には Payment confirmation ページが表示され、Your Webpay payment is being confirmed. Please do not pay again — check again in a moment. というメッセージと Check again ボタンが表示されます。その後、保存された応答から注文が作成され、2 回目の確定は行われません。

購入者が Webpay でキャンセルした場合、または Webpay フォームが期限切れになったりエラーを報告したりした場合、料金は請求されません。購入者は、たとえば You cancelled the Webpay payment. Nothing was charged — you can try again or choose another payment method. といったメッセージとともにチェックアウトに戻ります。カードが拒否された場合は、Your Webpay payment was rejected and nothing was charged. Please try again or choose another payment method. と表示されます。カートは保持され、再試行のたびに新しい Webpay トランザクションになります。

支払いの開始後にカートが変更された場合（たとえば別のタブでの変更、またはカート内のクーポンが無効になり PrestaShop が削除した場合）、トランザクションは確定されないため、Transbank は請求しません。購入者には Your cart changed after the Webpay payment was started. The payment was not confirmed, so it was not charged — please pay again. と表示されます。カートにすでに注文がある場合（別の試行または別の支払い方法で支払い済み）、遅れて戻ってきた場合も確定されず、その注文が未払いであれば、購入者には This order can no longer be paid (it was cancelled or already paid). Your Webpay payment was not confirmed, so it was not charged. と表示されます。

Webpay が支払いを開始できない場合、購入者はチェックアウトに留まり、たとえば Could not connect to Webpay. Please try again in a moment. や Webpay payments are not available at the moment. Please choose another payment method. といった短いメッセージが表示されます。技術的な理由はログに書き込まれます。

ショップがメンテナンスモードの間も、Webpay からの戻りは機能し、ショップの国別制限でブロックされることはありません。

Transbank には決済用のウェブフックがありません。結果は、購入者が Webpay から戻ったときに処理されます。購入者が Webpay でブラウザを閉じて戻らなかった場合、トランザクションは確定されず、注文も作成されません。Transbank によると、確定されていないトランザクションは決済されません。モジュールは、Webpay Plus Mall、Oneclick の保存カード、定期購入、遅延キャプチャ、通貨換算には対応していません。

注文と返金

注文ステータス

No order yet: 購入者は Webpay に移動しましたが、支払いをしなかった、キャンセルした、フォームの期限が切れた、カードが拒否された、または支払いをまだ確定できない状態です。カートだけが存在します。

Payment accepted: Transbank が支払いを承認しました。支払いは Webpay のトークンをトランザクション ID として記録され、メモには承認コード、カード番号の下 4 桁、buy order、金額、支払いの種類、分割払いの回数が表示されます。

Transbank payment on hold: Transbank が注文と一致しない支払い（金額、buy order、またはセッション）を承認したか、Transbank が支払いを承認した後にカート内のクーポンが無効になり、PrestaShop がそれを削除しました。支払いは Transbank が請求した金額で記録され、メモには相違点が一覧表示されます。Transbank ポータルを確認し、注文を完了するか、支払いを返金してください。

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

Webpay が、すでに注文があるカートの支払いを返した場合、その支払いは確定されず、その注文のメモで、購入者から請求の報告があった場合に Transbank ポータルを確認するよう求められます。後の試行によって既存の注文が影響を受けることはありません。

Transbank Webpay Plus ブロック

注文ページには Transbank Webpay Plus ブロックが表示され、buy order とその環境、支払いステータス、承認コード、カードと支払いの種類（分割払い回数を含む）、請求額と返金額、テスト支払い用の Integration バッジ、返金履歴、Webpay attempts of the cart、注文の Transbank notes が含まれます。

返金

Transbank Webpay Plus ブロックで CLP の金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Transbank をクリックします。Refund this amount via Transbank? の確認に応じると返金されます。全額返金と一部返金は整数のペソ単位でサポートされています。注文を編集する権限が必要です。モジュールのページへのアクセス権は必要ありません。小数点を含む一部の金額は、Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. と表示されて拒否されます。小数点を含む注文合計の端数は、請求と同じ方法で丸められます。返金は Transbank が請求した金額までが対象のため、相違が発生した後でも、購入者が実際に支払った金額を返金できます。返金は支払いが行われた環境で処理されるため、本番環境での支払いの場合は本番用認証情報が設定されている必要があります。

Transbank は取消（REVERSED）または無効化（NULLIFIED）で応答します。返金が成功すると、返金履歴とメモに、金額、種類、承認コード、Transbank 側に残っている残高が追加されます。全額返金すると、注文は Refunded になります。一部返金ではステータスは変わりません。Transbank が返金を受け付けない場合、ブロックにエラーが表示され、返金は記録されません。

モジュールはクレジットメモを作成しません。注文ページの標準の PrestaShop 返金ボタンでは、Transbank を通じて返金されません。Transbank ポータルで行われた返金は、PrestaShop にインポートされません。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Webpay Plus が表示されない: ライセンスが有効であること、Enable / Disable がオンであること、カートの通貨が CLP であること、そしてインテグレーションモードがオフの場合は、有効な Production Commerce Code（5970 で始まる 12 桁）と Production API Key Secret が保存されていることを確認してください。設定ページには、不足している条件ごとに警告が表示されます。Payment > Preferences で、モジュールが CLP、購入者の国、購入者の顧客グループに対して許可されていることを確認してください。

支払いは完了したが注文が作成されなかった: Transbank にはウェブフックがないため、注文は購入者が Webpay から戻ったときにのみ作成されます。購入者が Webpay でブラウザを閉じた場合、トランザクションは確定されず、Transbank によると決済されません。Debug log をオンにし、Log フィールドを確認して、Transbank ポータルでトランザクションを確認してください。

購入者に We could not confirm your Webpay payment with Transbank と表示される: 確定の呼び出しが失敗し、状態を確認できませんでした。注文は作成されておらず、理由はログにあります。購入者は少し待ってから再試行できます。Transbank ポータルでトランザクションが承認済みと表示される場合は、購入者が再度支払う前に連絡してください。

購入者に Your cart changed after the Webpay payment was started と表示される: カートの合計がトランザクションと異なっていました。たとえば別のタブでの変更や、期限切れのクーポンが原因です。料金は請求されていません。購入者は新しい合計額を支払います。

購入者が Webpay Plus を選択したときにエラーが表示される: Debug log をオンにし、モジュールのページにある Log フィールドを確認してください。Webpay payments are not available at the moment は通常、本番用認証情報が正しくないことを意味します。Could not connect to Webpay は、Transbank に接続できなかったことを意味します。Transbank Webpay only supports payments in CLP (Chilean Peso) は、カートが別の通貨であることを意味します。

合計と返金が数ペソ異なる: CLP 通貨には小数点があります。Webpay は整数のペソのみを請求するため、合計は丸められます。International > Localization > Currencies で CLP の精度を 0 に設定してください。

支払い後、注文が Transbank payment on hold になっている: Transbank Webpay Plus ブロックのメモを確認し（注文ステータスを参照）、注文を完了するか、支払いを返金してください。

The production Commerce Code / API Key are missing と表示されて返金に失敗する: 支払いは本番環境で行われましたが、本番用認証情報が保存されていません。認証情報を入力してから、もう一度お試しください。

Transbank refused the refund または Transbank did not approve the refund と表示されて返金に失敗する: Transbank が受け付けませんでした。メッセージには理由、または Transbank が返した種類と応答コードが表示されます。返金は行われていません。Transbank ポータルでトランザクションを確認してください。

Another request is processing this order と表示されて返金に失敗する: 注文が同時に返金または確定されていました。しばらくしてから再試行してください。

アンインストール

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

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