VibeFox dLocal for OpenCart — 帮助

系统要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

dLocal Go 账户：您需要 dLocal Go 账户的 API 密钥和 API 密码，可在 dLocal Go 控制台的 Payment integration 页面获取：测试环境为 dashboard-sbx.dlocalgo.com，正式环境为 dashboard.dlocalgo.com。测试环境和正式环境使用不同的凭据。本扩展仅适用于 dLocal Go，不适用于 dLocal Payments 企业版 API。

货币和国家：本扩展不做限制。dLocal Go 会根据您的 dLocal Go 账户，决定针对顾客所在国家和订单货币提供哪些付款方式。

可访问的店铺：dLocal Go 从其自身服务器发送付款和退款通知，因此通知网址必须能通过 HTTPS 从互联网访问。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包含 README.txt、OpenCart 3 安装包 wcp_dlocal_payment-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_dlocal_payment.ocmod.zip。只安装适合您 OpenCart 版本的安装包。两个版本的许可证密钥相同。

OpenCart 3

1. 进入后台，前往 Extensions > Installer，点击 Upload，选择文件 wcp_dlocal_payment-oc3-(version).ocmod.zip。本扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装程序，而是将此安装包中 upload 文件夹的内容复制到店铺的根目录。

2. 前往 Extensions > Extensions，选择类型 Payments。找到 VibeFox dLocal Payment，点击 Install（绿色的 + 按钮）。您的后台用户需要具有修改付款扩展列表的权限。

3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见许可证密钥）。

4. 输入测试环境的 API 密钥和 API 密码，以及用于真实付款的正式环境凭据。选择 Environment（参见配置）。

5. 开启 Enable/Disable 并点击 Save。在测试环境中完成一笔测试付款，然后将 Environment 切换为 Production。

OpenCart 4

1. 进入后台，前往 Extensions > Installer，点击 Upload，选择文件 wcp_dlocal_payment.ocmod.zip。不要重命名该文件：OpenCart 4 从文件名读取扩展代码，重命名后的安装包无法工作。

2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。

3. 前往 Extensions > Extensions，选择类型 Payments。找到 VibeFox dLocal Payment，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按照 OpenCart 3 的步骤 3 至 5 输入许可证密钥和 dLocal Go 凭据，并进行测试付款。设置页面及其字段在两个版本中相同。只有通知网址不同（参见 Notifications (IPN)）。

无需在 dLocal Go 控制台中进行任何设置：每次付款和退款时都会发送通知网址和返回网址。新安装默认关闭付款方式，并选择测试环境。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox dLocal Payment > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在未输入所选环境的 API 密钥和密码之前，页面会提示结账时将隐藏该付款方式，例如：Enter the sandbox API key and secret: until then the payment method is hidden at checkout.（请输入测试环境的 API 密钥和密码：在此之前，结账时将隐藏该付款方式。）当选择测试环境且已启用付款方式时，会显示 Sandbox mode is active: payments are simulated, no money is charged.（测试模式已启用：付款为模拟，不会扣款。）如果没有修改扩展的权限，页面只能显示设置，无法保存。

保存时，Title 不能为空且不能超过 128 个字符，Sort Order 必须是整数，Total 必须是大于或等于 0 的数字，并且地理区域和订单状态必须存在。否则不会保存任何内容，页面会显示错误。如果在未输入所选环境的密钥和密码的情况下启用了付款方式，设置仍会保存，但会显示上述警告。

dLocal Go

Enable/Disable：Enable dLocal Go 用于开启或关闭该付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：dLocal Go。必填。

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：通过 dLocal Go 使用本地银行卡、银行转账或现金付款。

Sort Order：dLocal Go 在结账时付款方式中的排列位置。可留空或输入整数。

Geo Zone：仅对所选地理区域内的付款地址提供 dLocal Go。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单必须达到的结账金额（以店铺默认货币计算），才会提供 dLocal Go。留空则对任何金额都提供 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 the saved value，然后点击 Save。

付款

Default country：dLocal Go 会显示顾客所在国家的付款方式，该国家依次取自付款地址，若无则取自配送地址。当订单两者都没有时，使用此国家。列表显示您店铺的国家。默认：Uruguay。

Auto-complete orders：让已付款订单获得 Complete Order Status，而不是 Paid Order Status。默认：关闭。

Notifications (IPN)：通知会告知您的店铺某笔付款或退款已发生变化。扩展会在每次付款和退款时将通知网址发送给 dLocal Go，因此无需在 dLocal Go 控制台中进行任何配置。此字段显示两个网址，它们由您 OpenCart 安装的店铺前台地址生成：

通知使用您的 API 密码（HMAC-SHA256）进行验证。没有有效签名的通知会被拒绝。通知必须使用付款所在环境的凭据签名。此后，付款的状态、金额和币种始终从 dLocal Go API 重新读取；不信任通知的内容。如果没有通知，订单只有在顾客返回店铺时才会获得状态。

订单

OpenCart 在 Confirm Order 步骤创建订单时不带状态（缺失订单）。只有在 dLocal Go 确认付款后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。

Paid Order Status：付款得到确认后的订单状态。默认：处理中。

Complete Order Status：当 Auto-complete orders 开启时，付款得到确认后的订单状态。默认：已完成。

On Hold (Review) Status：金额或币种与订单不符的付款，或在订单取消后到达的付款，会获得此状态，并附带说明原因的备注。默认：待付款，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Refunded Status：在订单页面将付款全额退款后设置。默认：已退款。

高级

Debug log：将 dLocal Go 的请求和通知写入 OpenCart 日志文件夹（storage/logs）中的 dlocal_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会被移动到备份文件中。API 凭据和个人数据不会被记录。错误和警告始终会被写入；其他条目仅在此选项开启时写入。默认：关闭。

Log：显示日志的大小和最新条目。点击 Clear log 可将其清空。

Delete data on uninstall：开启时，卸载扩展会删除网关设置和日志。订单的付款数据（dLocal 付款和退款）始终保留，以便现有订单继续正常运作。默认：关闭。

导入 / 导出

Export：Download JSON 会将设置保存为 JSON 文件。API 凭据不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的 API 凭据会被保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 dLocal Go）。在 Confirm Order 步骤中，顾客会看到您的描述以及提示 You will be redirected to the dLocal Go checkout page.（您将被重定向至 dLocal Go 结账页面。）在测试模式下，还会显示 Sandbox mode: no real payment is made.（测试模式：不会进行真实付款。）OpenCart 在此步骤创建订单，仍不带状态。顾客点击 Confirm Order 后，扩展会以订单货币为订单总额创建一笔 dLocal Go 付款，并附上顾客的国家、姓名、电子邮箱和电话，然后将顾客带到 dLocal Go 付款页面。在那里，顾客使用其所在国家的付款方式付款。在 dLocal Go 页面上，付款显示为 Order # 及订单编号。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。如果店铺不要求付款地址（OpenCart 4 默认设置），则使用配送地址和顾客姓名。

付款后，顾客返回您的店铺。只有在 dLocal Go 确认后，订单才会被标记为已付款：通过已签名的通知，或在顾客返回时由服务器向 dLocal Go API 发出请求。返回地址包含付款尝试的随机令牌。之后，订单以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面，并显示 Your payment with dLocal Go has been received.（我们已收到您通过 dLocal Go 的付款。）如果订单被置于审核状态，页面会显示 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 尚未确认付款（例如现金凭证尚未支付，或无法连接 dLocal Go），Payment confirmation 页面会请顾客不要重复付款，并提供 Check again 和 Back to checkout 按钮。dLocal Go 一旦确认付款，订单就会获得状态。在 OpenCart 4 中，dLocal Go 把顾客送回时浏览器不会发送店铺会话，因此扩展会先显示一个短暂页面，从您的店铺再次打开同一返回地址：顾客会保留购物车和登录状态。

如果顾客未付款就离开了 dLocal Go 页面，他会回到结账页面，并看到 The payment at dLocal Go was not completed. You can try again or choose another payment method.（dLocal Go 付款未完成。您可以重试或选择其他付款方式。）如果付款被拒绝或已过期，提示为 Your dLocal payment was not completed: it was declined or it expired. Please try again or choose another payment method.（您的 dLocal 付款未完成：已被拒绝或已过期。请重试或选择其他付款方式。）在 OpenCart 4 中，这些消息显示在结账页面上方。购物车会被保留。每次点击 Confirm Order 都会创建一笔新的 dLocal Go 付款。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 为结账保留一个订单并对其进行更新，因此新付款属于同一订单。较早的付款链接仍可付款，并会确认其对应的订单。在开始新的付款之前，会从 dLocal Go 读取同一订单和同一顾客会话（最近 24 小时）中未完成的付款：如果其中有一笔已付款，则确认其订单，顾客直接进入成功页面，无需再次付款。

OpenCart 4 会在成功页面显示之前一直把订单保留在结账中。如果该订单在未付款的情况下已被关闭（例如您取消了它），Confirm Order 或从 dLocal Go 的返回会将顾客带回结账页面，并显示 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.，随后的 Confirm Order 会为该购物车支付一个新订单。

如果 dLocal Go 无法发起付款，顾客会停留在 Confirm Order 步骤，并看到一条简短提示，例如 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.（此付款方式暂时不可用。请选择其他付款方式或联系我们。）技术原因会写入日志。

店铺处于维护模式时，通知也能正常工作：OpenCart 3 允许付款扩展的请求通过，而在 OpenCart 4 中，扩展会添加一个启动操作，让通知和顾客的返回请求通过。

本扩展仅在 dLocal Go 页面上处理一次性付款。您的网站上没有银行卡表单，不支持保存银行卡、订阅，也不支持单独的授权和扣款。

订单与退款

订单状态

无状态（缺失订单）：顾客已被发送至 dLocal Go，但尚未付款；或付款被拒绝或已过期；或在 dLocal Go 中仍处于待处理状态。在 Sales > Orders 中，此类订单仅在筛选条件 Order Status 设为 Missing Orders 时显示。

Paid Order Status（默认 处理中）或 Complete Order Status（默认 已完成）：付款已确认。当 Auto-complete orders 开启时，订单获得 Complete Order Status。备注中会显示环境和 dLocal 付款 ID。

On Hold (Review) Status（默认 待付款）：dLocal Go 报告的金额或币种与订单总额不符，或付款是在订单取消之后到达的。备注会说明原因。请对照 dLocal Go 控制台核实，然后发货或退款。

Refunded Status（默认 已退款）：付款已通过扩展全额退款。

被拒绝、已过期或已取消的付款，绝不会改变已有状态的订单。如果已付款的订单又收到第二笔付款，订单不会被改变，并会附上备注，请您在 dLocal Go 控制台中退还重复付款。当同一购物车（相同的顾客会话和购物车内容）在另一个订单中被再次付款时（例如在第二个浏览器标签页中），也会在已付款订单中添加同类备注；该另一订单不会获得任何状态。

备注是订单 History 中的条目，顾客不可见。

VibeFox dLocal Payment 选项卡

在 Sales > Orders 中打开一笔通过 dLocal Go 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox dLocal Payment 选项卡会显示 Payment ID、Environment（测试或正式）、付款的 Status、Paid / refunded 金额、退款表单、退款历史以及该订单的 dLocal Go notes。该选项卡对有权访问扩展的用户显示。

退款

在 VibeFox dLocal Payment 选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via dLocal Go。确认提问 Refund this amount through dLocal Go? This cannot be undone.（通过 dLocal Go 退还此金额？此操作无法撤销。）支持全额和部分退款。您需要具有修改扩展的权限（在 System > Users > User Groups 中设置）。退款按 dLocal Go 扣款的金额和币种进行；因此在金额或币种不一致之后，您可以退款的上限是顾客实际支付的金额，而不是订单总额。退款会使用付款所在环境的凭据发送至该环境。如果 dLocal Go 不接受退款，选项卡会显示错误，且不会记录任何退款。被接受的退款会连同退款 ID、状态和原因一起添加到退款历史和备注中。全额退款会将订单设置为 Refunded Status，且不通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会改变状态。只有 dLocal Go 确认付款后，才能进行退款。

随后 dLocal Go 会通过退款通知报告最终的退款状态，并将其添加到备注中。如果 dLocal Go 之后拒绝或取消了它此前已接受的退款，备注会警告资金未退还给顾客。请再次或以其他方式退款给顾客。

Sales > Returns 中的商品退货不会通过 dLocal Go 退回款项。在 dLocal Go 控制台中进行的退款不会在 OpenCart 中记录为退款。如有需要，请手动更新订单。

许可证密钥

本扩展需要使用 vibefox.net 提供的 VibeFox 许可证密钥。许可证区块 License — VibeFox dLocal Payment 位于 Extensions > Extensions > Payments > VibeFox dLocal Payment > Edit 的最上方，在设置之上。将密钥粘贴到 License key 中，然后点击 Activate。此后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方有一行 Product: opencart-payment-dlocal，以及一个链接 Manage licenses and domains in your account，可打开您在 vibefox.net 上的账户。只有对本扩展具有 Modify 权限的后台管理员才能更改密钥。该区块的文字跟随后台语言（包含英文和俄文）。

如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。更改店铺地址后，或在您的账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效的密钥时，结账时不会向顾客显示 dLocal Go。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one.（此付款方式不可用，请选择其他方式。）在同一浏览器中登录后台的管理员，仍可在店铺中看到该付款方式，并标记为 (unlicensed — visible to admins only)（未授权，仅管理员可见），以便您在购买密钥之前设置和测试扩展。在 OpenCart 4 中，此预览不可用：店铺看不到管理员的登录状态，因此在没有有效密钥的情况下，所有人都看不到该付款方式。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 可将其关闭，并隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，退款也照常运作。

许可证到期后，扩展仍会继续运行，但更新和支持需要续费。打开后台的 Dashboard 或 Edit 页面时，状态会自动重新检查：密钥输入后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。

故障排除

dLocal Go 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启，以及所选 Environment 的 API 密钥和 API 密码是否已填写。缺失时，设置页面会显示警告。另请检查付款地址是否位于所选 Geo Zone 内，以及订单是否达到设置中的 Total。

付款已成功，但订单仍无状态：dLocal Go 无法访问通知网址（防火墙、基本身份验证或没有公网 HTTPS 地址），且顾客也未返回店铺。请开启 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 密钥或 API 密码。请检查所选环境的凭据。

顾客看到 Payment gateway is not properly configured：所选环境的凭据缺失。

付款后订单处于审核状态：请阅读 VibeFox dLocal Payment 选项卡中的备注。付款的金额或币种与订单不符，或付款是在订单取消之后到达的。请发货或退款。

选项卡中没有退款表单：选项卡会说明原因：付款尚未确认、已全额退款、您的用户组无权修改扩展，或付款环境的凭据缺失。

退款时提示凭据缺失：该付款是在另一环境中完成的，而该环境的凭据未设置。请填写后重试。

开发人员须知：扩展会触发 OpenCart 事件 dlocal_p_payment_data（付款请求和订单，在创建付款之前）以及 dlocal_p_currency_decimals（货币的小数位数）。

卸载

前往 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox dLocal Payment 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态；重新安装后，这些设置会恢复为默认值。扩展的 OpenCart 事件也会被移除（在 OpenCart 4 中，还会移除其事件以及使 dLocal Go 能在维护模式下通过的启动操作）。如果 Delete data on uninstall 已开启，则其余网关设置（标题、描述、环境、凭据、默认国家、自动完成、日志记录）以及日志都会被删除。如果未开启，这些设置会保留，供以后重新安装时使用。订单的 dLocal 付款和退款始终会被保留，因此重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注。

在 OpenCart 4 中，若还要删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox dLocal Payment 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。

dLocal 是其各自所有者的商标。本扩展与 dLocal 无关联，也未获得 dLocal 认可。