VibeFox PayU LATAM for PrestaShop — ヘルプ

要件

PrestaShop：8.0 から 9.x。

PHP：8.0 以降。古い PHP バージョンではモジュールのインストールを拒否します。

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

PayU Latam アカウント：PayU 加盟店アカウントの三つの値が必要です：加盟店 ID、販売先の国のアカウント ID、API キー。これらは PayU モジュール（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. 管理画面で Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。

2. アップロードが完了したら Configure をクリックします。後からモジュール一覧で VibeFox PayU LATAM Payment を探し、Configure をクリックすることもできます。

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

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

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

インストール時に、モジュールは二つの注文ステータスを作成します：Awaiting PayU LATAM payment と PayU LATAM payment on hold。PrestaShop は、すべての通貨、国、顧客グループに対して新しい決済モジュールを提供します。Payment > Preferences で制限できます。後から有効にした国も、同じ場所でモジュールに対してチェックを入れる必要があります。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox PayU LATAM Payment > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上には、サンドボックスが有効な間は Sandbox mode. Payments go to the PayU sandbox and no real money is charged. が表示され、現在の環境の加盟店 ID、アカウント ID、API キーが不足している場合はエラーが、PayU LATAM がショップの既定通貨を処理しない場合は警告が表示されます。認証情報が不足している間、PayU LATAM はチェックアウトに表示されません。認証情報の先頭と末尾のスペースは無視されます。Title が空の場合はページに保存されず、Enter a title for the payment method. が表示されます。

PayU LATAM

Enable/Disable：Enable PayU LATAM で決済方法を有効または無効にします。既定値：無効。

Title：チェックアウトで購入者に表示される決済方法のタイトル。注文に保存される決済方法の名前にもなります。既定値：PayU LATAM。必須。

Description：チェックアウトで購入者に表示される決済方法の説明。既定値：Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.

環境

Sandbox：決済は下記のサンドボックス認証情報を使って PayU サンドボックスに送られ、実際の料金は請求されません。無効の場合は、本番認証情報と PayU の本番決済ページが使われます。既定値：有効。有効な間、購入者には決済方法の下に 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。国ごとに一つのアカウントがあります。

API Key：決済への署名と PayU 通知の検証に使われる秘密鍵。

サンドボックス認証情報

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

Sandbox merchant ID：PayU サンドボックスの加盟店 ID。

Sandbox account ID：PayU サンドボックスのアカウント ID。

Sandbox API key：PayU サンドボックスの API キー。

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

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

各決済試行は使用した環境を記憶します。サンドボックス決済の確認は、サンドボックスの API キーと加盟店 ID で検証され、本番決済の確認は本番の値で検証されます。そのため、切り替え後も保留中の決済は引き続き機能します。切り替え後に確認されたサンドボックス決済は、注文メモに [sandbox] と表示されます。

確認 URL

このセクションには、PayU が各決済結果を報告する URL が表示されます。フレンドリー URL を使用している場合は https://your-shop/module/wcp_payu_latam_payment/confirmation のようになり、/en/ のような言語コードが付くこともあります。モジュールは決済のたびにこの URL を PayU に送信するため、PayU 側で設定することはありません。この URL はインターネットからアクセス可能である必要があります。ショップがメンテナンスモードでも動作し、ショップの国別制限によってブロックされることもありません。確認は、お客様の API キーで PayU が署名します。有効な署名がない確認、別の加盟店 ID を含む確認、またはこのショップが発行していない決済参照番号を含む確認は拒否されます。モジュールは次の PayU トランザクション状態を処理します：

その他の状態はメモとしてのみ追加されます。確認がなければ、注文は作成されません。

詳細設定

Debug log：決済リクエストと PayU 通知を、モジュールフォルダー内の logs/payu_lp_debug.log.php に記録します。このファイルは Web から開くことはできません。キーや個人情報は記録されません。エラーと拒否された通知は、このスイッチがオフでも常に記録されます。既定値：無効。

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

Delete data：モジュールのアンインストール時に、設定とログを削除します。注文の PayU データ（決済試行）と注文ステータスは保持されます。既定値：無効。

チェックアウト

決済の段階で、購入者は決済方法（既定では PayU LATAM）を選んで確定します。ショップのページに You are being redirected to PayU LATAM to complete the payment... が表示され、署名付きフォームが PayU WebCheckout ページに自動的に送信されます。送信されない場合、購入者は Pay with PayU LATAM をクリックするか、Back to checkout をクリックして戻ります。この時点ではまだ注文は存在しません。

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

決済ページを開くたびに、独自の参照番号（PS、カート番号、タイムスタンプ）を持つ新しい決済試行が開始されます。以前の試行も記憶されます。購入者が以前開いた PayU のタブで支払っても、その決済は受け付けられます。

注文が支払い済みになるのは、PayU が署名付き確認を送った後だけです。PayU から戻った購入者が注文を支払い済みにすることはありません。購入者が戻ってきた場合：

現在の環境の認証情報が不足している場合、購入者には PayU LATAM is not available right now. Please choose another payment method. と表示されます。サポートされていないカートの通貨の場合、メッセージは PayU LATAM does not accept payments in に続けて通貨が表示されます。すでに注文があるカートは再度支払われません。購入者は注文確認ページに案内されます。

モジュールには、ショップ内の決済フォーム、PrestaShop からの返金、保存済みカード、サブスクリプション、分割払いの設定はありません（分割払いは PayU のページに表示されます）。決済ステータスについて PayU API に問い合わせることはありません。注文を更新するのは署名付きの確認だけです。

注文

注文ステータス

注文はまだありません：購入者は PayU に送られましたが、まだ支払っていない、決済が拒否された、または PayU がまだ確認を送っていません。カートだけが存在します。

Payment accepted：PayU が決済を確認し、金額と通貨が一致しています。決済は PayU のトランザクション ID とともに記録され、メモにはトランザクション、金額、決済方法、サンドボックス決済の場合は [sandbox] が表示されます。

Awaiting PayU LATAM payment：PayU が決済を保留中（現金払いまたは銀行振込）と報告しています。PayU が決済を確認すると、注文は Payment accepted に移ります。

PayU LATAM payment on hold：支払われた金額または通貨がカートの合計と一致しないか、キャンセルされた注文に対して決済が承認されました。決済が注文の通貨である場合は記録されます。メモには該当するケースが示されます。PayU モジュールで決済を確認し、その後、注文を処理するか、復元するか、決済を返金してください。

Payment error：最新の試行の保留中の決済が、その後、拒否、期限切れ、またはエラーで終了しました。メモには PayU のメッセージが表示されます。このカートは再度支払うことができません。購入者は新しい注文を行います。古い試行の拒否、または承認済みの決済がすでにある注文の拒否は、メモとしてのみ追加されます。

すべての通知は、カートごとのロックの下で一度だけ処理されます。繰り返し届く PayU の通知によって二つ目の注文が作成されたり、メモが二重に追加されたりすることはありません。支払い済みの注文が再度開かれたり、ステータスが下げられたりすることはありません。すでに支払い済みの注文に対して別の承認済み決済が届いた場合、メモにその旨が表示されます。購入者が二重に支払った場合は、PayU モジュールで重複分を返金してください。

PayU LATAM 決済ブロック

注文ページには PayU LATAM payment ブロックが表示されます。内容は、参照番号、トランザクション ID、PayU 参照番号、ステータスと PayU の状態、請求金額、PayU が報告した金額、決済方法、PayU のメッセージ、サンドボックス決済用の SANDBOX バッジ、カートのすべての決済試行の一覧、注文の PayU LATAM notes です。

返金

返金は PrestaShop からは行いません。PayU モジュールでトランザクションを返金し、その後、PrestaShop で返金を手動で記録してください。

ライセンスキー

本モジュールは、vibefox.net の VibeFox ライセンスキーで動作します。License — VibeFox PayU LATAM Payment のライセンスブロックは、Modules > Module Manager > VibeFox PayU LATAM Payment > Configure ページの一番上、設定より上にあります。キーを License key に入力し、Activate をクリックします。その後、ブロックにはキーがマスク表示され、ステータス（ライセンスの有効期限日やドメインなど）が表示されます。また、ステータスを再確認する Check now、別のキーを入力する Change key、このショップからキーを削除する Remove key のボタンがあります。その下には Product: presta-payment-payu-latam の行と、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 をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認できたステータスのまま動作を続けます。

一つのキーは一つのドメインで使用できます。メインショップのドメインを対象とし、マルチストア構成でも同様です。ショップからキーを削除しても、ドメインの枠は解放されません。vibefox.net アカウントで枠を解放してください。

有効なキーがないと、PayU LATAM は購入者にチェックアウトで表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. が表示されます。PrestaShop のショップフロント画面は、管理画面にログインしていることを認識しないため、決済方法はあなたに対しても非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文は影響を受けません。すでに開始された決済は、引き続き PayU の確認と購入者の帰還によって確認されます。

ライセンスの有効期限が切れた場合も、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。管理画面で作業している間、ステータスは自動的に再確認されます。キー入力後最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは必要ありません。モジュールのアンインストールまたはリセットでは、ライセンスキーとライセンスステータスが常に削除されます。

トラブルシューティング

チェックアウトに PayU LATAM が表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在の環境の加盟店 ID、アカウント ID、API キーが入力されていることを確認してください。Sandbox がオンのときはサンドボックス認証情報、オフのときは本番認証情報です。カートの通貨が ARS、BRL、CLP、COP、MXN、PEN、USD のいずれかであることを確認してください。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループに対してモジュールが許可されているか確認してください。

決済は完了したが注文が作成されていない：PayU の確認がショップに届かなかったか、拒否されました。設定に表示されている確認 URL がインターネットからアクセス可能か確認してください（ローカルサイト、ファイアウォール、パスワード保護は不可）。拒否された確認については、モジュールページの Log フィールドを確認してください。PayU は、エラー応答の後に確認を再送します。

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

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

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

確認が Retry を返す：同じタイミングで別のリクエストがカートを処理していたか、注文を作成できませんでした（たとえばモジュールが無効になっている場合）。何も変更されておらず、PayU は確認を再送します。理由は Log で確認してください。

確認が Unknown reference を返す：決済参照番号は、このショップが発行したものではありません。

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

購入者に This payment method is not available と表示される：Payment > Preferences で、購入者の国、通貨、またはグループに対してモジュールが許可されていないか、Enable/Disable がオフです。

注文が PayU LATAM payment on hold になっている：PayU LATAM payment ブロックのメモを確認してください。支払われた金額または通貨がカートと異なったか、注文のキャンセル後に決済が届きました。PayU モジュールでトランザクションを確認してください。

アンインストール

Modules > Module Manager に移動し、VibeFox PayU LATAM Payment の横にあるメニューを開いて Uninstall を選びます。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data がオンの場合は、設定とログが削除されます。オフの場合は、後で再インストールできるように、すべての設定が保持されます。決済試行と、Awaiting PayU LATAM payment と PayU LATAM payment on hold の注文ステータスは常に保持されるため、古い試行に対する PayU の遅延確認は、再インストール後も認識されます。既存の注文は、決済メモ、PayU 参照番号、トランザクション ID を保持します。

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