VibeFox Transbank for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 でテスト済み）または 4.0.2 以降（4.1.0.3 でテスト済み）。

PHP: 8.0 以降。

通貨: チリ・ペソ（CLP）。ストアにない場合は System > Localisation > Currencies で追加してください。小数点以下の桁数は 0 に設定します。Webpay Plus は整数のペソのみを請求します。CLP 以外の通貨の注文では、この決済方法は表示されません。

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

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

インストール

このダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。中には README.txt、OpenCart 3 用パッケージ wcp_transbank_gateway-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ wcp_transbank_gateway.ocmod.zip が含まれています。ご利用の OpenCart のバージョンに合ったパッケージだけをインストールしてください。ライセンスキーは両バージョンで同じです。

OpenCart 3

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

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

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

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

5. 本番運用に切り替えるには、Production Commerce Code と Production API Key Secret を入力し、Integration (test) mode をオフにして Save をクリックしてください。

OpenCart 4

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

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

3. Extensions > Extensions に移動し、種類として Payments を選択してください。VibeFox Transbank Gateway を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆のボタン）をクリックしてください。

4. ライセンスキーと設定は、OpenCart 3 の手順 3 から 5 と同じように入力してください。設定ページとそのフィールドは両バージョンで同じです。戻り URL だけが異なります（戻り URL を参照）。

Transbank 側で戻り URL や webhook を設定する必要はありません。この拡張機能は、すべての取引とともに自身の戻り URL を送信します。新規インストール時は、決済方法がオフ、統合モードがオンの状態で始まります。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox Transbank Gateway > Edit。セクションは左側に並んでおり、一覧の下にある Save ボタンでページ全体を保存します。設定の上部では、本番モードが選択されているのに本番用の Commerce Code または API Key が未入力または無効である場合（この場合、Webpay はチェックアウトで非表示になります）、ストアのデフォルト通貨が CLP でない場合（他の通貨では決済方法が非表示になります）、CLP に小数点以下の桁数が設定されている場合（合計は整数のペソに丸められます）に警告が表示されます。統合モードがオンの間は、支払いが公開されているテスト用の Commerce Code で Transbank の統合環境に送られ、実際の請求は行われないことがページに表示されます。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。

保存時、Title は空にできず 128 文字以内である必要があり、Sort Order は整数（負の値も可）、Total は 0 以上の数値、注文ステータスは存在している必要があります。これらの条件を満たさない場合は何も保存されず、ページにエラーが表示されます。

Transbank Webpay Plus

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

Title: チェックアウトで顧客に表示される決済方法の名前です。注文にも決済方法名として保存されます。デフォルト: Webpay Plus. 必須、最大 128 文字。

Description: Confirm Order のステップで、確認ボタンの上に顧客に表示されるテキストです。デフォルト: Pay with credit, debit or prepaid card via Webpay.

Sort Order: チェックアウトの決済方法の中で Webpay が表示される順番です。空欄のままにするか、整数（負の値も可）を入力してください。

Geo Zone: 選択した地域（ジオゾーン）内の支払い先住所に対してのみ Webpay を提供します。デフォルト: All zones. ジオゾーンは System > Localisation > Geo Zones で設定します。

Total: Webpay を提供するために、注文がストアのデフォルト通貨で到達している必要がある金額です。空欄にすると、どの金額でも Webpay を提供します。

環境と認証情報

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

Integration (test) mode: 支払いは、公開されているテスト用の Commerce Code（597055555532）を使って Transbank の統合環境に送られ、このコードは自動的に使用されます。下記の本番用認証情報は使用されず、実際の請求は行われません。デフォルト: on. 本番運用に切り替えるにはオフにしてください。オンの間、顧客は Confirm Order のステップで TEST MODE — Integration environment. No real charges. と表示されます。

Production Commerce Code: 本番用の Commerce Code（Tbk-Api-Key-Id）です。12 桁の数字で、5970 で始まります。8 桁の場合はそのまま入力してください。保存時に 5970 の接頭辞が追加されます。スペースやその他の文字は削除されます。Transbank の公開テスト用 Commerce Code は本番では動作しません。そのいずれかを使うと、Webpay はチェックアウトで引き続き非表示になります。

Production API Key Secret: 本番の Commerce の Tbk-Api-Key-Secret です。秘密に保ってください。保存時にスペースは削除されます。一度保存されたキーは再表示されず、欄は空のままで Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。保存済みのキーを削除するには、Clear saved API key にチェックを入れて Save をクリックしてください。

Integration (test) mode は、新しい支払いの送信先を決定します。各支払いは自身の環境を記憶しています。支払いの確認と返金は、モードを後から変更しても、常にその支払いが作成された環境（統合または本番）と認証情報を使って行われます。

戻り URL

Return from Webpay: Transbank が顧客を戻す先のアドレスです。参考のために表示されています。OpenCart 3 では https://your-store/index.php?route=extension/payment/wcp_transbank_gateway/back のような形式、OpenCart 4 では https://your-store/index.php?route=extension/wcp_transbank_gateway/payment/wcp_transbank_gateway.back のような形式です。Transbank 側で設定する必要はありません。この拡張機能がすべての取引でこの URL を送信します（Transbank には webhook がありません。顧客が戻ったときに支払いが確定します）。インターネットから到達可能である必要があります。メンテナンスモードでもブロックされません（OpenCart 4 では、拡張機能がそのためのスタートアップアクションを追加します）。

注文

OpenCart は Confirm Order のステップでステータスなしの注文を作成します（欠落注文）。注文がステータスを得るのは、顧客が Webpay から戻ってきたときに、ストアが Transbank で取引を確認（commit）した後だけです。以下の各フィールドには、あなたの OpenCart の注文ステータスが一覧表示されます。

Order Status After Payment: 承認され検証された Webpay の支払い後に設定されるステータスです。デフォルト: Processing.

Transbank Payment On Hold Status: Transbank が注文と一致しない支払い（金額、buy order、session id）を承認した場合、注文は手動確認のために保留され、理由を説明するメモが残ります。デフォルト: Pending. OpenCart には On hold ステータスがないためです。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。

Refunded Status: 注文ページから支払いが全額返金された後に設定されます。デフォルト: Refunded.

詳細設定

Debug log: API リクエストと応答を OpenCart のログフォルダ（storage/logs）内の wc_tbk_debug.log.php に記録します。このファイルはウェブから開くことはできません。このオプションがオフの場合でも、エラーは常に記録されます。カード情報、API キー、完全なトークンは記録されません。デフォルト: off.

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

Delete data on uninstall: オンにすると、拡張機能をアンインストールしたときにゲートウェイの設定とログが削除されます。注文と支払いのデータは常に保持されます。デフォルト: off.

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

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

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

チェックアウト

Payment Method のステップで、顧客は決済方法を選択します（デフォルトは Webpay Plus）。Confirm Order のステップでは、顧客に説明文と、You will be redirected to Webpay (Transbank) to complete the payment. という注意書きが表示されます。OpenCart はこのステップで、まだステータスのない注文を作成します。顧客が Confirm Order をクリックすると、拡張機能は注文合計額に対して整数のペソで Transbank の取引を作成します（小数を含む合計は最も近いペソに丸められます）。その後、顧客は直接 Webpay のフォームに移動し、クレジットカード、デビットカード、またはプリペイドカードで支払います。OpenCart 4 では、顧客は決済方法ブロックの Choose ボタンを使って、Payment method options ウィンドウで決済方法を選択し、チェックアウトページ下部の Confirm Order をクリックします。

顧客が戻ってくると、拡張機能はサーバー間通信で Transbank と取引を確認（commit）します。注文が支払い済みとしてマークされるのは、Transbank が確認した後だけです。応答が承認されており、金額、buy order、セッションがこの試行のためにストアが送信した内容と一致している必要があります。その後、注文は通常の OpenCart の方法でステータスを受け取り、通常の注文メールと在庫の更新が行われます。顧客には、Your Webpay payment has been received. と表示された OpenCart の注文完了ページが表示されます。審査中の注文の場合、ページには Your Webpay payment was received and is being reviewed by the store. と表示されます。

確認の呼び出しが失敗した場合（例：タイムアウト）、拡張機能は 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 と Back to checkout のボタンがあります。その後、ステータスは保存された応答から設定され、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 取引になります。OpenCart 4 では、これらのメッセージはチェックアウトページの上部に表示されます。

OpenCart 3 では、Confirm Order のステップが表示されるたびに新しい注文を作成します。OpenCart 4 では、チェックアウトの注文を 1 つだけ保持して更新するため、キャンセルまたは拒否された支払いの後も、顧客は同じ注文を新しい Webpay 取引で支払います。支払いの開始後に注文が変更された場合（通貨または合計が取引と一致しなくなった場合）、取引は確認されないため Transbank は請求せず、顧客には Your order 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. と表示されます。

OpenCart 4 では、チェックアウトの注文が Webpay の支払いなしでステータスを得た場合、またはその間にストアによって閉じられた場合、次の Confirm Order で顧客は同じメッセージとともにチェックアウトに戻され、カートは新しい注文で支払われます。チェックアウトの注文がすでに支払い済みでも、その後カートが変更された場合（数量の変更を含む）、顧客はチェックアウトに戻され、新しいカートは新しい注文で支払われます。

Webpay が支払いを開始できない場合、顧客は Confirm Order のステップに留まり、短いメッセージが表示されます（例：Could not connect to Webpay. Please try again in a moment. または Webpay could not start the payment. Please try again or choose another payment method.）。技術的な理由はログに書き込まれます。

Transbank には支払いの webhook がないため、結果は顧客が Webpay から戻ったときに処理されます。顧客が Webpay の画面でブラウザを閉じてそのまま戻らなかった場合、取引は確認されず、注文はステータスなしのままになります。Transbank によると、未確認の取引は決済されません。この拡張機能は、Webpay Plus Mall、保存された Oneclick カード、サブスクリプション、遅延キャプチャ、通貨換算には対応していません。

注文と返金

注文ステータス

ステータスなし（欠落注文）: 顧客は Webpay に移動しましたが、まだ支払っていない、キャンセルした、フォームが期限切れになった、カードが拒否された、または支払いがまだ確認できていない状態です。Sales > Orders では、Order Status のフィルターを Missing Orders に設定した場合にのみ、このような注文が表示されます。

Order Status After Payment（デフォルト Processing）: Transbank が支払いを承認しました。メモには、承認コード、カードの下 4 桁、buy order、金額、支払いの種類、分割払いの回数が表示されます。

Transbank Payment On Hold Status（デフォルト Pending）: Transbank が注文と一致しない支払い（金額、buy order、またはセッション）を承認しました。メモには違いが一覧表示されます。Transbank のポータルを確認し、注文を処理するか支払いを返金してください。

Refunded Status（デフォルト Refunded）: この拡張機能を通じて支払いが全額返金されました。

すでにステータスのある注文に対して、または別の注文ですでに支払い済みのカートに対して、Webpay が支払いを返してきた場合、その支払いは確認されず、顧客が請求について報告した際には Transbank のポータルを確認するようメモで促されます。キャンセル、期限切れのフォーム、フォームのエラー、カードの拒否も記録されます。メモは注文の History に表示される項目で、顧客には見えません。

VibeFox Transbank Gateway タブ

Sales > Orders で、Webpay で支払われた注文を開いてください。注文ページの下部、History と Additional の隣にある VibeFox Transbank Gateway タブには、Buy order とその環境（テスト支払いの場合は Integration ラベル）、支払いの Status、Authorization code、分割払いの回数を含む Card / payment type、Charged / refunded、返金フォーム、返金履歴、Webpay attempts of the order、Transbank notes が表示されます。このタブは、拡張機能へのアクセス権を持つユーザーに表示されます。

返金

タブで、CLP の Amount を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて Reason (optional) を入力し、Refund via Transbank をクリックしてください。Refund this amount via Transbank? の確認に応答します。全額返金と一部返金は、整数のペソ単位でサポートされています。拡張機能を変更する権限が必要です（System > Users > User Groups で設定します）。小数を含む一部金額は、Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. と表示されて拒否されます。小数を含む注文合計の最後の端数は、請求と同様に丸められます。返金は Transbank が請求した金額までです。返金は支払いが行われた環境に送られるため、本番の支払いでは本番の認証情報が設定されている必要があります。

Transbank は、取消（REVERSED）または無効化（NULLIFIED）で応答します。返金に成功すると、金額、種類、承認コード、Transbank に残っている残高とともに、返金履歴とメモに追加されます。全額返金では、顧客に通知せず、商品を在庫に戻すこともなく、手動でステータスを変更した場合と同じように Refunded Status が設定されます。一部返金ではステータスは変わりません。Transbank が返金を受け付けない場合、タブにエラーが表示され、返金は記録されません。

Sales > Returns での商品の返品では、Transbank を通じて返金は行われません。Transbank のポータルで行った返金は OpenCart には取り込まれません。

ライセンスキー

この拡張機能は、vibefox.net で発行された VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Transbank Gateway は、Extensions > Extensions > Payments > VibeFox Transbank Gateway > Edit の設定の上にある最初のブロックです。License key にキーを貼り付け、Activate をクリックしてください。その後、ブロックにはマスクされたキー、ステータス（ライセンスの有効期限日やドメインなど）、そして Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）のボタンが表示されます。その下には、Product: opencart-payment-transbank の行と、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 のアカウントで枠を解放してください。

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

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

トラブルシューティング

Webpay Plus がチェックアウトに表示されない: ライセンスが有効であること、Enable / Disable がオンであること、顧客が CLP で支払うこと、そして統合モードがオフの場合は、有効な Production Commerce Code（12 桁、5970 で始まる）と Production API Key Secret が保存されていることを確認してください。また、支払い先住所が選択された Geo Zone 内にあること、注文が設定の Total に達していることも確認してください。設定ページには、認証情報がない場合や、ストア通貨が CLP でない場合の警告が表示されます。

支払いは完了したが、注文がステータスなしのまま: Transbank には webhook がないため、注文は顧客が Webpay から戻ったときにのみステータスを受け取ります。顧客が Webpay でブラウザを閉じた場合、取引は確認されておらず、Transbank によると決済もされません。Debug log をオンにし、Log フィールドを確認して、Transbank のポータルで取引を確認してください。

顧客に We could not confirm your Webpay payment with Transbank と表示される: 確認の呼び出しが失敗し、ステータスを確認できませんでした。注文は変更されておらず、理由はログにあります。顧客はしばらくしてから再試行できます。Transbank のポータルで取引が承認済みと表示されている場合は、顧客が再度支払う前に連絡してください。

顧客に Your order changed after the Webpay payment was started と表示される: 注文の合計または通貨が取引と異なっていました。請求は行われていません。顧客は再度支払う必要があります。

顧客が Confirm Order の後にエラーを見る: 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) は、注文が別の通貨であることを意味します。This payment method is not available. Please reload the checkout page. は、チェックアウトのセッションが注文と一致しなくなったことを意味します。顧客はチェックアウトページを再読み込みする必要があります。

合計と返金が数ペソずれる: CLP 通貨には小数点以下の桁があります。Webpay は整数のペソを請求するため、合計は丸められます。System > Localisation > Currencies で CLP の小数点以下の桁数を 0 に設定してください。

支払い後に注文が審査ステータスになっている: VibeFox Transbank Gateway タブのメモを読み（注文ステータスを参照）、その後注文を処理するか支払いを返金してください。

返金が 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 で失敗する: 同じ瞬間に注文が返金中または確認中でした。しばらくしてから再試行してください。

アンインストール

Extensions > Extensions に移動し、種類として Payments を選択して、VibeFox Transbank Gateway の横にある Uninstall（赤色の − ボタン）をクリックしてください。この拡張機能のライセンスキーとライセンスステータスは常に削除されます。OpenCart は、拡張機能自身の設定を常に削除します。Enable / Disable、Sort Order、Geo Zone、Total、および Orders セクションの注文ステータスは、再インストール時にデフォルトに戻ります。拡張機能の OpenCart イベントも削除されます（OpenCart 4 では、そのイベントに加えて、メンテナンスモードでも Webpay からの戻りを通すスタートアップアクションも削除されます）。Delete data on uninstall がオンの場合、その他のゲートウェイ設定（タイトル、説明、統合モード、認証情報、デバッグログのスイッチ）とログが削除されます。オフの場合は、後で再インストールする際のために保持されます。注文の Webpay 試行と返金は常に保持されるため、以前に支払われた注文は再インストール後も返金できます。既存の注文は支払いのメモを保持します。

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

Transbank と Webpay は、それぞれの所有者の商標です。この拡張機能は Transbank と提携しておらず、Transbank による承認も受けていません。