VibeFox dLocal for PrestaShop — ヘルプ
要件
PrestaShop: 8.0 から 9.x まで。
PHP: 8.0 以降。モジュールは、それより古い PHP バージョンではインストールを拒否します。
ストアへのアクセス: dLocal Go が決済通知を送信できるように、ストアはインターネットからアクセスできる必要があり、本番では HTTPS を使用する必要があります。
dLocal Go アカウント: dLocal Go のダッシュボードの Payment integration セクションにある API キーと API シークレットが必要です。サンドボックスは dashboard-sbx.dlocalgo.com、本番は dashboard.dlocalgo.com を使用します。サンドボックスと本番では認証情報が異なります。エンタープライズ向けの dLocal Payments API（X-Login / X-Trans-Key 認証情報）は別製品であり、サポートされていません。
国と通貨: モジュールでは制限しません。購入者の国とカートの通貨に対してどの決済方法を提供するかは dLocal Go が決定します。適用されるのは PrestaShop の支払い方法の制限のみです。
VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
1. 管理画面で Modules > Module Manager に進み、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。
2. アップロードが完了したら Configure をクリックします。後からモジュール一覧で VibeFox dLocal Payment を見つけて、Configure をクリックすることもできます。
3. VibeFox ライセンスキーを Configure ページ上部のライセンスブロックの License key に貼り付け、Activate をクリックします（ライセンスキーの項を参照）。
4. Environment を選び、その環境の API キーと API シークレットを貼り付けます（設定の項を参照）。
5. Enable/Disable をオンにして Save をクリックします。サンドボックスでテスト決済を行い、その後 Environment を Production に切り替えます。
インストール時に、モジュールは注文ステータス dLocal payment on hold を作成します。PrestaShop は、新しい決済モジュールをすべての通貨、国、顧客グループ向けに提供します。Payment > Preferences で制限できます。
設定
すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox dLocal Payment > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。最初のセクションのタイトルには SANDBOX または PRODUCTION と表示されます。選択した環境の API キーとシークレットを入力するまでは、決済方法がチェックアウトで非表示になる旨の警告がページに表示されます（例：Enter the sandbox API key and secret: until then the payment method is hidden at checkout.）。サンドボックスが選択され、決済方法が有効になっている場合は、Sandbox mode is active: payments are simulated, no money is charged. と表示されます。
dLocal Go
Enable/Disable: Enable dLocal Go で決済方法のオン/オフを切り替えます。デフォルト: オフ。
Title: チェックアウトで購入者に表示される決済方法の名前です。注文にも決済方法名として保存されます。デフォルト: dLocal Go。必須。
Description: チェックアウトで決済方法の下に表示されるテキストです。デフォルト: Pay with local cards, bank transfer or cash via dLocal Go.
API 認証情報
dLocal Go のダッシュボードの Payment integration から API キーと API シークレットをコピーします：dashboard-sbx.dlocalgo.com（サンドボックス）または dashboard.dlocalgo.com（本番）。このセクションには両方のダッシュボードへのリンクがあります。
Environment: 新しい決済にどの認証情報とどの dLocal Go サーバーを使うかを選びます。
返金と通知は、その決済が行われた環境の認証情報を常に使用します。そのため、もう一方の環境の決済がまだ未完了であったり、返金の可能性があったりする間は、その環境の認証情報を保持してください。
Sandbox API Key: dLocal Go のサンドボックス API キーです。
Sandbox API Secret: dLocal Go のサンドボックス API シークレットです。
Production API Key: dLocal Go の本番 API キーです。
Production API Secret: dLocal Go の本番 API シークレットです。
保存済みのキーとシークレットは二度と表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更したい場合にのみ新しい値を入力してください。
Clear saved credentials: キーまたはシークレットにチェックを入れて Save をクリックすると削除されます。空のフィールドは保存済みの値を維持します。
決済
Default country: dLocal Go は、購入者の国の決済方法を表示します。国は請求先住所から取得され、なければ配送先住所から取得されます。カートにどちらもない場合は、この国が使われます。デフォルト: Uruguay。
Auto-complete orders: 支払い済みの注文を Payment accepted ではなく Delivered に設定します。ステータスは一度のステータス変更で即座に設定されます。デフォルト: オフ。
Notifications (IPN): 通知は、決済または返金が変更されたことをストアに知らせます。モジュールは決済と返金のたびに通知 URL を dLocal Go に送信するため、dLocal Go のダッシュボードで設定する必要はありません。このフィールドには両方の URL が表示されます：
通知は API シークレット（HMAC-SHA256）で検証されます。有効な署名がない通知は拒否されます。通知は、決済が行われた環境の認証情報で署名されている必要があります。その後、決済のステータス、金額、通貨は必ず dLocal Go API から読み直され、通知の内容は信頼されません。通知がない場合、注文は購入者がストアに戻ったときにのみ作成されます。
詳細設定
Debug log: dLocal Go へのリクエストと通知を、モジュールのフォルダ内 logs/dlocal_p_debug.log.php に書き込みます。このファイルは Web から開くことはできません。API 認証情報と個人データは記録されません。エラーと警告は常に記録され、それ以外のエントリはこのオプションがオンの間のみ記録されます。デフォルト: オフ。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックするとログを空にできます。
Delete data on uninstall: オンにすると、モジュールをアンインストールしたときにゲートウェイの設定とログが削除されます。注文の決済データ（dLocal の決済と返金）と注文ステータス dLocal payment on hold は常に保持されるため、既存の注文は引き続き機能します。デフォルト: オフ。
チェックアウト
決済の段階で、購入者は決済方法（デフォルトは dLocal Go）を選びます。サンドボックスモードでは、チェックアウトで決済方法の下に Sandbox mode: no real payment is made. と表示されます。確定後、モジュールはカートの通貨でカート合計額について、購入者の国、氏名、メールアドレス、電話番号を添えて dLocal Go の決済を作成し、購入者を dLocal Go の決済ページに移動させます。そこで購入者は自国の決済方法で支払います。dLocal Go のページでは、決済は Order # とカート番号として表示されます。この時点ではまだ注文は存在しません。
支払い後、購入者は貴店に戻ります。注文は、dLocal Go が確認した後にのみ支払い済みになります。署名付きの通知によるか、購入者が戻ったときにサーバー側から dLocal Go API へリクエストを送ることによって確認されます。その後注文が作成され、購入者には標準の注文確認ページが表示され、Your payment with dLocal Go has been received. と表示されます。注文が保留にされた場合、ページには Your dLocal Go payment has been received and is being reviewed by the store. You will be informed when your order is confirmed. と表示されます。dLocal Go がまだ決済を確認していない場合（例：まだ支払われていない現金払いバウチャー、または dLocal Go に接続できなかった場合）、Payment confirmation ページが購入者に再度支払わないよう促し、Check again と Back to checkout を表示します。dLocal Go が決済を確認するとすぐに注文が作成されます。
購入者が支払わずに dLocal Go のページを離れた場合、購入者はチェックアウトに戻り、The payment at dLocal Go was not completed. You can try again or choose another payment method. と表示されます。決済が拒否された場合や期限切れの場合、メッセージは Your dLocal payment was not completed: it was declined or it expired. Please try again or choose another payment method. になります。カートは保持されます。新しい試行ごとに新しい dLocal Go の決済が作成されます。同じカートの古い決済リンクも支払いが可能で、その場合は注文が作成されます。
dLocal Go が決済を開始できない場合、購入者は短いメッセージ（例：dLocal could not start the payment:）とともにチェックアウトに留まり、その後に dLocal が示した理由が表示されます。購入者の国とカートの通貨が dLocal Go アカウントで有効になっていない場合にも同様になります。dLocal Go が認証情報を拒否した場合、購入者には This payment method is temporarily unavailable. Please choose another payment method or contact us. と表示されます。技術的な理由はログに記録されます。
通知はストアがメンテナンスモードの間も機能し、ストアの国の制限によってブロックされることはありません。
モジュールは dLocal Go のページでの 1 回限りの決済のみに対応しています。貴店のサイトにはカード入力フォーム、保存済みカード、定期購入、オーソリとキャプチャの分離はありません。
注文と返金
注文ステータス
注文はまだありません: 購入者は dLocal Go に移動しましたが、まだ支払っていないか、決済が dLocal Go で保留中です。カートのみが存在します。
Payment accepted or Delivered: 決済が確認されました。注文は「支払い受付済み」になります。Auto-complete orders がオンの場合は「配達済み」になります。決済は dLocal の決済 ID をトランザクション ID として記録され、メモには環境と決済 ID が表示されます。
dLocal payment on hold: dLocal Go が、カート合計と異なる金額または通貨を報告しました（例：決済の開始後に別のタブでカートが変更された）。または、注文がキャンセルされた後に決済が届きました。メモに理由が記載されます。dLocal Go のダッシュボードと照合したうえで、注文を処理するか、決済を返金してください。
Refunded: 決済はモジュール経由で全額返金されました。
拒否、期限切れ、キャンセルされた決済が既存の注文を変更することはありません。支払い済みの注文に 2 回目の決済が届いた場合、注文は変更されません。重複した決済を dLocal Go のダッシュボードで返金するよう、メモで案内されます。
dLocal Go 決済ブロック
注文ページには dLocal Go payment ブロックが表示されます。このブロックには、dLocal の決済 ID、環境（テスト決済には Sandbox バッジが付きます）、決済のステータス、dLocal Go が請求した金額と返金済み金額、返金フォーム、返金履歴、注文の dLocal Go notes が含まれます。
返金
dLocal Go payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via dLocal Go をクリックします。確認の質問 Refund this amount through dLocal Go? This cannot be undone. を承認してください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。Modules のページへのアクセスは必要ありません。返金は dLocal Go が請求した金額と通貨で行われます。そのため、金額や通貨に差異がある場合は、注文の合計ではなく、購入者が実際に支払った金額まで返金できます。返金は、決済が行われた環境に、その環境の認証情報を使って送信されます。dLocal Go が返金を受け付けない場合、ブロックにエラーが表示され、返金は記録されません。受け付けられた返金は、返金 ID、ステータス、理由とともに返金履歴とメモに追加されます。全額返金を行うと注文は Refunded になります。一部返金ではステータスは変わりません。
その後、dLocal Go は返金通知によって最終的な返金ステータスを報告し、それがメモに追加されます。dLocal Go が以前受け付けた返金を後から拒否またはキャンセルした場合、メモにはお金が購入者に返金されていない旨の警告が表示されます。購入者に再度返金するか、別の方法で返金してください。
モジュールはクレジットスリップを作成しません。注文ページの標準の PrestaShop の返金ボタンでは、dLocal Go を通じてお金が返金されることはありません。dLocal Go のダッシュボードで行われた返金は、PrestaShop では返金として記録されず、通常はメモも追加されません。必要に応じて注文を手動で更新してください。
ライセンスキー
モジュールは vibefox.net で購入した VibeFox ライセンスキーで動作します。License — VibeFox dLocal Payment のライセンスブロックは、Modules > Module Manager > VibeFox dLocal Payment > Configure ページの一番上、設定より上にあるブロックです。キーを License key に貼り付けて Activate をクリックします。その後、ブロックにはキーが伏せ字で表示され、ステータス（例：ライセンスの有効期限日とドメイン）と、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-payment-dlocal の行と、vibefox.net のアカウントを開く Manage licenses and domains in your account のリンクがあります。キーを変更できるのは、このモジュールの Configure 権限を持つ従業員だけです。ブロックの文言は back office の言語に従います（英語とロシア語を含みます）。
キーが受け付けられない場合、ブロックには理由が表示されます（例：Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on）。ショップのアドレスを変更した後や、アカウントでドメインの枠を解放した後に、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認できたステータスで動作を続けます。
1 つのキーは 1 つのドメインで機能します。マルチストア構成の場合も、メインショップのドメインです。ショップからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。
有効なキーがない場合、dLocal Go はチェックアウトで購入者に表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、バックオフィスにログインしていることを認識しないため、決済方法はあなたにも非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文は影響を受けません。開始済みの決済は引き続き確認され、返金も機能します。
ライセンスの期限が切れても、モジュールは動作を続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キー入力後の最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。
トラブルシューティング
チェックアウトに dLocal Go が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、選択した Environment の API キーと API シークレットが設定されていることを確認してください。設定ページでは、不足している場合に警告が表示されます。Payment > Preferences で、モジュールがカートの通貨、購入者の国、購入者のグループに対して許可されているか確認してください。
決済は完了したが、注文が作成されなかった: dLocal Go が通知 URL に到達できず（ファイアウォール、基本認証、公開アドレスなし）、購入者がストアに戻らなかったためです。Debug log をオンにし、Log フィールドを確認して、dLocal Go のダッシュボードで決済を確認してください。通知が届くか、購入者が Check again を開くと、注文が作成されます。
通知の応答が Missing signature または Invalid signature: 設定の API キーとシークレットが、その通知を送信したアカウントのものではありません。通知は決済が行われた環境の認証情報で検証されるため、Environment を切り替える前に開始された決済も、その環境の認証情報が設定に残っていれば引き続き確認されます。
通知の応答が Gateway not configured: 決済の環境の認証情報がありません。入力してください。dLocal Go は通知を再試行します。
通知の応答が API verification failed: 決済を読み取るために dLocal Go API に接続できませんでした。dLocal Go は通知を再試行します。
通知の応答が Temporarily unavailable: 同じ瞬間に別のリクエストで注文が確認されていたか、注文を作成できませんでした（例：モジュールが無効）。dLocal Go は通知を再試行します。理由はログにあります。
通知の応答が Order not found: その決済は、このストアのカートに属していません。たとえば、同じ dLocal Go アカウントを使う別のサイトで作成された可能性があります。
購入者に This payment method is temporarily unavailable と表示される: dLocal Go が API キーまたはシークレットを拒否しました。選択した環境の認証情報を確認してください。
購入者に Payment gateway is not properly configured と表示される: 選択した環境の認証情報がありません。
支払い後に注文が dLocal payment on hold になる: dLocal Go payment ブロックのメモを確認してください。支払われた金額または通貨がカートと異なっていたか、注文がキャンセルされた後に決済が届きました。注文を処理するか、決済を返金してください。
認証情報がないという内容で返金が失敗する: 決済はもう一方の環境で行われており、その環境の認証情報が設定されていません。認証情報を入力してからもう一度お試しください。
開発者向けには、モジュールのドキュメントに actionWcpDlocalPaymentData と actionWcpDlocalCurrencyDecimals のフックが記載されています。
アンインストール
Modules > Module Manager に進み、VibeFox dLocal Payment の横のメニューを開いて Uninstall を選びます。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合、ゲートウェイの設定とログが削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。注文の dLocal の決済と返金、および注文ステータス dLocal payment on hold は常に保持されるため、以前に支払われた注文は再インストール後も返金できます。既存の注文は、決済のメモとトランザクション ID を保持します。
dLocal は、それぞれの所有者の商標です。本モジュールは dLocal と提携しておらず、dLocal による承認も受けていません。