VibeFox MercadoPago for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：8.0 或更高版本，已安装并启用。未安装 WooCommerce 时，插件无法启用。
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 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_mercadopago_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > MercadoPago > Manage，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 选择 Account country，填写测试和正式凭据；如需要，还可以在 MercadoPago 应用中设置通知（参见配置）。
6. 开启 Enable / Disable 并保存。使用 MercadoPago 测试卡进行测试（持卡人姓名 APRO = 已批准，CONT = 待处理，OTHE = 已拒绝），然后取消勾选 Test mode。
配置
所有设置都位于同一页面：WooCommerce > Settings > Payments > MercadoPago。在测试模式开启期间，字段上方会显示 Test mode is on: the TEST- credentials are used and no real money is charged.。当当前模式的凭据缺失、店铺货币不是您 MercadoPago 账户的货币（此时付款方式会在结账时隐藏），或凭据所属账户的国家与 Account country 不一致时，页面会发出警告。在付款方式列表中，在当前模式的凭据填写完成之前，MercadoPago 会被标记为需要设置。
保存时，前缀不符合预期（测试字段为 TEST-，正式字段为 APP_USR-）的凭据不会被保存：会显示错误，并保留原值。插件还会向 MercadoPago 查询 Access Token 所属的国家。如果无法验证令牌、账户不在受支持的国家，或国家与 Account country 不一致，都会显示错误。此时插件使用账户所在的国家。
常规
Enable / Disable：Enable MercadoPago card payments 用于开启或关闭该付款方式。默认：关闭。
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：Use the test credentials (no real charges)。测试模式下使用 TEST- 凭据，您使用 MercadoPago 测试卡付款；结账时会显示 TEST MODE 标识。取消勾选则使用正式凭据对真实银行卡扣款。默认：开启。若要使用 MercadoPago 测试用户账户（APP_USR- 凭据）进行测试，请将该账户的凭据填入正式字段，并关闭测试模式。
Test Public Key：以 TEST- 开头。在浏览器中用于对银行卡进行令牌化。
Test Access Token：以 TEST- 开头。仅在服务器端使用。请妥善保密。
Production Public Key：以 APP_USR- 开头。
Production Access Token：以 APP_USR- 开头。仅在服务器端使用。请妥善保密。
付款选项
Maximum installments：顾客可选择的最高分期数，范围为 1 至 24。1 = 仅一次性付款，且不显示分期字段。服务器端同样执行此限制。默认：1。
付款通知（Webhook）
银行卡付款通常会立即得到最终结果。MercadoPago 保留审核中（处理中或待处理）的付款，通过 MercadoPago 通知完成。当您的网站拥有公网地址时，插件会在每笔付款时发送通知 URL。您也可以在 your application > Webhooks 中添加该 URL，事件选择 Payments。该 URL 显示在设置的此部分，格式如下：https://your-site/wc-api/wc_mpg_webhook/?source_news=webhooks。
通知本身绝不会被直接信任。插件会使用付款所在环境的 Access Token，通过 MercadoPago API 重新读取付款，并按订单 ID 和订单密钥将其绑定到订单。若没有通知，审核中的订单会一直保持保留状态，直到您手动更新。
插件会处理以下 MercadoPago 付款状态：
Webhook secret signature：可选。your application > Webhooks 中显示的签名密钥。设置后，缺少有效 x-signature 的通知将被拒绝（HTTP 401）。
高级
Debug log：Log API requests and notifications 会记录到 WooCommerce > Status > Logs，来源为 wcp_mercadopago_gateway。日志不会记录 Access Token、银行卡令牌和付款人数据。默认：关闭。
Delete data on uninstall：Remove the gateway settings and logs when the plugin is deleted。订单上保存的 MercadoPago 付款 ID 属于付款记录，始终保留。默认：关闭。
结账
顾客选择付款方式（默认为 Credit or debit card (MercadoPago)），然后填写银行卡字段：Card number、Expiry (MM/YY)、Security code 和 Cardholder name。根据国家和银行卡的不同，顾客还需要选择 Document type 并输入 Document number，选择 Card issuer，以及 Installments 的期数。分期选项和利息由 MercadoPago 根据订单总额提供。
下单时，MercadoPago 会将银行卡转换为一次性令牌，您的店铺随即在服务器上为订单总额创建付款。账单邮箱和姓名、证件以及订单号会传递给 MercadoPago。CLP 和 COP 金额按整数扣款并四舍五入，因此请将这些货币在 WooCommerce 中的小数位数设置为 0。
付款获得批准后会立即标记为已付款，顾客会被引导至订单接收页面。审核中的付款会将订单置为保留，顾客同样会被引导至订单接收页面，订单随后由通知完成。被拒绝的银行卡会在结账时显示简短原因，例如 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.
该付款方式支持经典结账、结账区块和 Pay for order 页面，并兼容 WooCommerce 高性能订单存储（HPOS）。
本插件仅接受信用卡和借记卡。不支持 Checkout Pro 跳转、MercadoPago 钱包或账户余额，不支持现金（Rapipago、OXXO、boleto 等）、Pix、PSE 或 Yape，不支持保存银行卡或订阅，不支持单独授权和扣款，不支持 3-D Secure 验证，也不支持货币转换。
订单和退款
订单状态
Pending payment：订单已创建，但尚未收到任何付款结果，例如超时之后。
Processing：MercadoPago 已批准付款，且金额和币种一致。仅包含虚拟可下载商品的订单会变为已完成，这是 WooCommerce 的默认行为。订单备注会显示 MercadoPago 付款 ID 和分期数。交易 ID 即为 MercadoPago 付款 ID。
On hold：付款正在审核（处理中或待处理），等待 MercadoPago 通知。当批准的金额或币种与订单不符，或 MercadoPago 返回了意外状态时，订单也会被置为保留。订单备注会说明原因。
Failed：付款被拒绝或取消。订单备注会显示状态及其详情。顾客可以重新付款。
如果 MercadoPago 为已取消或已退款的订单批准了付款，订单状态不会改变，并会出现一条备注，提示您完成订单或退还该付款。如果已付款的订单又收到另一笔付款，备注会提示您在 MercadoPago 面板中退还多收的付款。
退款
打开订单，点击 Refund，输入金额，然后点击 Refund via Credit or debit card (MercadoPago)（按钮会显示您的 Title）。支持全额和部分退款。退款会使用付款所在环境（测试或正式）的凭据发送，因此该环境的 Access Token 必须已设置。如果 MercadoPago 拒绝退款，WooCommerce 会显示 MercadoPago refused the refund 及原因，且不会记录退款。获得批准或处理中的退款会以退款 ID 添加到订单备注中。
在 MercadoPago 面板中完成的退款和拒付会通过通知送达，并添加到订单备注中。它们不会自动记录为 WooCommerce 退款。
许可证密钥
本插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > MercadoPago 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期的截止日期以及您的域名。使用 Check now 可再次检查状态，Change key 用于输入其他密钥，Remove key 用于将密钥从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，MercadoPago 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one.。已登录的店铺管理员仍会看到该付款方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可正常使用。
许可证到期后，插件仍可继续运行，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
MercadoPago does not appear at checkout：请检查许可证是否有效，Enable / Disable 是否开启，当前模式是否具备两项带正确前缀的凭据：测试模式使用 TEST- 密钥，正式模式使用 APP_USR- 密钥。请确认店铺货币（或 Pay for order 页面上的订单货币）与您 MercadoPago 账户的货币一致。设置页面会指出缺少的项目。
The payment went through, but the order stays On hold or Pending payment：付款已完成，但订单仍处于保留或待付款状态：通知没有送达。只有当您的网站拥有公网地址（不是 localhost，也不是 .local 或 .test 域名）时，插件才会发送通知 URL。请将设置中的 URL 添加到 your application > Webhooks，事件选择 Payments。如果设置了 Webhook secret signature，请确认它来自同一个应用。MercadoPago 面板会显示您的店铺对每条通知的响应。
Notification answers invalid signature：签名密钥属于另一个应用，或通知中没有有效的 x-signature。请重新复制密钥，或将该字段留空。
Notification answers not for this store：该付款不属于本店铺中通过 MercadoPago 付款的订单。订单不会被修改。
A credential is not saved：错误 must start with 表示该值的前缀与字段不符。测试字段需要 TEST- 凭据，正式字段需要 APP_USR- 凭据。
The customer sees This payment method is not configured correctly. Please choose another payment method or contact the store.：当前模式的凭据缺失、前缀错误，或被 MercadoPago 拒绝。请在设置页面检查。
The customer sees MercadoPago cannot process payments in：订单货币不是您 MercadoPago 账户的货币。MercadoPago 不会转换货币。
The secure card form does not load：顾客会看到 The secure card form could not be loaded. Please reload the page or choose another payment method.。请检查当前模式的 Public Key。如需更多详情，请开启 Debug log，并查看 WooCommerce > Status > Logs 中来源为 wcp_mercadopago_gateway 的日志。
Refund fails with a message about the mode：该付款是在测试或正式模式下完成的，但该模式的 Access Token 未设置。请填写后重试。
Refund fails with MercadoPago did not answer the refund request：请先在 MercadoPago 面板中检查该付款，再重试。
The license block shows an error：请按照许可证区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活该密钥。如果无法连接许可证服务器，插件将沿用上次已知的状态继续运行。
卸载
停用插件会保留所有数据。如需删除，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被删除。网关设置、已保存的账户检查和日志仅在 Delete data on uninstall 开启时才会被删除；否则它们会保留，以便日后重新安装。现有订单会保留付款备注、MercadoPago 付款 ID 和交易 ID。
MercadoPago 是其各自所有者的商标。本插件与 MercadoPago 无关联，也未获得 MercadoPago 的认可。