VibeFox MercadoPago for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
商店货币：您 MercadoPago 账户所在国家的货币：ARS（阿根廷）、BRL（巴西）、CLP（智利）、COP（哥伦比亚）、MXN（墨西哥）、PEN（秘鲁）或 UYU（乌拉圭）。MercadoPago 以账户货币扣款且不进行转换，因此购物车使用其他货币时，付款方式会被隐藏。
MercadoPago 账户：您需要在 MercadoPago 开发者面板（Your integrations > your application > Credentials）中创建一个应用，并同时获取其测试凭据（以 TEST- 开头）和正式凭据（以 APP_USR- 开头）：每组凭据都包括一个 Public Key 和一个 Access Token。若要启用可选的通知签名验证，还需要 your application > Webhooks 中的签名密钥。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台依次进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox MercadoPago Gateway，再点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 选择 Account country，输入测试和正式凭据；如有需要，在您的 MercadoPago 应用中设置通知（参见配置）。
5. 开启 Enable / Disable，然后点击 Save。使用 MercadoPago 测试卡在测试模式下完成一笔付款，然后关闭 Test mode。
安装时，模块会创建两个订单状态：Awaiting MercadoPago payment 和 MercadoPago payment on hold。PrestaShop 会将新的付款模块分配给安装时已启用的国家。请在 Payment > Preferences 中检查模块的货币、国家和客户组。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox MercadoPago Gateway > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。在测试模式开启时，字段上方会显示 Test mode is on: the TEST- credentials are used and no real money is charged. 页面还会在以下情况发出警告：当前模式的 Public Key 或 Access Token 缺失；商店货币与 MercadoPago 账户货币不一致（此时结账时会隐藏付款方式）；凭据所属账户的国家与 Account country 不同。
保存时，前缀与预期不符（测试字段应为 TEST-，正式字段应为 APP_USR-）的凭据不会被保存，并显示错误 must start with … — the previous value was kept.。模块还会向 MercadoPago 查询每个 Access Token 所属的国家。如果无法验证当前模式的令牌，或账户不在支持的国家，或国家与 Account country 不一致，就会显示错误。此时模块将使用账户所在的国家。
MercadoPago
Enable / Disable：Enable MercadoPago card payments 用于开启或关闭该付款方式。默认：off。
Title：顾客在结账时看到的付款方式名称。订单中保存的也是该名称。默认：Credit or debit card (MercadoPago)。必填。
Description：结账时银行卡字段上方显示的文字。默认：Pay securely with your credit or debit card. Card data is sent directly to MercadoPago.
MercadoPago 账户
请在 MercadoPago 开发者面板中获取应用的凭据：Your integrations > your application > Credentials。测试凭据以 TEST- 开头，正式凭据以 APP_USR- 开头。
Account country：您 MercadoPago 账户所在的国家。它决定扣款货币、银行卡字段的语言，以及是否要求填写持卡人证件。商店货币必须与之相同，例如阿根廷对应 ARS。保存凭据时，系统会将该国家与账户进行核对。默认：Argentina (ARS)。
Test mode：测试模式下使用 TEST- 凭据，您使用 MercadoPago 测试卡付款；结账时会显示 TEST MODE 标识。关闭后，将使用正式凭据对真实银行卡扣款。默认：on。
Test Public Key：以 TEST- 开头。在浏览器中用于将银行卡信息令牌化。
Test Access Token：以 TEST- 开头。仅在服务器上使用。请妥善保密。
Production Public Key：以 APP_USR- 开头。
Production Access Token：以 APP_USR- 开头。仅在服务器上使用。请妥善保密。
已保存的 Access Token 和 Webhook 密钥不会再次显示。字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。
付款选项
Maximum installments：顾客可选择的最高分期数，范围为 1 至 24。1 = 仅一次性付款，此时不显示分期字段。服务器端同样执行此限制。默认：1。
付款通知（Webhook）
银行卡付款通常会立即得到最终结果。MercadoPago 保留审核中（处理中或待处理）的付款，将通过 MercadoPago 通知完成。如果您的商店拥有公网地址（不是 localhost，也不是 .local 或 .test 域名），模块会在每笔付款中发送通知 URL。您也可以在 your application > Webhooks 中添加该 URL，事件选择 Payments。URL 显示在本节的 Notification URL 中。使用友好 URL 时，其格式类似 https://your-shop/en/module/wcp_mercadopago_gateway/webhook?source_news=webhooks。请按设置中显示的内容完整复制该 URL。
通知本身从不被直接信任。模块会使用付款所在环境的 Access Token，通过 MercadoPago API 重新读取付款，并将其与您商店的某次付款尝试进行绑定。如果没有通知，审核中的订单会一直保持在 Awaiting MercadoPago payment，直到您手动更新。
模块会处理以下 MercadoPago 付款状态：
Webhook secret signature：可选。在 your application > Webhooks 中显示的签名密钥。设置后，不带有效 x-signature 的通知会被拒绝（HTTP 401）。
Clear saved secrets：勾选 Test Access Token、Production Access Token 或 Webhook secret signature，然后点击 Save 即可删除。空字段会保留已保存的值。
高级
Debug log：将 MercadoPago 的请求和通知写入模块文件夹中的 logs/wc_mpg_debug.log.php。该文件无法通过网页打开。即使此设置关闭，错误也始终会被记录。Access Token、银行卡令牌和付款人数据不会被记录。默认：off。
Log：显示日志的大小和最新记录。点击 Clear log 可清空日志。
Delete data on uninstall：开启后，卸载模块时会删除网关设置和日志。MercadoPago 付款记录、退款以及模块的订单状态始终会保留，因此之前已付款的订单即使在重新安装后也可以退款。默认：off。
结账
在付款步骤中，顾客选择付款方式（默认为 Credit or debit card (MercadoPago)），并填写银行卡字段：Card number、Expiry (MM/YY)、Security code 和 Cardholder name。根据国家和银行卡的不同，顾客还需选择 Document type 并输入 Document number，选择 Card issuer，并选择 Installments 的数量。分期选项和利息由 MercadoPago 针对购物车总额提供。银行卡表单可与 Classic 和 Hummingbird 主题配合使用。
顾客确认后，MercadoPago 将银行卡转换为一次性令牌，您的商店随即在服务器上按购物车总额创建付款。顾客的电子邮件和姓名、证件以及购物车编号会传递给 MercadoPago；付款会显示为 Cart #、购物车编号和您的商店名称。CLP 和 COP 金额按整数收取。在 MercadoPago 作出响应之前，不会存在任何订单。
批准的付款会生成已付款订单，顾客会看到订单确认页面，显示 Your card payment has been received. 审核中的付款会生成 Awaiting MercadoPago payment 订单，页面显示 MercadoPago is reviewing your payment. Your order will be updated automatically as soon as MercadoPago confirms it. 如果审核中的付款之后被拒绝，页面会显示 Your MercadoPago payment was not completed. Please contact us about this order. 处于保留状态的订单显示 Your payment is being reviewed. We will update your order as soon as the review is complete.
被拒绝的银行卡不会生成订单。顾客会停留在付款步骤，并看到简短的原因，例如 Your card has insufficient funds. Please use another card or payment method. 或 Please check the security code of your card. 顾客可以更正信息或更换银行卡；每次尝试都会生成新的银行卡令牌。
如果 MercadoPago 没有响应，顾客会看到 We could not confirm your payment with MercadoPago. Please wait a minute before trying again — if the payment went through, your order will be updated automatically. 下一次尝试会先查询该笔付款，因此银行卡不会被重复扣款。在购物车付款过程中再次点击，会显示 This order is already being paid. Please wait a moment and check your e-mail before trying again. 已生成订单的购物车绝不会再次扣款；顾客会被引导至该订单的确认页面。
即使商店处于维护模式，通知 URL 仍然有效，并且不会受到您商店国家限制的阻挡。
本模块仅接受信用卡和借记卡。不支持 Checkout Pro 跳转、MercadoPago 钱包或余额、现金（Rapipago、OXXO、boleto 等）、Pix、PSE 或 Yape 付款，不支持保存银行卡或订阅，不支持单独授权和扣款，不支持 3-D Secure 验证，也不支持货币转换。
订单和退款
订单状态
No order：银行卡被拒绝，或 MercadoPago 尚未作出响应。此时只存在购物车。
Payment accepted：MercadoPago 已批准付款，且金额和币种与购物车一致。付款会以 MercadoPago 付款 ID 作为交易 ID 记录，备注中显示付款 ID、环境和分期数。
Awaiting MercadoPago payment：付款处于审核中（处理中或待处理），等待 MercadoPago 通知。MercadoPago 批准后，订单会变为 Payment accepted。
MercadoPago payment on hold：已批准的金额或币种与购物车不一致，或 MercadoPago 返回了意外的状态。备注会说明原因。请检查订单，然后完成订单或退款。
Payment error：审核中的付款被拒绝或取消。备注中显示状态及其详情。
Refunded：付款已通过模块全额退款。
如果 MercadoPago 为已取消或已退款的订单批准了付款，订单状态不会改变，备注会提示您完成订单或退款。如果已付款的订单又收到了另一笔付款，备注会提示您在 MercadoPago 后台退还多收的付款。
MercadoPago 付款区块
订单页面会显示 MercadoPago payment 区块，包括付款 ID、付款状态、环境（测试付款会显示 Test 标识）、分期数、MercadoPago 扣取的金额和订单总额、已退款金额、退款记录，以及订单的 MercadoPago notes。
退款
在 MercadoPago payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via MercadoPago。请确认提示 Refund this amount through MercadoPago? This cannot be undone. 支持全额和部分退款。您需要具备编辑订单的权限。退款金额以 MercadoPago 扣取的金额为上限，因此在金额不一致的情况下，您最多只能退还顾客实际支付的金额，而不是订单总额。退款使用付款所在环境（测试或正式）的凭据发送，因此该环境的 Access Token 必须已设置。如果 MercadoPago 拒绝退款，区块会显示 MercadoPago refused the refund 及原因，且不会记录任何退款。已批准或处理中的退款会以退款 ID 添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不会更改状态。
模块不会生成退款单。PrestaShop 订单页面上的标准退款按钮不会通过 MercadoPago 退款。
在 MercadoPago 后台进行的退款、拒付和争议会通过通知到达，并添加到备注中。订单状态和退款单不会自动更改，如有需要请手动更新。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox MercadoPago Gateway 许可证区块是 Modules > Module Manager > VibeFox MercadoPago Gateway > Configure 页面的第一个区块，位于设置上方。请将密钥输入 License key，然后点击 Activate。之后，该区块会以遮蔽形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（再次检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方是 Product: presta-payment-mercadopago 一行，以及打开您 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 账户中释放该名额。
没有有效的密钥时，结账时不会向顾客显示 MercadoPago。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 标签页中会出现提醒。现有订单不受影响：已开始的付款仍会被确认，退款也可以正常进行。
许可证到期后，模块仍会继续工作，但更新和支持需要续费。在您使用后台时，系统会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 MercadoPago：请检查许可证是否有效，Enable / Disable 是否开启，以及当前模式是否具有前缀正确的两组凭据：测试模式使用 TEST- 密钥，正式模式使用 APP_USR- 密钥。检查购物车货币是否为您 MercadoPago 账户的货币。设置页面会指出缺少哪一项。在 Payment > Preferences 中，检查模块是否允许用于购物车货币、顾客所在国家和顾客组。
付款已完成，但订单仍停留在 Awaiting MercadoPago payment：通知没有到达。模块仅在您的商店拥有公网地址（不是 localhost，也不是 .local 或 .test 域名）时才会发送通知 URL。请将 Notification URL 中的 URL 添加到 your application > Webhooks，并选择事件 Payments。如果设置了 Webhook secret signature，请确认它是同一应用的密钥。MercadoPago 后台会显示您的商店对每条通知的响应。
通知返回 invalid signature：签名密钥属于其他应用，或通知没有有效的 x-signature。请重新复制密钥，或将该字段留空。
通知返回 no credentials for test 或 no credentials for live：付款所在环境的 Access Token 未设置。请输入该令牌；MercadoPago 会重试通知。
通知返回 not for this store：该付款不属于本商店的任何付款尝试。不会更改任何订单。
通知返回 order busy 或 payment could not be read：订单在同一时刻正被另一个请求更新，或无法连接 MercadoPago。MercadoPago 会自动重试通知。
凭据未能保存：错误 must start with 表示该值的前缀与字段不符。测试字段接受 TEST- 凭据，正式字段接受 APP_USR- 凭据。
顾客看到 This payment method is not configured correctly. Please choose another payment method or contact the store.：当前模式的凭据缺失、前缀错误，或被 MercadoPago 拒绝。请在设置页面检查。
顾客看到 MercadoPago cannot process payments in：购物车货币不是您 MercadoPago 账户的货币。MercadoPago 不进行货币转换。
安全银行卡表单无法加载：顾客会看到 The secure card form could not be loaded. Please reload the page or choose another payment method. 请检查当前模式的 Public Key。
顾客看到 Your payment was received, but the order could not be completed automatically：MercadoPago 已收款，但 PrestaShop 无法创建订单（例如当时模块已被禁用）。请查看模块页面的 Log 字段：错误始终会被记录。顾客会被要求不要重复付款；该购物车的下一次付款尝试或通知会在不再次扣款的情况下创建订单。
付款后订单变为 MercadoPago payment on hold：请阅读订单区块中的 MercadoPago notes（参见订单状态），然后完成订单或退款。
退款因模式相关的消息失败：付款是在测试或正式模式下完成的，而该模式的 Access Token 未设置。请输入后重试。
退款因 MercadoPago did not answer the refund request 失败：请先在 MercadoPago 后台检查该笔付款，然后再重试。
卸载
进入 Modules > Module Manager，打开 VibeFox MercadoPago Gateway 旁边的菜单，选择 Uninstall。此模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，网关设置、已保存的账户检查和日志将被删除。如果已关闭，所有设置都会保留，以便以后重新安装时使用。MercadoPago 付款记录和退款，以及订单状态 Awaiting MercadoPago payment 和 MercadoPago payment on hold 始终会保留，因此之前已付款的订单即使在重新安装后也可以退款。现有订单会保留其付款备注和交易 ID。
MercadoPago 是其各自所有者的商标。本模块与 MercadoPago 无关联，也未获得 MercadoPago 的认可。