VibeFox PayU LATAM for OpenCart — ヘルプ

要件

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

PHP: 8.0 以降。

通貨: 購入者のチェックアウト通貨は ARS、BRL、CLP、COP、MXN、PEN、USD のいずれかである必要があります。これらは PayU Latam がアルゼンチン、ブラジル、チリ、コロンビア、メキシコ、パナマ、ペルーで処理する通貨です。その他の通貨では、チェックアウトで決済方法が表示されません。

PayU Latam アカウント: PayU の加盟店アカウントから 3 つの値が必要です：merchant ID、販売先の国の account ID、API キー。これらは PayU 加盟店パネルの Settings > Technical configuration（merchant ID、API key）と Accounts（account ID）にあります。テスト用に、PayU は開発者ドキュメントの「Test your solution」ページで公開のサンドボックス認証情報とテストカードを提供しています。決済は PayU のホスト型ページで行われ、本拡張機能は PayU API を一切呼び出さないため、API Login やその他の API 認証情報は不要です。

ストアのインターネット接続: PayU は決済結果を PayU のサーバーからストアに送信します。そのため、ストアはインターネットから到達できる必要があります（ローカルサイトやパスワード保護されたサイトは不可）。

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

インストール

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

OpenCart 3

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

2. Extensions > Extensions に移動し、種類として Payments を選択します。VibeFox PayU LATAM Payment を見つけて、Install（緑色の + ボタン）をクリックします。管理者ユーザーには、決済拡張機能の一覧を変更する権限が必要です。

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

4. サンドボックスの認証情報と本番の認証情報を入力します（設定を参照）。PayU で確認 URL を設定する必要はありません。

5. Enable/Disable をオンにして Save をクリックします。テスト決済を行うまでは Sandbox をオンのままにし、その後オフにすると、本番の認証情報で実際の決済を受け付けられます。

OpenCart 4

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

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

3. Extensions > Extensions に移動し、種類として Payments を選択します。VibeFox PayU LATAM Payment を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆ボタン）をクリックします。

4. OpenCart 3 の手順 3 から 5 と同じように、ライセンスキーと PayU の認証情報を入力します。設定ページとその欄は両方のバージョンで同じです。違うのは確認 URL だけです（「確認 URL」を参照）。

新規インストール直後は、決済方法がオフ、サンドボックスがオンの状態です。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit。セクションは左側に一覧表示され、一覧の下にある Save ボタンでページ全体を保存します。設定の上部には、サンドボックスがオンの間は Sandbox mode. Payments go to the PayU sandbox and no real money is charged. と表示されます。現在の環境の merchant ID、account ID、API キーが未入力の場合はエラーが表示され（その場合、PayU Latam はチェックアウトで提供されません）、PayU Latam がストアの既定通貨を処理しない場合は警告が表示されます。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。

保存時、Title は空にできず、128 文字を超えることもできません（ページには Enter a title for the payment method (at most 128 characters). と表示されます）。Sort Order は整数である必要があります（負の数も使用できます）。Total は 0 以上の数値である必要があります。ジオゾーンと注文ステータスも存在している必要があります。これらを満たさない場合、何も保存されません。認証情報の先頭と末尾のスペースは無視されます。

PayU LATAM

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

Title: 購入者がチェックアウトで目にする決済方法の名前です。注文にも決済方法の名前として保存されます。既定値：PayU LATAM。必須、128 文字まで。

Description: Confirm Order のステップで、確認ボタンの上に購入者へ表示されるテキストです。既定値：Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.

Sort Order: チェックアウトでの決済方法の中における PayU LATAM の位置です。空欄のままにするか、整数を入力します。

Geo Zone: 選択したジオゾーン内の支払い先住所に対してのみ PayU LATAM を提供します。既定値：All zones。ジオゾーンは System > Localisation > Geo Zones で設定します。

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

環境

Sandbox: 決済はサンドボックスの認証情報を使って PayU サンドボックスに送られ、実際の料金は請求されません。オフにすると、本番の認証情報と PayU の本番決済ページが使用されます。既定値：オン。オンの間、購入者は Confirm Order のステップで Sandbox mode: no real money is charged. と表示されます。

本番の認証情報

PayU 加盟店パネルで確認できます：Settings > Technical configuration（merchant ID、API key）と Accounts（販売先の国の account ID）。このセクションには PayU 加盟店パネルへのリンクがあります。

Merchant ID: PayU 加盟店アカウントの数値 ID です。

Account ID: PayU アカウントの ID です。国ごとに 1 つのアカウントがあります。

API Key: 決済への署名と PayU からの通知の検証に使われる秘密キーです。

サンドボックスの認証情報

PayU は、サンドボックス用に公開のテスト認証情報とテストカードを提供しています。このセクションには PayU ドキュメントの「Test your solution」ページへのリンクがあります。

Sandbox merchant ID: PayU サンドボックスの merchant ID です。

Sandbox account ID: PayU サンドボックスの account ID です。

Sandbox API key: PayU サンドボックスの API キーです。

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

決済の試行ごとに、その環境が記録されます。サンドボックスの決済の確認はサンドボックスの API キーと merchant ID で検証され、本番の決済の確認は本番の値で検証されるため、環境を切り替えた後も保留中の決済は正常に処理されます。サンドボックスの決済は、注文の履歴にサンドボックスとして記録されます。

確認 URL

このセクションには、PayU が決済結果を通知する URL が表示されます。OpenCart 3 では https://your-store/index.php?route=extension/payment/wcp_payu_latam_payment/confirmation の形式で、OpenCart 4 では https://your-store/index.php?route=extension/wcp_payu_latam_payment/payment/wcp_payu_latam_payment.confirmation の形式です。URL は OpenCart のインストール先のストアのアドレスから生成されます。拡張機能は決済ごとにこの URL を PayU に送信するため、PayU 側で設定することはありません。URL はインターネットから到達可能である必要があります。ストアがメンテナンスモードでも動作します（OpenCart 4 では、拡張機能の起動アクションによって、購入者が PayU から戻ることもできます）。確認は PayU が API キーで署名します。署名が無効な確認、別の merchant ID を含む確認、またはこのストアが発行していない決済参照を含む確認は拒否されます。拡張機能は次の PayU トランザクションステータスを扱います：

その他のステータスは、メモとして追加されるだけです。確認がなければ、注文にステータスは設定されません。

注文

OpenCart は Confirm Order のステップで、ステータスのない注文（欠落注文）を作成します。注文にステータスが設定されるのは、署名された PayU の確認を受け取った後だけです。以下の各フィールドには、OpenCart の注文ステータスが一覧表示されます。

Order Status After Payment: 承認された決済（PayU ステータス 4）で、金額と通貨が想定どおりの場合。既定値：Processing。

Awaiting Payment Status: 保留中の決済（ステータス 7、10、12、14、15、18。例えば、まだ完了していない現金払いや銀行振込）。PayU が確認すると、注文は Order Status After Payment になります。既定値：Pending。

On Hold (Review) Status: PayU が決済を承認したものの、金額または通貨が注文と異なる場合、またはキャンセル済みの注文の場合。メモに詳細が表示されます。注文は支払い済みとしてマークされません。既定値：Pending。OpenCart には On hold ステータスがないためです。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。

Failed Payment Status: 最後の試行の保留中の決済が、その後 PayU により拒否、期限切れ、または失敗と報告された場合。既定値：Failed。

Cancelled Order Status: ストアがキャンセル済みの注文に使用するステータスです。そのような注文に対して承認された決済は、支払い済みとしてマークする代わりに On Hold (Review) Status にします。拡張機能がこのステータスを設定することはありません。既定値：Canceled。

詳細設定

Debug log: 決済リクエストと PayU の通知を、OpenCart のログフォルダ（storage/logs）内の payu_lp_debug.log.php に記録します。このファイルは Web からは開けず、5 MB に達すると payu_lp_debug.old.log.php に移動されます。キーや個人データは記録されません。エラーと拒否された通知は、このスイッチがオフでも常に記録されます。既定値：オフ。

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

Delete data: オンの場合、拡張機能をアンインストールするとゲートウェイの設定とログが削除されます。注文と PayU の決済記録（決済の試行）は削除されません。既定値：オフ。

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

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

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

チェックアウト

Payment Method のステップで、購入者は決済方法を選択します（既定では PayU LATAM）。Confirm Order のステップで、購入者にはあなたの説明が表示されます。OpenCart はこのステップで注文を作成しますが、まだステータスはありません。OpenCart 4 では、購入者は決済方法ブロックの Choose ボタンを押し、Payment method options ウィンドウで決済方法を選んで、チェックアウトページ下部の Confirm Order をクリックします。購入者が Confirm Order をクリックすると、拡張機能が署名付きの決済フォームを準備し、ページには You are being redirected to PayU LATAM to complete the payment... と表示され、フォームは自動的に PayU WebCheckout ページに送信されます。自動で移動しない場合、購入者は Pay with PayU LATAM をクリックします。

フォームには、注文通貨での注文合計、注文の税額と課税標準（税のない注文では両方とも 0 で、PayU が既定の付加価値税を追加しないようにします）、注文番号とストア名を含む説明 Order #、そして購入者のメールアドレス、氏名、電話番号、請求先住所が含まれます。PayU のページは、購入者の言語に応じてスペイン語、ポルトガル語、または英語で開きます。PayU のページでは、購入者は PayU アカウントで有効になっている任意の方法で支払えます。

Confirm Order をクリックするたびに、独自の参照（OC、注文番号、タイムスタンプ）を持つ新しい決済の試行が開始されます。OpenCart 4 では、新しい試行はチェックアウトの同じ注文を決済します。以前の試行も記憶されるため、購入者が古い PayU のタブで支払った場合でも、決済は認識されます。

注文が支払い済みになるのは、PayU が署名付きの確認で決済を確認した後だけです。その後、通常の OpenCart の方法で注文ステータスが設定され、通常の注文メールが送信され、在庫が更新されます。PayU から戻った購入者が注文を支払い済みにすることはありません。購入者が戻ってきた場合：

OpenCart 4 では、チェックアウトのメッセージはチェックアウトページの上に表示されます。

OpenCart 3 は Confirm Order のステップが表示されるたびに新しい注文を作成し、OpenCart 4 はチェックアウトの注文を更新しますが、カートの支払いは 1 回だけです。同じカートの別の注文がすでに支払い済み、支払い待ち、または審査中の場合、Confirm Order は直接成功ページに進みます。カートを変更した場合（数量の変更を含む）は、新しいカートとして扱われ、独自の決済が必要です。現在の環境の認証情報が不足している場合、購入者には PayU LATAM is not available right now. Please choose another payment method. が表示されます。

OpenCart 4 では、完了ページが表示されるまで注文がチェックアウト内に保持されます。その間に注文が決済なしで閉じられた場合（たとえば現金払いが失敗した、またはキャンセルした場合）、購入者は Your PayU LATAM payment was not approved と、PayU の理由がある場合はその理由とともにチェックアウトに戻されます。決済された後にストアによって閉じられた場合、または以前のカートについて支払い済みで、その後カートが変更された場合、メッセージは Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order. です。次の Confirm Order で新しい注文の決済が行われます。閉じられた注文が支払い済みとして表示されることはありません。

本拡張機能は、ストアに決済フォームを持たず、OpenCart からの返金、保存済みカード、サブスクリプション、分割払いの設定にも対応していません（PayU はそのページで分割払いを表示します）。決済状況を取得するために PayU API に問い合わせることもありません。注文を更新するのは署名付きの確認だけです。

注文

注文ステータス

ステータスなし（欠落注文）: 購入者は PayU に移動されたものの支払っていない、決済が拒否された、または PayU がまだ確認を送信していない状態です。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定した場合にのみ表示されます。

Order Status After Payment (default Processing): PayU が決済を確認し、金額と通貨が一致しています。メモには、取引、金額、決済方法、サンドボックスの決済かどうかが表示されます。

Awaiting Payment Status (default Pending): PayU が決済を保留中（現金払いまたは銀行振込）と報告しています。PayU が決済を確認すると注文は Order Status After Payment に、失敗した場合は Failed Payment Status に移行します。OpenCart は、これらの変更を購入者に通知します。

On Hold (Review) Status (default Pending): 支払われた金額または通貨が注文合計と一致しない、またはキャンセル済みの注文に対して決済が承認されました。メモには該当するケースが示されます。PayU 加盟店パネルで決済を確認してから、注文を処理するか、復元するか、返金してください。

Failed Payment Status (default Failed): 最後の試行の保留中の決済が、その後拒否、期限切れ、またはエラーで終了しました。メモには PayU のメッセージが表示されます。より古い試行の拒否、または承認済みの決済がある注文の拒否は、メモとしてのみ追加されます。

すべての通知は、カート単位のロックのもとで 1 回だけ処理されます。繰り返し届く PayU の通知によって注文が 2 回変更されたり、メモが重複して追加されたりすることはありません。支払い済みの注文が未払いの状態に戻されることはありません。すでに支払い済みの注文、または同じカートの別の注文に対して、別の承認済みの決済が届いた場合は、支払い済みの注文にその旨のメモが付きます。購入者が二重に支払った場合は、PayU 加盟店パネルで重複分を返金してください。

メモは、購入者には表示されない注文の History のエントリです。

VibeFox PayU LATAM Payment タブ

Sales > Orders で、PayU LATAM で支払われた注文を開きます。注文ページの下部、History と Additional の隣にある VibeFox PayU LATAM Payment タブには、Reference、Transaction ID、PayU reference、Status と PayU のステータス、Requested 金額、Amount reported by PayU、Payment method、PayU message、サンドボックスの決済を示す SANDBOX バッジ、カートの Payment attempts の一覧、注文の PayU LATAM notes が表示されます。このタブは、拡張機能へのアクセス権を持つユーザーに表示されます。

返金

返金は OpenCart からは行えません。PayU 加盟店パネルで取引を返金し、その後 OpenCart で返金を手動で記録してください。

ライセンスキー

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

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

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

トラブルシューティング

PayU LATAM がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在の環境の merchant ID、account ID、API キーが入力されていることを確認してください。Sandbox がオンの場合はサンドボックスの認証情報、オフの場合は本番の認証情報を入力します。購入者の通貨が ARS、BRL、CLP、COP、MXN、PEN、USD のいずれかであること、支払い先住所が選択した Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。

決済は完了したが、注文がステータスなしのまま: PayU の確認がストアに届かなかったか、拒否されました。設定に表示されている確認 URL がインターネットから到達できることを確認してください（ローカルサイト、ファイアウォール、パスワード保護は不可）。拒否された確認は、拡張機能ページの Log フィールドで確認できます。PayU は、エラー応答の後に確認を再送します。

確認が Invalid signature を返す: 確認が、決済の環境の API キーで署名されていません。本番の決済では API Key、サンドボックスの決済では Sandbox API key を確認してください。

確認が Merchant mismatch を返す: 確認の merchant ID が、決済の環境の Merchant ID または Sandbox merchant ID と異なります。決済を処理する PayU アカウントの merchant ID を入力してください。

確認が Gateway not configured を返す: 決済の環境の API キーまたは merchant ID が不足しています。例えば、サンドボックスの決済が保留中のときにサンドボックスの認証情報が削除された場合です。再度入力してください。PayU は確認を再試行します。

確認が Retry を返す: 同じ瞬間に、カートが別のリクエストで処理されていたか、注文ステータスを設定できませんでした。PayU は確認を再送します。理由は Log で確認してください。

確認が Unknown reference を返す: 決済の参照は、このストアによって発行されていません。

確認 URL をブラウザで開くと Method not allowed と表示される: これは正常です。この URL は PayU からのリクエストのみを受け付けます。

購入者に This payment method is not available. Please reload the checkout page. と表示される: チェックアウトのセッションが注文と一致しなくなったか、その間に Enable/Disable がオフにされました。購入者はチェックアウトを再読み込みする必要があります。

注文が審査ステータスにある: VibeFox PayU LATAM Payment タブのメモを確認してください。支払われた金額または通貨が注文と異なったか、注文がキャンセルされた後に決済が届きました。PayU 加盟店パネルで取引を確認してください。

アンインストール

Extensions > Extensions に移動し、種類として Payments を選択して、VibeFox PayU LATAM Payment の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は、拡張機能自身の設定を常に削除します：Enable/Disable、Sort Order、Geo Zone、Total、および Orders セクションの注文ステータス。これらは再インストール時に既定値に戻ります。拡張機能の OpenCart イベントも削除されます（OpenCart 4 では、そのイベントと起動アクションも削除されます。起動アクションにより、メンテナンスモードでも確認と購入者の戻りが通過します）。Delete data がオンの場合は、その他のゲートウェイ設定（タイトル、説明、サンドボックス、認証情報、デバッグログのスイッチ）とログも削除されます。オフの場合は、後で再インストールする際に使用できるように保持されます。決済の試行は常に保持されるため、古い試行に対する PayU の遅延確認は、再インストール後も認識されます。既存の注文は、決済のメモを保持します。

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

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