VibeFox Transbank for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

WooCommerce: 8.0 以降。インストールされて有効になっている必要があります。WooCommerce がない場合、プラグインは有効化できません。

PHP: 8.0 以降。

ストアの通貨: チリ・ペソ（CLP）。Webpay Plus は整数のペソのみ請求するため、WooCommerce > Settings > General で Number of decimals を 0 に設定してください。他の通貨のストアでは、この決済方法は表示されません。

Transbank アカウント: 本番決済には、標準の Webpay Plus コマース（即時キャプチャ）と、その本番用 Commerce Code および API Key Secret が必要です。Commerce Code は加盟申請が承認されたときに、API Key Secret は統合検証プロセスの完了後に Transbank から提供されます（Transbank 開発者向けドキュメントを参照してください）。テストには認証情報は不要です。Webpay Plus Mall、Oneclick、および遅延キャプチャのコマースコードはサポートされていません。

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

インストール

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

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

3. WooCommerce > Settings > General で、ストアの通貨をチリ・ペソに、Number of decimals を 0 に設定します。

4. 設定を開きます：WooCommerce > Settings > Payments > Transbank Webpay Plus > Manage。または、プラグインページのプラグイン名の下にある Settings をクリックします。

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

6. Enable / Disable をオンにし、Integration (test) mode をオンにした状態で、Transbank 開発者向けドキュメントのテストカードを使って決済を試してください。

7. 本番運用に移行するには、Production Commerce Code と Production API Key Secret を入力し、Integration (test) mode のチェックを外して保存します。

Transbank で戻り URL やウェブフックを設定する必要はありません。プラグインは各トランザクションで独自の戻り URL を送信します。

設定

すべての設定は 1 つのページにあります：WooCommerce > Settings > Payments > Transbank Webpay Plus。フィールドの上部には、本番モードが選択されているのに Production Commerce Code または API Key が未入力または無効な場合（その場合 Webpay はチェックアウトで非表示になります）、ストアの通貨が CLP でない場合（決済方法は非表示になります）、CLP の価格に小数点がある場合（合計は整数のペソに丸められます）の警告が表示されます。インテグレーションモードがオンの間は、ページに Integration (test) environment と表示され、実際の料金は請求されません。保存後は、新しい設定に基づいて警告が更新されます。決済方法の一覧では、有効な認証情報がないまま本番モードが選択されている場合、ゲートウェイは設定が必要な状態として表示されます。

一般

Enable / Disable: Enable Transbank Webpay Plus payments で、決済方法のオン／オフを切り替えます。デフォルト：オフ。

Title: チェックアウトで購入者に表示される決済方法の名前。デフォルト：Webpay Plus。

Description: チェックアウトで決済方法の下に表示されるテキスト。デフォルト：Pay with credit, debit or prepaid card via Webpay.

環境と認証情報

このセクションのテキストには Transbank 開発者向けドキュメントへのリンクがあり、Transbank が本番用認証情報を提供するタイミングを説明しています。

Integration (test) mode: Use the Transbank integration environment。決済は Transbank のインテグレーション環境に送信され、その公開テスト用コマースコード（597055555532）が自動的に入力されます。以下の本番用認証情報は使用されず、実際の料金は請求されません。デフォルト：オン。本番運用に移行するにはチェックを外してください。

Production Commerce Code: 本番用コマースコード（Tbk-Api-Key-Id）：12 桁で、5970 から始まります。お持ちのコードが 8 桁の場合は、そのまま入力してください。保存時にプラグインが 5970 のプレフィックスを追加します。スペースやその他の文字は削除されます。Transbank の公開テスト用コマースコードは本番では使用できません。

Production API Key Secret: 本番用コマースの Tbk-Api-Key-Secret。秘密にしてください。保存時にスペースは削除されます。

詳細設定

Debug log: Log API requests and returns (errors are always logged)。詳細は WooCommerce > Status > Logs に、ソース wcp_transbank_gateway として書き込まれます。このフィールドには view logs リンクがあります。このオプションがオフでも、エラーと警告は記録されます。カード情報、API キー、トークン全体はログに記録されません。デフォルト：オフ。

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted (order data is kept)。デフォルト：オフ。

テストと本番

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

チェックアウト

購入者は決済方法（デフォルトは Webpay Plus）を選び、注文を確定します。インテグレーションモードでは、チェックアウトに TEST MODE: Integration environment と表示されます。実際の請求は発生しません。プラグインは注文合計を整数のペソとして Transbank トランザクションを作成し（小数点を含む合計は最も近いペソに丸められます）、購入者を短いページ Redirecting to Webpay. Please wait... に送ります。このページから Webpay フォームに転送されます。JavaScript が無効な場合は、購入者が Proceed to Webpay をクリックします。Webpay で、購入者はクレジットカード、デビットカード、またはプリペイドカードで支払います。

購入者が戻ってくると、プラグインはサーバー間通信で Transbank とトランザクションを確定（commit）します。注文が支払い済みになるのは、Transbank が確定した後だけです。応答が承認されており、金額、buy order、セッションが、この試行についてストアが送信した内容と一致している必要があります。その後、購入者には注文受付ページが表示されます。確定の呼び出しが失敗した場合（たとえばタイムアウト）、プラグインは 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. と表示されます。

購入者が Webpay でキャンセルした場合、Webpay フォームが期限切れになった場合、またはエラーが報告された場合は、何も請求されません。注文は支払い待ちのままで、購入者はメッセージとともに Pay for order ページに戻ります。メッセージの例：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 トランザクションになります。

各 Webpay の試行は、最大 1 回だけ確定されます。戻りページの再読み込み、ブラウザの戻るボタン、同時に行われた 2 回目の戻りでも、2 回確定されたり、注文が変更されたりすることはありません。注文がすでに支払いを必要としない場合（別の試行で支払い済み、キャンセル済み、または返金済み）、遅れて戻ってきた場合は確定されないため、Transbank は請求しません。購入者には 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. です。技術的な理由はログに記録されます。

この決済方法は、クラシックチェックアウト、チェックアウトブロック、および Pay for order ページで動作します。WooCommerce の High-Performance Order Storage（HPOS）に対応しています。

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

注文と返金

注文ステータス

Pending payment: 購入者は Webpay に送られたものの、まだ支払っていない、キャンセルした、フォームの期限が切れた、または支払いをまだ確定できていない状態です。試行が終了するたびに、その buy order とともにメモが記録されます。

Processing or Completed: Transbank が支払いを承認しました。ステータスは WooCommerce によって設定されます。仮想のダウンロード可能な商品のみの注文は「完了」（Completed）、それ以外は「処理中」（Processing）になります。注文メモには、承認コード、カード番号の下 4 桁、buy order、金額、支払い種別、分割払いの回数が表示されます。トランザクション ID は Webpay トークンです。

On hold: Transbank が、注文と一致しない支払い（金額、buy order、またはセッション ID）を承認しました。たとえば、支払い開始後に注文が編集された場合などです。メモには相違点が一覧表示されます。Transbank ポータルを確認し、返金するか注文を完了させてください。

Failed: 支払いが拒否されました。請求はされていません。メモには応答コードとステータスが表示されます。

Webpay が、すでに支払い済み、キャンセル済み、または返金済みの注文に対して支払いを返してきた場合、その支払いは確定されず、購入者が請求を報告したときは Transbank ポータルを確認するよう、メモで案内されます。既存の注文は、後の試行の影響を受けません。

返金

返金ボタンは、Webpay で支払われた注文にのみ表示されます。注文を開き、Refund をクリックし、金額を入力して Refund via Webpay Plus をクリックします（ボタンには決済方法のタイトルが使われます）。全額返金と一部返金は、整数のペソ単位でサポートされています。小数点を含む一部返金の金額は、Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. と表示されて拒否されます。小数点を含む注文合計の端数は、請求と同じように丸められます。返金は支払いが行われた環境に送られるため、本番環境では本番用の認証情報を設定しておく必要があります。

Transbank は、取り消し（REVERSED）または無効化（NULLIFIED）で応答します。返金が成功すると、金額、種別、承認コード、および Transbank に残っている残高とともに注文メモに追加されます。Transbank が返金を受け付けない場合、WooCommerce はエラーを表示し、返金は記録されません。Transbank ポータルで行われた返金は WooCommerce にインポートされません。

ライセンスキー

プラグインは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロックは WooCommerce > Settings > Payments > Transbank Webpay Plus の上部にあります。キーを License key に貼り付けて、Activate をクリックします。ブロックにはステータス（たとえばライセンスの有効期限日とドメイン）が表示されます。Check now でステータスを再確認、Change key で別のキーを入力、Remove key でこのサイトからキーを削除できます。Manage licenses and domains in your account のリンクから、vibefox.net のアカウントを開けます。

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

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

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

トラブルシューティング

Webpay Plus がチェックアウトに表示されない: ライセンスが有効であること、Enable / Disable がオンであること、ストアの通貨が CLP であること（Pay for order ページでは注文の通貨）、インテグレーションモードがオフの場合は、有効な Production Commerce Code（12 桁で 5970 から始まる）と Production API Key Secret が保存されていることを確認してください。設定ページには、不足している条件ごとに警告が表示されます。

支払いは完了したが、注文が Pending payment のまま: Transbank にはウェブフックがないため、注文は購入者が Webpay から戻ったときにのみ確定されます。購入者が Webpay でブラウザを閉じた場合、トランザクションは確定されず、Transbank によると清算されません。注文メモ、ログ、Transbank ポータルのトランザクションを確認してください。

購入者に We could not confirm your Webpay payment with Transbank と表示される: 確定の呼び出しが失敗し、ステータスを確認できませんでした。注文は変更されず、メモが追加されています。購入者は少し時間をおいて再試行できます。Transbank ポータルでトランザクションが承認済みと表示されている場合は、発送前にそちらで確定してください。

購入者が注文時にエラーを見る: Debug log をオンにして、WooCommerce > Status > Logs（ソース wcp_transbank_gateway）を確認してください。Webpay payments are not available at the moment は、通常、本番用認証情報が正しくないことを意味します。Could not connect to Webpay は、Transbank に接続できなかったことを意味します。CLP 以外の通貨の注文は、Webpay で支払うことができません。

合計と返金が数ペソずれている: CLP の価格には小数点があります。Webpay は整数のペソのみを請求するため、合計は丸められます。Number of decimals を 0 に設定してください。

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

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

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

アンインストール

プラグインを無効化してもすべてのデータは保持されます。削除するには、Plugins ページで無効化してから削除してください。このプラグインのライセンスキーとライセンスステータスは、常に削除されます。ゲートウェイの設定、その他のオプション、プラグインの一時データ、およびログ（ローテーションされたものを含むログファイルとデータベースのログエントリー）は、Delete data on uninstall がオンだった場合にのみ削除されます。それ以外の場合は、後で再インストールするために残ります。注文に保存されている Transbank のデータは、経理や返金に必要なため、常に保持されます。既存の注文は、支払いメモとトランザクション ID を保持します。

Transbank および Webpay は、それぞれの所有者の商標です。本プラグインは Transbank と提携しておらず、Transbank による承認も受けていません。