VibeFox dLocal for WooCommerce — 帮助
系统要求
WordPress: 5.8 或更高版本。
WooCommerce: 7.0 或更高版本，已安装并启用。
PHP: 8.0 或更高版本。在较旧的 PHP 或 WordPress 版本上，插件会拒绝激活。
网站访问：您的网站必须可从互联网访问，并在正式环境中使用 HTTPS，以便 dLocal Go 能够送达付款通知。防火墙、维护模式或基本身份验证可能会拦截这些通知。
dLocal Go 账户：您需要 dLocal Go 控制面板 Payment integration 部分中的 API 密钥和 API Secret：测试环境为 dashboard-sbx.dlocalgo.com，正式环境为 dashboard.dlocalgo.com。测试环境和正式环境使用不同的凭据。企业版 dLocal Payments API（X-Login / X-Trans-Key 凭据）是另一种产品，不受支持。
国家和币种：插件不做限制。由 dLocal Go 决定针对顾客所在国家和店铺币种提供哪些付款方式。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥适用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。也可以通过 FTP 将 wcp_dlocal_payment 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。WooCommerce 必须处于启用状态。
3. 打开设置：WooCommerce > Settings > Payments > dLocal Go > Manage，或在「插件」页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 选择 Environment，并粘贴该环境的 API 密钥和 API Secret（见「配置」）。
6. 开启 Enable/Disable 并保存。在测试环境中测试一笔付款，然后将 Environment 切换为 Production。
配置
所有设置都在同一页面：WooCommerce > Settings > Payments > dLocal Go。页面标题显示 SANDBOX 或 PRODUCTION。在输入所选环境的 API 密钥和 Secret 之前，页面会提示该付款方式在结账页面中处于隐藏状态。选择测试环境且网关已启用时，页面显示 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 Secret：dashboard-sbx.dlocalgo.com（测试环境）或 dashboard.dlocalgo.com（正式环境）。所有凭据字段都是密码字段。
Environment: 决定使用哪组凭据和哪些 dLocal Go 服务器。
Sandbox API Key: 您的 dLocal Go 测试环境 API 密钥。
Sandbox API Secret: 您的 dLocal Go 测试环境 API Secret。
Production API Key: 您的 dLocal Go 正式环境 API 密钥。
Production API Secret: 您的 dLocal Go 正式环境 API Secret。
付款
Default country: dLocal Go 显示顾客所在国家的付款方式，国家取自账单地址，其次取自收货地址。当订单两者都没有时，使用此国家。默认：Uruguay。
Auto-complete orders: Set paid orders to "Completed" instead of "Processing". 状态一次性设置，只发送一组电子邮件。默认：关闭。
通知（IPN）
通知用于告知您的店铺某笔付款或退款发生了变化。插件会在每次付款和退款时将通知 URL 发送给 dLocal Go，因此无需在 dLocal Go 控制面板中进行任何配置。设置的这一部分会显示两个 URL：
通知使用您的 API Secret（HMAC-SHA256）进行验证。没有有效签名的通知会被拒绝。之后，始终从 dLocal Go API 重新读取付款的状态、金额和币种；通知内容不被信任。没有通知时，订单只会在顾客返回店铺时更新。
高级
Debug log: Log API requests and notifications 会将详细信息写入 WooCommerce > Status > Logs，来源为 wcp_dlocal_payment，不包含 API 凭据或个人数据。错误始终会被记录。默认：关闭。
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 页面上接受一次性付款。它不在您的网站上提供银行卡表单，不支持保存银行卡、订阅或分开的授权与扣款。
订单和退款
订单状态
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 报告最近一次付款尝试已取消。
只有最近一次付款尝试才能使未付款订单变为失败或取消。已付款订单绝不会因旧通知而被重新打开。如果已付款订单又收到第二笔付款，订单不会被更改。备注会提示您在 dLocal Go 控制面板中退还这笔重复付款。
退款
打开订单，点击 Refund，输入金额并点击 Refund via dLocal Go。通过 dLocal Go 付款的订单支持全额和部分退款。退款会发送到付款所在的环境，并使用该环境的凭据。如果 dLocal Go 不接受退款，WooCommerce 会显示错误，且不会记录退款。已接受的退款会连同退款 ID 和状态添加到订单备注中。
随后 dLocal Go 通过退款通知报告最终退款状态，并添加到订单备注中。如果 dLocal Go 之后拒绝或取消了已接受的退款，备注会提醒您款项未退还给顾客。请检查为此记录的 WooCommerce 退款：将其删除后重新退款，或通过其他方式向顾客退款。
在 dLocal Go 控制面板中进行的退款不会记录为 WooCommerce 退款，通常也不会添加订单备注。如有需要，请在 WooCommerce 中不使用 Refund via dLocal Go 创建一笔手动退款。
许可证密钥
本插件需配合来自 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 账户。
一个密钥适用于一个域名。从网站移除密钥不会释放其域名名额。请在您的 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 Secret 是否已设置。缺少这些信息时，设置页面会显示警告。
付款已完成，但订单仍为等待付款：dLocal Go 无法访问通知 URL（防火墙、维护模式、基本身份验证），且顾客未返回订单已收到页面。请检查 WooCommerce > Status > Logs（来源 wcp_dlocal_payment）以及 dLocal Go 控制面板中的付款。一旦收到通知或顾客打开订单已收到页面，订单就会更新。
通知返回 Missing signature 或 Invalid signature：设置中的 API 密钥和 Secret 不属于发送该通知的账户。通知会使用两个环境的凭据进行校验，因此在您切换 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 密钥或 Secret。请检查所选环境的凭据。
付款后订单处于保留状态：请阅读订单备注。所付金额或币种与订单不符，或付款在订单取消后才到达。请履行订单或退还该付款。
退款失败并提示缺少凭据：该付款是在另一个环境中完成的，且该环境的凭据未设置。请输入凭据后重试。
许可证区块显示错误：请按照区块中的提示操作。例如，如果密钥已在其他域名上使用，请在您的 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 的认可。