VibeFox dLocal for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块会拒绝在更早的 PHP 版本上安装。
店铺访问：您的店铺必须可从互联网访问，并且正式环境需使用 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 会根据顾客所在国家和购物车币种决定提供哪些付款方式。只适用 PrestaShop 的付款限制。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 进入后台，前往 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox dLocal Payment，然后点击 Configure。
3. 将您的 VibeFox 许可证密钥粘贴到 Configure 页面顶部许可证区块中的 License key 中，然后点击 Activate（参见许可证密钥）。
4. 选择 Environment，并粘贴该环境的 API 密钥和 API Secret（参见配置）。
5. 开启 Enable/Disable 并点击 Save。先在沙盒中测试付款，然后将 Environment 切换为 Production。
安装时，模块会创建订单状态 dLocal payment on hold。PrestaShop 会为所有币种、国家和客户群组提供新的付款模块。您可以在 Payment > Preferences 中加以限制。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox dLocal Payment > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。第一个部分的标题会显示 SANDBOX 或 PRODUCTION。在输入所选环境的 API 密钥和 Secret 之前，页面会提示付款方式在结账时被隐藏，例如 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 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。
已保存的密钥和 Secret 不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Clear saved credentials: 勾选某个密钥或 Secret，然后点击 Save 将其删除。空字段会保留已保存的值。
付款
Default country: dLocal Go 会显示顾客所在国家的付款方式，该国家依次取自账单地址、再取自配送地址。如果购物车两者都没有，则使用此国家。默认：Uruguay。
Auto-complete orders: 将已付款订单设为 Delivered，而不是 Payment accepted。状态会一次性设置，只做一次状态变更。默认：关闭。
Notifications (IPN): 通知会告知您的店铺某笔付款或退款已发生变化。模块会在每笔付款和退款时将通知网址发送给 dLocal Go，因此无需在 dLocal Go 控制台中进行任何配置。此字段显示两个网址：
通知使用您的 API Secret（HMAC-SHA256）进行验证。没有有效签名的通知会被拒绝。通知必须使用付款所在环境的凭据签名。之后，付款的状态、金额和币种始终从 dLocal Go API 重新读取；通知的内容不予信任。没有通知时，只有在顾客返回店铺时才会创建订单。
高级
Debug log: 将 dLocal Go 的请求和通知写入模块文件夹中的 logs/dlocal_p_debug.log.php。该文件无法通过网页打开。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 页面上接受一次性付款。它不在您的网站上提供银行卡表单，不支持保存银行卡、订阅或分开的授权与扣款。
订单和退款
订单状态
尚无订单：顾客已被引导至 dLocal Go 但尚未付款，或付款在 dLocal Go 仍待处理。此时只存在购物车。
Payment accepted 或 Delivered：付款已确认。订单状态为「付款已接受」；若启用了 Auto-complete orders，则为「已配送」。付款会以 dLocal 付款 ID 作为交易 ID 记录，备注中会显示环境和付款 ID。
dLocal payment on hold：dLocal Go 报告的金额或币种与购物车总额不符（例如，付款开始后购物车在另一个标签页中被修改），或付款是在订单取消后到达的。备注会说明原因。请与 dLocal Go 控制台核对，然后处理订单或退款。
Refunded：付款已通过本模块全额退款。
被拒绝、已过期或已取消的付款绝不会改变已有订单。如果已付款订单又收到第二笔付款，订单不会被修改。备注会提醒您在 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 之后拒绝或取消了它此前接受的退款，备注会警告资金没有退还给顾客。请再次退款给顾客或采用其他方式退款。
本模块不会创建贷项单（credit slip）。订单页面上标准的 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 以及链接 Manage licenses and domains in your account，该链接会打开您的 vibefox.net 账户。只有拥有本模块 Configure 权限的员工才能更改密钥。区块中的文字遵循后台语言（包含英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或带有日期的 License expired on。更改店铺地址后，或在账户中释放域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续按最后已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺设置中也是如此。将密钥从店铺中移除并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，结账页面不会向顾客显示 dLocal Go。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已发起的付款仍会被确认，退款也仍可进行。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。您在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 dLocal Go：请检查许可证是否有效、Enable/Disable 是否已开启，以及所选 Environment 的 API 密钥和 API Secret 是否已填写。如果缺少这些信息，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于购物车币种、顾客所在国家和顾客群组。
付款已成功，但没有创建订单：dLocal Go 无法访问通知网址（防火墙、基本身份验证、没有公网地址），并且顾客没有返回店铺。请开启 Debug log，查看 Log 字段，并在 dLocal Go 控制台中核对该付款。一旦收到通知或顾客打开 Check again，订单就会被创建。
通知返回 Missing signature 或 Invalid signature：设置中的 API 密钥和 Secret 不属于发送该通知的账户。通知使用付款所在环境的凭据进行验证，因此在您切换 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 密钥或 Secret。请检查所选环境的凭据。
顾客看到 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 的认可。