VibeFox Pagar.me for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在更旧的 PHP 版本上安装。
货币：巴西雷亚尔（BRL）。对于使用其他货币的购物车，付款方式将被隐藏。
Pagar.me 账户：您需要 Pagar.me 账户的密钥：测试密钥（sk_test_...），以及在正式上线时使用的正式密钥（sk_...）。它们位于 Pagar.me 控制台的 Development > Keys 下。只使用密钥；不需要公钥（pk_...）。只能提供在您的 Pagar.me 账户中已启用的付款方式。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Pagar.me Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见许可证密钥）。
4. 输入测试密钥；正式上线时，输入正式密钥。
5. 在 Pagar.me 控制台中，使用设置中显示的 URL 创建 Webhook（见配置）。
6. 开启 Enable / Disable 并点击 Save。在开启 Test mode 的情况下进行测试付款，然后关闭它以接收真实付款。
安装时，模块会创建两个订单状态：Awaiting Pagar.me payment 和 Pagar.me payment on hold。PrestaShop 会为所有货币、国家和顾客组提供新的付款模块。您可以在 Payment > Preferences 中对其进行限制。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Pagar.me Gateway > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。在字段上方，页面会显示当前模式：TEST MODE（付款使用测试密钥创建，不产生真实扣款）或 LIVE。当当前模式的密钥缺失（此时结账页面会隐藏该付款方式）、测试密钥不以 sk_test_ 开头、正式密钥不以 sk_ 开头或为测试密钥，以及店铺默认货币不是 BRL 时，页面会发出警告。
Pagar.me
Enable / Disable：Enable Pagar.me payments 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Pagar.me。必填。
Description：结账时显示在付款方式下方的文字。默认：Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.
API 密钥
从 Pagar.me 控制台复制密钥：Development > Keys。Pagar.me 对测试和正式付款使用同一个 API 地址；由密钥决定某笔付款是测试还是真实付款。
Test mode：使用测试密钥，不产生真实扣款。开启期间，顾客会在付款方式下方看到 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 saved secret keys：勾选某个密钥并点击 Save 即可将其删除。空字段会保留已保存的值。
付款页面
Payment methods：在 Pagar.me 付款页面上提供的付款方式。请仅选择您 Pagar.me 账户中已启用的付款方式。如果一个都未勾选，则使用默认付款方式。默认：Credit card, PIX and Boleto。
Boleto due in (days)：boleto 的到期天数，范围为 1 至 30。在 Pagar.me 确认付款之前，订单会保持在 Awaiting Pagar.me payment 状态。默认：3。保存时，其他值会被拒绝，并显示 Boleto due in (days): enter a number from 1 to 30.
付款通知（Webhook）
在 Pagar.me 控制台中打开 Settings > Webhooks，并使用本部分 Webhook URL 中显示的 URL 创建 Webhook。使用友好 URL 时，它的样子是：https://your-shop/module/wcp_pagarme_gateway/webhook，可能会带有语言代码，例如 /en/。请按设置中显示的内容完整复制。
选择以下事件（本部分也列出了这些事件）：
Webhook 不需要密码或签名。其内容绝不会被信任：店铺只从中获取 Pagar.me 订单 ID，并使用该订单创建时所处模式的密钥通过 Pagar.me API 读取该订单。同一 Pagar.me 账户中其他店铺订单的通知会被忽略。如果没有 Webhook，之后完成的 PIX 和 boleto 付款只有在顾客返回店铺时才会被确认。
高级
Debug log：将 API 请求和通知记录到模块文件夹中的 logs/wc_pgm_debug.log.php。该文件无法通过网页打开。错误和警告始终会被记录。密钥和顾客数据不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可将其清空。
Delete Data on Uninstall：开启后，卸载模块时会删除网关设置和日志。订单、其 Pagar.me 付款数据（退款所需）以及订单状态会被保留。默认：关闭。
结账
在付款步骤中，顾客选择付款方式（默认为 Pagar.me）并确认。需要有效的电子邮件地址。模块会以 BRL 计算的购物车总额创建一个 Pagar.me 订单，其中包含购物车商品行、运费和礼品包装（如果购物车有折扣，则改为一行 Order #，并附上购物车编号），然后将顾客转到 Pagar.me 付款页面。此时，您的店铺中还不存在任何订单。
顾客的姓名和电子邮件会传递给 Pagar.me。CPF 或 CNPJ 取自地址中的 Identification number 字段，或取自 VAT number；同时还会传递巴西手机号码。只有在地址为巴西地址、包含 8 位 CEP 且包含州的情况下，才会传递账单地址。PrestaShop 默认没有巴西的州，因此顾客通常会在 Pagar.me 页面上填写地址。如果没有 CPF 或 CNPJ，顾客也需要在那里填写。
付款后，顾客会返回您的店铺。只有在 Pagar.me 确认之后，订单才会被标记为已付款：店铺通过 API 读取 Pagar.me 订单，且已付金额和货币必须与购物车一致。已完成的银行卡、PIX 或 boleto 付款会创建状态为 Payment accepted 的订单，顾客会看到标准的订单确认页面，并显示 Your payment with Pagar.me has been received. 已生成但尚未付款的 PIX 或 boleto 会创建状态为 Awaiting Pagar.me payment 的订单，页面会显示 Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. 之后每次返回都会重新读取 Pagar.me 订单，因此即使 Webhook 没有到达，期间完成的 PIX 或 boleto 付款也会被应用。如果此类订单的付款失败或已过期，页面会显示 Your Pagar.me payment was not completed. Please contact us about this order.
如果顾客没有付款就返回，会回到结账页面，并显示 The Pagar.me payment was not completed. You can pay the order below. 如果付款被拒绝或取消，提示为 The Pagar.me payment was declined or canceled. You can try again below. 购物车会被保留。如果订单已存在且其付款失败或已过期，提示为 The Pagar.me payment of your order was declined, canceled or has expired. Please place a new order or contact us. 如果无法连接到 Pagar.me，将显示 Payment confirmation 页面，提醒顾客不要重复付款，并提供 Check again 和 Back to checkout 按钮。
顾客再次付款时，如果金额和模式相同，则会复用仍然打开的 Pagar.me 付款页面；否则，在创建新页面之前会先在 Pagar.me 中将其关闭。如果之前的尝试在此期间已付款，或其 PIX 或 boleto 仍在等待付款，则会在不再次付款的情况下创建订单。如果无法关闭之前的页面，它会继续与购物车关联，因此在该页面完成的付款仍会被记录。
如果 Pagar.me 无法启动付款，顾客会停留在结账页面，并看到简短提示，例如 Could not connect to Pagar.me. Please try again in a moment.，或 Pagar.me 关于账单信息无效的提示。技术原因会记录到日志中。
即使店铺处于维护模式，Webhook 仍然有效，并且不受店铺国家限制的影响。
本模块在您的结账流程中没有银行卡表单，不支持保存银行卡、订阅或定期付款、分期规则、拆分付款（多商户平台）、仅授权的银行卡付款，也不支持 Pagar.me Hub 集成。
订单与退款
订单状态
No order yet：顾客已被转到 Pagar.me，但尚未付款，也未生成 PIX 或 boleto。目前只存在购物车。
Payment accepted：付款已确认。该付款会以 Pagar.me 订单 ID（or_...）作为交易 ID 记录，并且备注中会显示 Pagar.me 订单和付款方式。
Awaiting Pagar.me payment：已生成 PIX 或 boleto（或银行卡付款正在审核），正在等待付款。当 Pagar.me 确认付款时，订单会转为 Payment accepted。
Pagar.me payment on hold：boleto 仅部分付款；或已付金额或货币与订单不符（例如，付款开始后购物车被修改）；或付款在订单被取消后才到达；或已付款订单上发起了拒付。备注会说明原因。请检查订单并完成处理，或对付款进行退款。
Payment error：等待中或被保留的订单付款失败，或其 Pagar.me 订单已取消或已过期（例如未付款的 boleto）。如果 Pagar.me 之后报告了付款，订单仍会转为 Payment accepted。
Refunded：付款已通过模块全额退款，或在 Pagar.me 中已退款或取消。
每个 Pagar.me 状态只会应用一次，因此重复的 Webhook 或返回不会添加备注或付款。如果同一购物车的第二个 Pagar.me 订单被付款，备注会提醒您在 Pagar.me 控制台中对重复付款进行退款。
Pagar.me 付款区块
订单页面会显示 Pagar.me payment 区块，其中包括 Pagar.me 订单 ID 和扣款 ID、付款方式、状态、已付和已退金额、测试付款的 Test mode 标记、退款记录以及订单的 Pagar.me notes。
退款
在 Pagar.me payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Pagar.me。确认提问 Refund this amount through Pagar.me? This cannot be undone. 支持对银行卡和 PIX 付款进行全额和部分退款。您需要具备编辑订单的权限。您最多可以退款至 Pagar.me 实际收取的金额，因此在金额不符之后，上限是顾客实际支付的金额，而不是订单总额。退款使用付款时所处模式的密钥发送，因此必须已设置该模式的正式或测试密钥。只有在 Pagar.me 确认退款后才会记录退款；否则，该区块会显示错误，例如 Pagar.me refused the refund: ... 或 Pagar.me did not confirm the refund，并且不会记录任何退款。成功的退款会连同扣款 ID 一起添加到退款记录和备注中。全额退款会将订单设置为 Refunded。部分退款不会改变状态。Pagar.me 报告付款后，即可进行退款。
boleto 付款只能退还到顾客的银行账户。请在 Pagar.me 控制台中退款，然后在 PrestaShop 中手动记录退款。
模块不会生成退款单（credit slips）。订单页面上的 PrestaShop 标准退款按钮不会通过 Pagar.me 退回款项。
在 Pagar.me 控制台中进行的全额退款或取消会通过 Webhook 传回，将订单设置为 Refunded 并添加备注。拒付会添加备注，并将已付款订单设置为 Pagar.me payment on hold。
许可证密钥
本模块需要使用在 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Pagar.me Gateway 是 Modules > Module Manager > VibeFox Pagar.me Gateway > Configure 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、许可证状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: presta-payment-pagarme 一行，以及打开您 vibefox.net 账户的 Manage licenses and domains in your account 链接。只有拥有本模块 Configure 权限的员工才能更改密钥。区块中的文字遵循后台语言（包含英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。更改店铺地址后，或在您的账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续使用最后已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺设置中同样如此。从店铺中移除密钥不会释放域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，结账页面不会向顾客显示 Pagar.me。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 中的 Alerts 标签页会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也照常可用。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron job。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时未显示 Pagar.me：请检查许可证是否有效、Enable / Disable 是否开启、当前模式的密钥是否已设置（测试模式为 Test secret key，正式模式为 Live secret key），以及购物车货币是否为 BRL。当密钥缺失时，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于该购物车货币、顾客所在国家以及顾客所在的顾客组。
付款已完成，但未创建订单，或订单停留在 Awaiting Pagar.me payment：Webhook 无法正常工作。在 Pagar.me 控制台中，请检查该账户和模式下是否存在 Webhook，其 URL 是否与 Webhook URL 中显示的完全一致，以及上文列出的事件是否均已选中。每次顾客返回店铺时，也会检查该订单。
Webhook 返回 verification failed, retry later：店铺无法通过 API 读取 Pagar.me 订单，例如该模式的密钥缺失或 API 没有响应。Pagar.me 会重试该 Webhook。
Webhook 返回 busy：购物车在同一时刻正被另一个请求更新，或订单无法创建（例如模块已禁用）。Pagar.me 会重试该 Webhook。请开启 Debug log 查看原因。
Webhook 返回 unknown order：该 Pagar.me 订单并非由本店铺创建，例如同一账户中其他店铺的订单。不会做任何更改。
顾客看到 Pagar.me payments are not available right now：密钥错误或缺失。请检查当前模式的密钥。
顾客看到 Pagar.me could not start the payment：Pagar.me 拒绝了账单信息，例如地址中 Identification number 字段的 CPF。提示会说明问题；完整原因记录在日志中。
顾客看到 Pagar.me only supports payments in Brazilian Real (BRL)：购物车使用的是其他货币。
顾客看到 This order already has a Pagar.me payment that the store has to review：该购物车之前的一笔付款需要您进行审核。请检查 Pagar.me 控制台和日志。
付款后订单处于 Pagar.me payment on hold：请阅读 Pagar.me payment 区块中的备注（参见订单状态），然后完成订单或对付款进行退款。
boleto 退款失败：boleto 付款无法通过 API 退款。请在 Pagar.me 控制台中退款，并手动记录退款。
退款失败并显示与模式有关的提示：付款是在测试或正式模式下完成的，而该模式的密钥未设置。请输入该密钥后重试。
开发者可以在发送之前，通过钩子 actionWcpPagarmeOrderData 修改 Pagar.me 订单数据。
卸载
进入 Modules > Module Manager，打开 VibeFox Pagar.me Gateway 旁边的菜单，然后选择 Uninstall。此模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，网关设置和日志将被删除。如果已关闭，所有设置都会保留，以便以后重新安装。订单的 Pagar.me 付款数据以及订单状态 Awaiting Pagar.me payment 和 Pagar.me payment on hold 始终会被保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
Pagar.me 是其各自所有者的商标。本模块与 Pagar.me 无关联，也未获得 Pagar.me 的认可。