VibeFox Pagar.me for OpenCart — 帮助
系统要求
OpenCart: 3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP: 8.0 或更高版本。
Currency: 巴西雷亚尔（BRL）。商店必须设置 BRL 货币（System > Localisation > Currencies），并且只有当顾客使用 BRL 结账且订单总额大于零时，才会显示该付款方式。
Pagar.me account: 您需要 Pagar.me 账户的密钥：测试密钥（sk_test_...）以及正式上线时使用的正式密钥（sk_...）。它们位于 Pagar.me 控制台的 Development > Keys 下。仅使用密钥（secret key）；公钥（pk_...）不需要。只能提供您 Pagar.me 账户中已启用的付款方式。
VibeFox license key: 请在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包含 README.txt、OpenCart 3 安装包 wcp_pagarme_gateway-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_pagarme_gateway.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_pagarme_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Pagar.me Gateway，点击 Install（绿色的 + 按钮）。您的管理员用户需要有修改付款扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见许可证密钥）。
4. 输入测试密钥（secret key），正式上线时再输入正式密钥。
5. 在 Pagar.me 控制台中，使用设置中显示的 URL 创建 webhook（参见配置）。
6. 开启 Enable / Disable，然后点击 Save。在 Test mode 开启的状态下进行测试付款，之后关闭它以接收真实付款。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_pagarme_gateway.ocmod.zip。不要重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Pagar.me Gateway，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 3 至 6 步输入许可证密钥、secret key 和 webhook。两个版本的设置页面及其字段完全相同。只有 Webhook URL 不同（参见付款通知（webhook））。
新安装时，付款方式默认关闭，测试模式默认开启。
配置
所有设置都位于扩展页面中：Extensions > Extensions > Payments > VibeFox Pagar.me Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会显示当前模式：TEST MODE（付款使用测试密钥创建，不会产生真实扣款）或 LIVE。当当前模式的密钥缺失时（此时付款方式会在结账时隐藏）、测试密钥不以 sk_test_ 开头时、正式密钥不以 sk_ 开头或为测试密钥时，以及商店的默认货币不是 BRL 时，页面都会发出警告。如果没有修改扩展的权限，页面会显示设置，但无法保存。
保存时，Title 不能为空（最多 128 个字符），Boleto due in (days) 必须是 1 到 30 之间的整数，Sort Order 必须是整数（允许负数），Total 必须是 0 或更大的数字，并且地理区域和订单状态必须存在。如果某个值有误，错误信息会指出该值，并且不会保存任何内容。
Pagar.me
Enable / Disable: Enable Pagar.me payments 用于开启或关闭该付款方式。默认：关闭。
Title: 顾客在结账时看到的付款方式名称。它也是保存在订单中的付款方式名称。默认：Pagar.me。必填，最多 128 个字符。
Description: 顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：通过 Pagar.me 安全付款（信用卡、PIX 或 boleto）。您将被重定向以完成付款。
Sort Order: Pagar.me 在结账时付款方式中的位置。留空或输入一个整数。
Geo Zone: 仅对所选地理区域内的付款地址提供 Pagar.me。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。在 OpenCart 4 中，当商店不要求付款地址时，使用配送地址。
Total: 订单需要达到的结账总额（以商店默认货币计）才会提供 Pagar.me。留空则对任何金额都提供 Pagar.me。
API 密钥
从 Pagar.me 控制台复制密钥（本节中有指向该控制台的链接）：Development > Keys。Pagar.me 对测试付款和正式付款使用同一个 API 地址；由密钥决定某笔付款是测试还是真实付款。
Test mode: 使用测试密钥，不会产生真实扣款。开启时，顾客会在 Confirm Order 步骤中看到 TEST MODE — Use test credentials. No real charges.。订单的状态查询和退款始终使用其付款创建时所处模式的密钥。默认：开启。
Test secret key: Pagar.me 测试密钥（sk_test_...）。测试模式开启时使用。
Live secret key: Pagar.me 正式密钥（sk_...）。测试模式关闭时使用。请妥善保密。
已保存的密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。若要删除已保存的密钥，请勾选字段下方的 Clear the saved key on save，然后点击 Save。
付款页面
Pagar.me 付款页面上提供的付款方式，每种都有自己的开关。请只选择您 Pagar.me 账户中已启用的方式。如果未选择任何方式，则提供信用卡、PIX 和 boleto。默认：信用卡、PIX 和 boleto。
Boleto due in (days): boleto 到期前的天数，范围 1 到 30。默认：3。保存时输入其他值会被拒绝，并显示 Boleto due in (days): enter a number from 1 to 30.
付款通知（webhook）
在 Pagar.me 控制台中打开 Settings > Webhooks，并使用本节 Webhook URL 中显示的 URL 创建 webhook。在 OpenCart 3 中，它的格式类似 https://your-store/index.php?route=extension/payment/wcp_pagarme_gateway/webhook，在 OpenCart 4 中则类似 https://your-store/index.php?route=extension/wcp_pagarme_gateway/payment/wcp_pagarme_gateway.webhook，由您 OpenCart 安装的前台地址生成。请严格按照设置中显示的内容复制。该 URL 必须能从互联网访问。
选择以下事件（本节中也列出了这些事件）：
webhook 不需要密码或签名。其内容永远不被信任：商店只从中获取 Pagar.me 订单 ID，并使用订单创建时所处模式的密钥，从 Pagar.me API 读取该订单。对于并非由本商店创建的 Pagar.me 订单，其通知会被忽略。如果没有 webhook，之后完成的 PIX 和 boleto 付款只有在顾客返回商店时才会被确认。
订单
OpenCart 在 Confirm Order 步骤中创建订单，此时没有状态（即缺失订单，missing order）。只有在 Pagar.me 通过 webhook 报告付款或顾客返回时，订单才会获得状态；Pagar.me 订单始终从 API 重新读取。下面每个字段都列出了您 OpenCart 的订单状态。
Order Status After Payment: Pagar.me 付款经核实后设置的状态。默认：处理中。
Awaiting Pagar.me Payment Status: 已生成 PIX 代码或 boleto，或卡付款正在审核中；Pagar.me 稍后确认款项。默认：待处理。
Pagar.me Payment On Hold Status: 该付款需要您审核（参见订单状态）。默认：待处理，因为 OpenCart 没有暂停状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。
Payment Failed Status: 等待中订单的付款失败、被取消或已过期。如果 Pagar.me 之后报告该付款已完成，订单将获得付款后的状态。默认：失败。
Cancelled Order Status: 您的商店用于已取消订单的状态。该扩展不会设置它：在此之后到达的 Pagar.me 付款会使订单进入审核状态。默认：已取消。
Refunded Status: 在订单页面或 Pagar.me 控制台中将付款全额退款后设置。默认：已退款。
高级
Debug log: 将 API 请求和通知写入 OpenCart 日志文件夹（storage/logs）中的 wc_pgm_debug.log.php。该文件无法通过网页打开。错误和警告始终会被记录。密钥和顾客数据（电子邮件、电话、CPF）不会被记录。默认：关闭。
Log: 显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall: 开启后，卸载扩展时会删除网关设置和日志。订单及其 Pagar.me 付款数据（退款所需）始终保留。默认：关闭。
导入 / 导出
Export: Download JSON 将设置保存为 JSON 文件。密钥不会被导出。
Import: 粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的密钥会被保留。
结账
在 Payment Method 步骤中，顾客选择付款方式（默认为 Pagar.me）。在 Confirm Order 步骤中，顾客会看到您的说明以及备注 You will be redirected to the Pagar.me payment page to pay by credit card, PIX, boleto or debit card. OpenCart 在此步骤中创建订单，仍然没有状态。在 OpenCart 4 中，顾客在付款方式区块中点击 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。当顾客点击 Confirm Order 时，扩展会以 BRL 为单位，按订单总额创建一个 Pagar.me 订单，并将顾客带到 Pagar.me 付款页面。包含税费、运费和其他附加费的订单行会作为商品项发送；如果订单有折扣（优惠券、礼券、积分），或各行之和与总额不符，则会以一行 Order #（含订单号）按总额发送。需要有效的电子邮件地址。
顾客的姓名和电子邮件会传递给 Pagar.me。CPF 或 CNPJ（11 或 14 位数字）取自顾客或付款地址中名称包含 CPF 或 CNPJ 的自定义字段；OpenCart 默认没有此类字段，如果希望传递该信息，请在 Customers > Custom Fields 中添加。在 OpenCart 4 中，如果商店不要求付款地址，则使用配送地址及其自定义字段。巴西手机号码也会一并传递。只有巴西地址（带有 8 位 CEP 和州信息）才会传递账单地址。没有 CPF 或 CNPJ 时，顾客需要在 Pagar.me 页面上输入。
付款后，顾客返回您的商店。只有在 Pagar.me 确认后，订单才会被标记为已付款：商店会从 API 读取 Pagar.me 订单，并且付款金额和货币必须与订单一致。随后，订单会以 OpenCart 的标准方式获得状态，发送常规订单邮件并更新库存，顾客会看到 OpenCart 的订单成功页面。已生成但尚未付款的 PIX 或 boleto 会使订单进入等待状态，页面还会显示 Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. 对于处于审核状态的订单，页面会显示 We are confirming your payment with Pagar.me. The order will be updated automatically — please do not pay again. 之后每次返回都会重新读取 Pagar.me 订单，因此即使 webhook 没有到达，期间完成的 PIX 或 boleto 付款也会被应用。
如果顾客未付款就返回，他会回到结账页面，并看到 The Pagar.me payment was not completed. You can try again or choose another payment method. 如果付款被拒绝或取消，提示为 The Pagar.me payment was declined or canceled. You can try again or choose another payment method. 购物车会保留。在 OpenCart 4 中，这些提示会显示在结账页面上方。如果订单已有状态，且其付款失败或已过期，提示为 The Pagar.me payment of your order was declined, canceled or has expired. Please place a new order or contact us. 如果购物车已经为空（例如订单在其 PIX 或 boleto 过期之前已到达成功页面），结账时没有任何需要支付的内容：Payment confirmation 页面会显示 The Pagar.me payment of order #N was not completed (declined, canceled or expired), so the order will not be shipped. To buy these items, please place a new order. 并附带 Continue 按钮。如果无法连接到 Pagar.me，Payment confirmation 页面会要求顾客不要重复付款，并提供 Check again 和 Back to checkout 按钮。
OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单。OpenCart 4 则为结账保留一个订单并对其进行更新，因此在付款未完成或被拒绝后，顾客会再次为同一订单付款。在新付款之前，扩展会检查同一购物车的先前尝试：如果其中有一笔已付款，或其 PIX 或 boleto 正在等待付款，顾客会直接进入成功页面，而无需再次付款。如果同一订单仍有未关闭的 Pagar.me 付款页面，且金额和模式相同，则会重复使用该页面；其他未关闭的页面会先在 Pagar.me 上关闭。如果同一购物车的第二个 Pagar.me 订单仍被付款，它不会被应用，并且已付款订单上的备注会要求您退还该重复付款。
OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单在此期间已被关闭（例如其 PIX 或 boleto 已过期、付款失败，或您取消或退款了该订单），Confirm Order 会将顾客送回结账页面，并显示 Your previous order was cancelled or its payment failed. Please confirm the order again.；如果订单在您关闭之前已付款，则显示 This order was closed by the store, so it will not be shipped. Your cart is kept: confirm the order again to pay. 下一次 Confirm Order 会为新订单付款。当顾客从 Pagar.me 返回到一个已付款、随后被您关闭的订单时，顾客会在结账页面看到相同的提示；如果购物车已为空，则会看到一个页面，显示 Order #(编号) was closed by the store, so it will not be shipped. To buy these items, please place a new order. 如果结账流程中的订单已有状态，且购物车中现在包含其他商品或数量，顾客会被送回结账页面，新购物车将获得一个新订单。
如果 Pagar.me 无法启动付款，顾客会停留在 Confirm Order 步骤，并看到简短提示，例如 Could not connect to Pagar.me. Please try again in a moment.，或 Pagar.me 关于账单信息无效的提示。技术原因会写入日志。
商店处于维护模式时，webhook 仍然有效：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 中，扩展会添加一个启动动作（startup action），用于放行 webhook 以及顾客从 Pagar.me 的返回请求。
该扩展在您的结账页面中没有银行卡表单，不支持保存银行卡、订阅或定期付款、分期规则、分账付款（市场）以及仅授权的银行卡付款。
订单与退款
订单状态
No status (missing order): 顾客已被转到 Pagar.me，但尚未付款，也未生成 PIX 或 boleto；或者付款被拒绝。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设为 Missing Orders 时才会显示。
在 OpenCart 4 中，结账流程中未付款的订单可能会获得 Voided 状态，该状态由 OpenCart 4 在顾客返回 Confirm Order 步骤时设置。扩展会将此类订单视为没有状态的订单，之后的付款仍会确认该订单。
Order Status After Payment (default Processing): 付款已确认。备注会显示 Pagar.me 订单 ID（or_...）和付款方式。
Awaiting Pagar.me Payment Status (default Pending): 已生成 PIX 或 boleto（或卡付款正在审核中），并等待付款。当 Pagar.me 确认付款后，订单会转为 Order Status After Payment。
Pagar.me Payment On Hold Status (default Pending): boleto 只付了部分款项；或已付金额或货币与订单不符；或付款是在订单被取消或退款之后到达的；或已付订单上发起了拒付（chargeback）。备注会说明原因。请检查订单，然后完成订单或退还付款。
Payment Failed Status (default Failed): 等待中或暂停中订单的付款失败，或其 Pagar.me 订单被取消或已过期（例如未付款的 boleto）。如果 Pagar.me 之后报告了付款，订单仍会转为 Order Status After Payment。
Refunded Status (default Refunded): 付款已通过该扩展全额退款，或在 Pagar.me 中被退款或取消。
每个 Pagar.me 状态只应用一次，因此重复的 webhook 或返回不会添加备注或付款。备注是订单 History 中的条目，顾客看不到。
VibeFox Pagar.me Gateway 选项卡
在 Sales > Orders 中打开一笔通过 Pagar.me 付款的订单。在订单页面底部，History 和 Additional 旁边，VibeFox Pagar.me Gateway 选项卡会显示 Pagar.me order 的 ID（测试付款会带有 Test mode 标签）、Payment method、Status、Paid / refunded 金额、退款表单、退款记录以及该订单的 Pagar.me notes。该选项卡对有权访问此扩展的用户可见。
退款
在 VibeFox Pagar.me Gateway 选项卡中输入 Amount（尚未退款的金额会自动填入），可选填写 Reason (optional)，然后点击 Refund via Pagar.me。确认提示 Refund this amount through Pagar.me? This cannot be undone.。支持银行卡和 PIX 付款的全额及部分退款。您需要修改该扩展的权限（在 System > Users > User Groups 中设置）。您最多可以退还 Pagar.me 实际扣款的金额；因此，出现金额差异后，上限是顾客实际支付的金额，而不是订单总额。退款使用付款时所处模式的密钥发送，因此该模式的 secret key 必须已设置。只有在 Pagar.me 确认后才会记录退款；否则选项卡会显示错误，例如 Pagar.me refused the refund: ... 或 Pagar.me did not confirm the refund，并且不会记录任何退款。成功的退款会连同扣款 ID 一起添加到退款记录和备注中。全额退款会将订单设为 Refunded Status，且不会通知顾客，也不会将商品退回库存，与手动更改状态一样。部分退款不会更改状态。Pagar.me 报告付款后即可进行退款。
boleto 付款只能退还到顾客的银行账户。请在 Pagar.me 控制台中退款，然后在 OpenCart 中手动记录该退款。在 Sales > Returns 中的商品退货不会通过 Pagar.me 退回款项。
在 Pagar.me 控制台中进行的全额退款或取消会通过 webhook 到达，将订单设为 Refunded Status 并添加备注。拒付会添加备注，并将已付款订单置于审核状态。
许可证密钥
该扩展需要来自 vibefox.net 的 VibeFox 许可证密钥才能使用。License — VibeFox Pagar.me Gateway 许可证区块是 Extensions > Extensions > Payments > VibeFox Pagar.me Gateway > Edit 页面上的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示被遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店删除密钥）。其下方是 Product: opencart-payment-pagarme 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有对该扩展拥有 Modify 权限的管理员用户才能更改密钥。该区块的文字遵循后台语言（包括英文和俄文）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。在更改商店地址之后，或在您的账户中释放了一个域名名额之后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用上次已知的状态运行。
一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店删除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
如果没有有效的密钥，结账时不会向顾客显示 Pagar.me。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 一个在同一浏览器中登录后台的管理员用户仍会在商店中看到该付款方式，并带有 (unlicensed — visible to admins only) 标记，这样您可以在购买密钥之前设置和测试该扩展。在 OpenCart 4 中，此预览不可用：商店无法看到管理员的登录状态，因此在没有有效密钥的情况下，所有人都看不到该付款方式。打开过一次 Edit 页面之后，后台 Dashboard 上会出现一条提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已经开始的付款仍会被确认，退款仍可使用。
许可证到期后，扩展仍会继续工作，但更新和支持需要续订。打开后台的 Dashboard 或 Edit 页面时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。
故障排除
Pagar.me does not appear at checkout: 请检查许可证是否有效，Enable / Disable 是否已开启，当前模式的 secret key 是否已设置（测试模式下为 Test secret key，正式模式下为 Live secret key），以及顾客是否使用 BRL 结账。如果缺少密钥，设置页面会显示警告。另外请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。
The payment went through, but the order stays without a status or in the awaiting status: webhook 无法正常工作。请在 Pagar.me 控制台中检查您所用账户和模式的 webhook 是否存在，其 URL 是否与 Webhook URL 中显示的完全一致，以及上面列出的事件是否已选中。每当顾客返回商店时，也会检查该订单。
The webhook answers verification failed, retry later: 商店无法从 API 读取 Pagar.me 订单，例如该模式的密钥缺失或 API 没有响应。Pagar.me 会重试该 webhook。
The webhook answers busy: 购物车在同一时刻正被另一个请求处理，或无法设置订单状态。Pagar.me 会重试该 webhook。请开启 Debug log 查看原因。
The webhook answers unknown order: 该 Pagar.me 订单不是由本商店创建的，例如同一账户下其他商店的订单。不会做任何更改。
The webhook answers invalid payload or invalid order id: 该请求不是 Pagar.me 通知。不会做任何更改。
The customer sees Pagar.me payments are not available right now: secret key 错误或缺失。请检查当前模式的密钥。
The customer sees Pagar.me could not start the payment: Pagar.me 拒绝了账单信息，例如自定义字段中的 CPF。该信息会说明问题；完整原因在日志中。
The customer sees A valid billing email is required for Pagar.me.: 订单的电子邮件地址无效。
The customer sees Pagar.me only supports payments in Brazilian Real (BRL).: 结账使用的是其他货币。
The customer sees This order already has a Pagar.me payment that the store has to review: 该购物车之前的一笔付款需要您审核。请检查 Pagar.me 控制台和日志。
Order is in the review status after payment: 请阅读 VibeFox Pagar.me Gateway 选项卡中的备注（参见订单状态），然后完成订单或退还付款。
No refund form in the tab: 选项卡会说明原因：付款尚未被报告、已全额退款、您的用户组没有修改扩展的权限，或该付款所用模式的 secret key 未设置。
Refund fails for a boleto: boleto 付款无法通过 API 退款。请在 Pagar.me 控制台中退款，并手动记录该退款。
面向开发者：在发送 Pagar.me 订单之前，扩展会以请求正文和订单触发 OpenCart 事件 wc_pgm_order_data。付款金额必须保持等于订单总额。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Pagar.me Gateway 旁边的 Uninstall（红色的 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable / Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态，这些设置在重新安装时会恢复为默认值。该扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还包括其事件以及在维护模式下放行 webhook 和顾客返回的启动动作）。如果 Delete data on uninstall 已开启，其余网关设置（标题、说明、测试模式、secret key、付款方式、boleto 天数、日志记录）以及日志都会被删除。如果未开启，这些设置会保留，供以后重新安装时使用。Pagar.me 的付款和退款记录始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Pagar.me Gateway 旁边的 Uninstall（橙色的 − 按钮），然后点击 Delete（红色的垃圾桶按钮）以删除已上传的安装包。
Pagar.me 是其各自所有者的商标。本扩展与 Pagar.me 无关联，也未获得 Pagar.me 的认可或背书。