VibeFox MercadoPago for OpenCart — 帮助
要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
商店货币：您 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 购买。一个密钥仅适用于一个域名。
安装
下载文件是一个压缩包，包含两个 OpenCart 版本的安装包。请先在您的电脑上解压。压缩包中有 README.txt、OpenCart 3 安装包 wcp_mercadopago_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_mercadopago_gateway.ocmod.zip。只安装适用于您 OpenCart 版本的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 wcp_mercadopago_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，直接把此安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox MercadoPago Gateway，点击 Install（绿色 + 按钮）。您的管理员用户需要有修改支付扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块的 License key 中，然后点击 Activate（见许可证密钥）。
4. 选择 Account country，输入测试和生产凭据；如需要，在您的 MercadoPago 应用中设置通知（见配置）。请在 System > Localisation > Currencies 中确认账户货币已启用。
5. 开启 Enable / Disable 并点击 Save。使用 MercadoPago 测试卡在测试模式下试付，然后关闭 Test mode。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 wcp_mercadopago_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox MercadoPago Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 3 至 5 步输入许可证密钥、凭据和通知设置。两个版本的设置页面及其字段相同。只有通知 URL 不同（参见付款通知（Webhooks））。
新安装默认关闭支付方式，并开启测试模式。
配置
所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox MercadoPago Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当测试模式开启时，页面会显示 Test mode is on: the TEST- credentials are used and no real money is charged.。如果当前模式的 Public Key 或 Access Token 缺失，页面会提示（此时结账时将隐藏该支付方式）；如果商店默认货币与您 MercadoPago 账户的货币不一致，页面也会提示（此时该支付方式仅向以账户货币付款的顾客显示，若商店没有启用该货币则隐藏）；如果凭据所属账户的国家与 Account country 不同，同样会提示。若您没有修改扩展的权限，页面只能显示设置，无法保存。
如果保存时 Title 为空（或超过 128 个字符），则不会保存任何内容，页面会显示 Enter a title for the payment method (1 to 128 characters).。其他错误的值不会保存，并保留原值，同时显示一条错误信息，指出字段名称，并以 — the previous value was kept. 结尾。这适用于：不以预期前缀开头的凭据（测试字段为 TEST-，生产字段为 APP_USR-）；超出 1–24 范围的 Maximum installments；不是整数的 Sort Order（Sort Order must be a whole number）；不是大于或等于 0 的数字的 Total；以及不存在的地理区域或订单状态。保存后，扩展会向 MercadoPago 查询每个访问令牌所属的国家。如果无法验证当前模式的令牌，如果账户不在受支持的国家，或者国家与 Account country 不一致，则会显示警告。此时扩展会使用账户所在的国家。
MercadoPago
Enable / Disable：Enable MercadoPago card payments 用于开启或关闭该支付方式。只有当活动模式的凭据已填写，并且顾客以 MercadoPago 账户货币付款时，结账页面才会显示此支付方式。默认：关闭。
Title：结账时顾客看到的支付方式名称。它也会作为支付方式名称保存在订单中。默认：Credit or debit card (MercadoPago)。必填，最多 128 个字符。
Description：在 Confirm Order 步骤中显示在卡片字段上方的文字。默认：Pay securely with your credit or debit card. Card data is sent directly to MercadoPago.
Sort Order：MercadoPago 在结账时的支付方式排列位置。留空或输入整数。
Geo Zone：仅向所选地理区域内的付款地址提供 MercadoPago。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。
Total：订单必须达到的结账金额（以商店默认货币计）才会提供 MercadoPago。留空则对任何金额都提供 MercadoPago。
MercadoPago 账户
在 MercadoPago 开发者面板中获取应用凭据：Your integrations > your application > Credentials（页面中有直达链接）。测试凭据以 TEST- 开头，生产凭据以 APP_USR- 开头。
Account country：您 MercadoPago 账户所在的国家。它决定收费货币、卡片字段的语言，以及是否要求持卡人证件。顾客必须以相同货币付款，例如阿根廷使用 ARS。保存凭据时，会与账户核对国家。默认：Argentina (ARS)。
Test mode：在测试模式下使用 TEST- 凭据，您使用 MercadoPago 测试卡付款；结账时会显示 TEST MODE 标记，以及 Use MercadoPago test cards. No real charges.。关闭该选项后，将使用生产凭据向真实银行卡收费。退款和通知始终使用付款所在模式的凭据。默认：开启。
Test Public Key：以 TEST- 开头。在浏览器中用于卡片令牌化。
Test Access Token：以 TEST- 开头。仅在服务器上使用。请妥善保密。
Production Public Key：以 APP_USR- 开头。
Production Access Token：以 APP_USR- 开头。仅在服务器上使用。请妥善保密。
已保存的访问令牌和 Webhook 密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it.。只有在需要更改时才输入新值。要删除已保存的值，请勾选字段下方的 Clear the saved value on save，然后点击 Save。
支付选项
Maximum installments：顾客可以选择的最大分期数（cuotas 或 parcelas），范围为 1 到 24。1 = 仅一次性付款。服务器端也会执行此限制。默认：1。
付款通知（Webhooks）
银行卡付款通常会立即得到最终结果。MercadoPago 处于审核中（处理中或待定）的付款，会通过 MercadoPago 通知完成。当您的商店具有公共地址（不是 localhost，也不是 .local 或 .test 域名）时，扩展会在每笔付款中发送通知 URL。您也可以在 your application > Webhooks 中、针对 Payments 事件添加该 URL。该 URL 显示在本部分的 Notification URL 中。在 OpenCart 3 中它形如 https://your-store/index.php?route=extension/payment/wcp_mercadopago_gateway/webhook&source_news=webhooks；在 OpenCart 4 中形如 https://your-store/index.php?route=extension/wcp_mercadopago_gateway/payment/wcp_mercadopago_gateway.webhook&source_news=webhooks，由您 OpenCart 安装的前台地址构成。请完全按照设置中显示的内容复制该 URL。
通知本身绝不会被直接信任。扩展会使用付款所在环境的访问令牌，从 MercadoPago API 重新读取该付款，并将其与您商店的一次付款尝试绑定。若没有通知，审核中的订单会保持在 Awaiting MercadoPago Status，直到您手动更新。
扩展会处理以下 MercadoPago 付款状态：
Webhook secret signature：可选。在 your application > Webhooks 中显示的密钥签名。设置后，没有有效 x-signature 的通知会被拒绝（HTTP 401）。
订单
OpenCart 在 Confirm Order 步骤创建订单，此时没有状态（缺失订单）。只有在 MercadoPago 作出响应后，订单才会获得状态。被拒绝的银行卡会让订单保持无状态（备注会说明原因），顾客则停留在 Confirm Order 步骤。下面的每个字段都会列出您的 OpenCart 订单状态。
Order Status After Payment：MercadoPago 已批准付款，且金额和货币与订单相符。默认：处理中。
Awaiting MercadoPago Status：付款正在 MercadoPago 审核中（处理中或待定）；通知将完成订单。默认：待付款。
On Hold (Review) Status：MercadoPago 批准的金额或货币与订单不同，或返回了意外状态。备注会说明需要在 MercadoPago 面板中检查什么。默认：待付款，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，以区分等待中和待审核的订单。
Payment Failed Status：处于审核中的付款被 MercadoPago 拒绝或取消。默认：失败。
Cancelled Status：处于此状态（或已退款状态）的订单已关闭：MercadoPago 迟到的批准只会添加一条备注。默认：已取消。
Refunded Status：在订单页面中全额退款时，付款会变为此状态。部分退款只会添加备注。默认：已退款。
高级
Debug log：将 MercadoPago 请求和通知写入 OpenCart 日志文件夹（storage/logs）中的 wc_mpg_debug.log.php。该文件无法通过网页打开。即使此设置关闭，错误也始终会记录。访问令牌、卡片令牌和付款人数据不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启后，卸载扩展会删除网关设置和日志。MercadoPago 付款记录和退款始终保留，因此之前付款的订单在重新安装后仍可退款。默认：关闭。
导入 / 导出
Export：Download JSON 将设置保存为 JSON 文件。访问令牌和 Webhook 密钥不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的密钥会被保留。
结账
在 Payment Method 步骤中，顾客选择支付方式（默认为 Credit or debit card (MercadoPago)）。OpenCart 在 Confirm Order 步骤创建订单，此时仍没有状态。顾客在这里会看到您的描述，并填写卡片字段：Card number、Expiry (MM/YY)、Security code 和 Cardholder name。根据国家和卡片的不同，顾客还需选择 Document type 并输入 Document number，选择 Card issuer 以及 Installments 的期数。分期选项和利息由 MercadoPago 针对订单总额提供。
在 OpenCart 4 中，顾客在付款方式区块中点击 Choose 按钮选择付款方式（位于 Payment method options 窗口中）。卡片字段此时会出现在结账页面底部的订单确认区块中，位于 Confirm Order 按钮上方。
顾客点击 Confirm Order 后，MercadoPago 会将银行卡转换为一次性令牌，您的商店则在服务器端按订单货币和订单总额创建付款。顾客的电子邮件、姓名和证件会传给 MercadoPago；付款在 MercadoPago 中显示为 Order #、订单号以及您的商店名称。CLP 和 COP 金额按无小数位收取。
付款获批后，订单状态将以 OpenCart 标准方式设置，并发送常规订单邮件、更新库存；购物车会被清空，顾客会看到 OpenCart 的订单成功页面。审核中的付款会设置 Awaiting MercadoPago Status，页面还会显示 MercadoPago is reviewing your payment. Your order will be updated automatically as soon as MercadoPago confirms it.。处于审核状态的订单会显示 Your payment is being reviewed. We will update your order as soon as the review is complete.
被拒绝的银行卡会让订单保持无状态。顾客仍停留在 Confirm Order 步骤，并看到简短原因，例如 Your card has insufficient funds. Please use another card or payment method. 或 Please check the security code of your card. 顾客可以修改信息，或使用其他卡片；每次尝试都会生成新的卡片令牌。如果缺少卡片信息，则显示 Please fill in all card fields.
如果 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. OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单，OpenCart 4 则会保留并更新结账订单，顾客在被拒绝的卡片之后会支付同一订单。无论哪种情况，已付款或等待中的订单所对应的购物车绝不会再次扣款；顾客会被引导至成功页面。
在 OpenCart 4 中，订单会保留在结账流程中，直到显示成功页面。如果该订单在未付款的情况下已被关闭（例如您取消了订单），则不会扣款，顾客会看到 Your previous order was cancelled without a payment. Please reload the checkout page and confirm the order again — the payment will be made with a new order. 如果订单已经生成，且购物车此后已变化，提示为 Your previous order has already been placed. Your cart has changed since — please reload the checkout page and confirm the order again to pay for the current cart with a new order. 购物车发生变化（包括数量变化）时，视为需要单独付款的新购物车。
商店处于维护模式时，通知 URL 仍然有效：OpenCart 3 允许支付扩展的请求通过，而在 OpenCart 4 中，扩展会为其添加一个启动动作。
该扩展仅接受信用卡和借记卡。它不支持 Checkout Pro 跳转、MercadoPago 钱包或账户余额、现金支付（Rapipago、OXXO、boleto 等）、Pix、PSE 或 Yape、保存的卡片或订阅、单独的授权与捕获、3-D Secure 验证以及货币转换。
订单与退款
订单状态
No status (missing order)：银行卡被拒绝，或 MercadoPago 尚未响应。在 Sales > Orders 中，只有将 Order Status 筛选设为 Missing Orders 时才会显示此类订单。
Order Status After Payment（默认 处理中）：MercadoPago 已批准付款，且金额和货币与订单相符。备注会显示付款 ID、环境和分期数。
Awaiting MercadoPago Status（默认 待付款）：付款正在审核中（处理中或待定），等待 MercadoPago 通知。当 MercadoPago 批准后，订单会转为 Order Status After Payment。
On Hold (Review) Status（默认 待付款）：批准的金额或货币与订单不同，或 MercadoPago 返回了意外状态。备注会说明原因。请检查订单，然后履行订单或退还付款。
Payment Failed Status（默认 失败）：处于审核中的付款被拒绝或取消。备注会显示状态及其详情。
Refunded Status（默认 已退款）：付款已通过扩展全额退款。
如果 MercadoPago 为已取消或已退款的订单批准了付款，订单状态不会改变，并会出现备注，提醒您完成订单或退还付款。如果同一订单或已付款的购物车又收到另一笔付款，备注会提醒您在 MercadoPago 面板中退还多余的付款。
备注是订单 History 中的条目，顾客无法看到。
VibeFox MercadoPago Gateway 选项卡
在 Sales > Orders 中打开一笔通过 MercadoPago 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox MercadoPago Gateway 选项卡会显示 Payment ID、付款的 Status、Environment（测试付款会带有 Test 标签）、Installments、Charged / order 金额、Refunded 金额、退款表单、退款记录以及订单的 MercadoPago notes。有权访问该扩展的用户会看到此选项卡。
退款
在 VibeFox MercadoPago Gateway 选项卡中输入 Amount（尚未退款的金额会自动填入），可选填写 Reason (optional)，然后点击 Refund via MercadoPago。确认提示 Refund this amount through MercadoPago? This cannot be undone.。支持全额和部分退款。您需要拥有修改扩展的权限（在 System > Users > User Groups 中设置）。退款金额受 MercadoPago 实际收取金额的限制，因此如果金额出现偏差，您最多只能退还顾客实际支付的金额，而不是订单总额。退款使用付款所在环境（测试或生产）的凭据发送，因此该环境的访问令牌必须已设置。如果 MercadoPago 拒绝退款，选项卡会显示 MercadoPago refused the refund 及原因，并且不会记录退款。已批准或处理中的退款会连同退款 ID 一起添加到退款记录和备注中。全额退款会将订单设为 Refunded Status，但不会通知顾客，也不会将商品退回库存，与手动修改状态相同。部分退款不会改变状态。
Sales > Returns 中的商品退货不会通过 MercadoPago 退还款项。
在 MercadoPago 面板中进行的退款、拒付和争议处理会通过通知传回，并添加到备注中。订单状态不会自动改变，如有需要请手动更新。
许可证密钥
该扩展需要使用 vibefox.net 提供的 VibeFox 许可证密钥。许可证区块 License — VibeFox MercadoPago Gateway 是 Extensions > Extensions > Payments > VibeFox MercadoPago Gateway > Edit 页面中设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期的截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。下方是 Product: opencart-payment-mercadopago 这一行，以及 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 账户中释放名额。
没有有效密钥时，顾客在结账时看不到 MercadoPago。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one.。在同一浏览器中登录后台的管理员仍会在商店中看到该支付方式，并标记为 (unlicensed — visible to admins only)，这样您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中没有此预览：商店看不到管理员登录状态，因此没有有效密钥时，付款方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，退款也照常运行。
许可证到期后，扩展仍会继续工作，但更新和支持需要续费。打开后台 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时总会删除许可证密钥和许可证状态。
故障排除
结账时不显示 MercadoPago：请检查许可证是否有效、Enable / Disable 是否开启，以及当前模式是否同时具有正确前缀的两项凭据：测试模式下为 TEST- 密钥，生产模式下为 APP_USR- 密钥。请检查顾客是否以您 MercadoPago 账户的货币付款（该货币必须在商店中启用）、付款地址是否在所选的 Geo Zone 内，以及订单是否达到设置中的 Total。设置页面会指出缺少的项目。
付款已完成，但订单仍停留在 Awaiting MercadoPago Status：通知没有到达。扩展只有在商店具有公共地址（不是 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：付款所在环境的访问令牌未设置。请输入该令牌；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 session has expired. Please reload the page and try again.」：卡片表单已不再属于顾客的结账会话。顾客需要重新加载结账页面。
顾客看到「Your payment was received, but the order could not be completed automatically」：MercadoPago 已收款，但 OpenCart 无法设置订单状态。请查看扩展页面上的 Log 字段：错误始终会被记录。系统会请顾客不要再次付款；购物车的下一次付款尝试或通知会在不重复收费的情况下设置状态。
付款后订单处于审核状态：请阅读订单选项卡中的 MercadoPago notes（参见订单状态），然后履行订单或退还付款。
退款因模式相关的消息失败：付款是在测试或生产模式下完成的，而该模式的访问令牌未设置。请输入该令牌后重试。
退款因 MercadoPago did not answer the refund request 失败：重试前请先在 MercadoPago 面板中检查该付款。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox MercadoPago Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被移除。OpenCart 总会移除扩展自身的设置：Enable / Disable、Sort Order、Geo Zone、Total 以及 Orders 部分的订单状态；重新安装后它们会恢复为默认值。扩展的 OpenCart 事件也会被移除（在 OpenCart 4 中还包括其启动动作，该动作在维护模式下允许通知和顾客的返回请求通过）。如果开启了 Delete data on uninstall，其余网关设置（标题、描述、账户国家、测试模式、凭据、分期、Webhook 密钥、日志记录）、已保存的账户验证信息和日志都会被删除；如果关闭，则会保留，以便之后重新安装时使用。MercadoPago 付款记录和退款始终保留，因此之前付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。
在 OpenCart 4 中，如需同时删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox MercadoPago Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
MercadoPago 是其各自所有者的商标。本扩展与 MercadoPago 无关联，也未获得 MercadoPago 的认可或背书。