VibeFox dLocal for WooCommerce — ヘルプ

要件

WordPress: 5.8 以降。

WooCommerce: 7.0 以降、インストール済みで有効化されていること。

PHP: 8.0 以降。古い PHP または WordPress のバージョンでは、プラグインは有効化されません。

サイトへのアクセス: 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 が決定します。

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

インストール

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

2. Activate をクリックします。WooCommerce が有効になっている必要があります。

3. 設定を開きます: WooCommerce > Settings > Payments > dLocal Go > Manage。または、プラグインページでプラグイン名の下にある Settings をクリックします。

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

5. Environment を選び、その環境の API キーと API シークレットを貼り付けます（「設定」を参照）。

6. Enable/Disable をオンにして保存します。サンドボックスで決済をテストしてから、Environment を Production に切り替えます。

設定

すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > dLocal Go。ページのタイトルには SANDBOX または PRODUCTION と表示されます。選択した環境の API キーとシークレットが入力されるまで、ページには、決済方法がチェックアウトで非表示になっているという警告が表示されます。サンドボックスが選択され、ゲートウェイが有効な間は、Sandbox mode is active: payments are simulated, no money is charged. と表示されます。決済方法の一覧では、認証情報が設定されるまで dLocal Go は設定が必要と表示され、サンドボックスでは Test mode と表示されます。

一般

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 シークレット。

決済

Default country: dLocal Go は、請求先住所、次に配送先住所から取得した購入者の国の決済方法を表示します。注文にどちらもない場合は、この国が使用されます。デフォルト: Uruguay。

Auto-complete orders: Set paid orders to "Completed" instead of "Processing". ステータスは一度に設定され、送信されるメールも 1 回分だけです。デフォルト: オフ。

通知（IPN）

通知は、決済または返金が変化したことをストアに知らせます。プラグインは決済と返金のたびに通知 URL を dLocal Go に送信するため、dLocal Go ダッシュボードで設定する必要はありません。設定のこのセクションには両方の URL が表示されます:

通知は API シークレット（HMAC-SHA256）で検証されます。有効な署名のない通知は拒否されます。その後、決済のステータス、金額、通貨は必ず dLocal Go API から読み直され、通知の内容はそのまま信頼されません。通知がない場合、注文は購入者がストアに戻ったときにのみ更新されます。

詳細設定

Debug log: Log API requests and notifications は、API 認証情報や個人データを含めずに、詳細を WooCommerce > Status > Logs（ソース wcp_dlocal_payment）に書き込みます。エラーは常に記録されます。デフォルト: オフ。

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

チェックアウト

購入者は決済方法（デフォルトは dLocal Go）を選んで注文します。プラグインは、注文合計額について、注文通貨で、購入者の国、氏名、メールアドレス、電話番号を含む dLocal Go 決済を作成し、購入者を dLocal Go の決済ページに送ります。購入者はそこで自国の決済方法で支払います。dLocal Go のページでは、決済は Order # と注文番号で表示されます。サンドボックスモードでは、チェックアウトの決済方法の下に Sandbox mode: no real payment is made. と表示されます。

支払い後、購入者は貴店の注文受付ページに戻ります。注文が支払い済みになるのは、dLocal Go が確認した後だけです。確認は、署名付きの通知、または購入者がそのページに到達したときの dLocal Go API へのサーバー側リクエストによって行われます。

購入者が支払わずに dLocal Go のページを離れると、チェックアウト（または Pay for order ページ）に戻り、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 could not start the payment: の後に dLocal からの理由が続き、購入者は別の方法を選べます。これは、購入者の国とストアの通貨が貴店の dLocal Go アカウントで有効になっていない場合にも起こります。技術的な理由はログに書き込まれます。

この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce の高性能注文ストレージ（HPOS）に対応しています。

本プラグインは dLocal Go のページでの 1 回限りの決済のみに対応しています。貴店のサイト上のカード入力フォーム、保存済みカード、定期購入、オーソリとキャプチャの分離には対応していません。

注文と返金

注文ステータス

Pending payment: 購入者は dLocal Go に送られたもののまだ支払っていないか、dLocal Go で決済が処理待ちです（たとえば、まだ支払われていない現金払いバウチャー）。新しい決済の試行ごとに、dLocal 決済 ID、金額、環境が注文に記録されます。

Processing or Completed: 決済が確認されました。注文は「処理中」（WooCommerce のデフォルト）、または Auto-complete orders がオンの場合は「完了」になります。取引 ID は dLocal 決済 ID です。

On hold: dLocal Go が注文合計と異なる金額または通貨を報告したか、注文がキャンセルされた後に決済が届きました。注文メモに理由が記載されます。dLocal Go ダッシュボードと照合し、注文を発送するか決済を返金してください。

Failed: 最新の決済の試行が拒否されたか、期限切れになりました。購入者は再試行できます。

Cancelled: dLocal Go が最新の決済の試行をキャンセル済みと報告しました。

未払いの注文を失敗またはキャンセルにできるのは、最新の決済の試行だけです。支払い済みの注文が古い通知によって再び開かれることはありません。すでに支払い済みの注文に 2 回目の決済が届いた場合、注文は変更されません。メモで、dLocal Go ダッシュボードで重複した決済を返金するよう求められます。

返金

注文を開き、Refund をクリックし、金額を入力して Refund via dLocal Go をクリックします。dLocal Go で支払われた注文では、全額返金と一部返金に対応しています。返金は、決済が行われた環境に、その環境の認証情報で送信されます。dLocal Go が返金を受け付けない場合、WooCommerce にエラーが表示され、返金は記録されません。受け付けられた返金は、返金 ID とステータスとともに注文メモに追加されます。

その後、dLocal Go は返金通知で最終的な返金ステータスを報告し、それが注文メモに追加されます。dLocal Go が一度受け付けた返金を後で拒否またはキャンセルした場合、メモで、購入者にお金が戻っていないことが警告されます。そのために記録された WooCommerce の返金を確認し、削除して返金し直すか、別の方法で購入者に返金してください。

dLocal Go ダッシュボードで行った返金は WooCommerce の返金として記録されず、通常は注文メモも追加されません。必要に応じて、Refund via dLocal Go を使わずに WooCommerce で手動返金を作成してください。

ライセンスキー

本プラグインは、vibefox.net で入手する VibeFox ライセンスキーで動作します。ライセンスブロックは WooCommerce > Settings > Payments > dLocal Go の上部にあります。キーを License key に貼り付け、Activate をクリックします。ブロックには、ライセンスの有効期限やドメインなどのステータスが表示されます。ステータスを再確認するには Check now、別のキーを入力するには Change key、このサイトからキーを削除するには Remove key を使用します。Manage licenses and domains in your account リンクから vibefox.net のアカウントが開きます。

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

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

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

トラブルシューティング

チェックアウトに dLocal Go が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、選択した Environment の API キーと API シークレットが設定されていることを確認してください。これらが不足している場合、設定ページに警告が表示されます。

決済は完了したが、注文が支払い待ちのまま: dLocal Go が通知 URL に到達できず（ファイアウォール、メンテナンスモード、ベーシック認証）、購入者も注文受付ページに戻りませんでした。WooCommerce > Status > Logs（ソース wcp_dlocal_payment）と、dLocal Go ダッシュボードの決済を確認してください。通知が届くか、購入者が注文受付ページを開くとすぐに、注文が更新されます。

通知が Missing signature または Invalid signature を返す: 設定の API キーとシークレットが、通知を送信したアカウントのものではありません。通知は両方の環境の認証情報で確認されるため、Environment を切り替える前に開始された決済も、その環境の認証情報が設定に残っている限り確認されます。

通知が Gateway not configured を返す: 選択した環境の認証情報がありません。dLocal Go は通知を再送します。

通知が API verification failed を返す: 決済を読み取るための dLocal Go API に到達できませんでした。dLocal Go は通知を再送します。

通知が Order not found を返す: 決済がこのストアの注文のものではありません。たとえば、同じ dLocal Go アカウントを使う別のサイトで作成されたものです。

購入者に This payment method is temporarily unavailable と表示される: dLocal Go が API キーまたはシークレットを拒否しました。選択した環境の認証情報を確認してください。

支払い後に注文が保留中になる: 注文メモを確認してください。支払われた金額または通貨が注文と異なっていたか、注文のキャンセル後に決済が届きました。注文を発送するか決済を返金してください。

認証情報が不足しているというメッセージで返金に失敗する: 決済はもう一方の環境で行われており、その環境の認証情報が設定されていません。認証情報を入力して再試行してください。

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

開発者向けに、プラグインのドキュメントには dlocal_p_payment_data、dlocal_p_currency_decimals、dlocal_p_icon のフィルターが記載されています。

アンインストール

プラグインを無効化しても、すべてのデータは保持されます。削除するには、Plugins ページでプラグインを無効化してから削除します。このプラグインのライセンスキーとライセンスステータスは常に削除されます。ゲートウェイの設定とログは、Delete data on uninstall がオンだった場合にのみ削除されます。それ以外の場合は、後で再インストールするときのために残ります。既存の注文には、決済メモと取引 ID が残ります。

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