Mercado Pago Terminal 支付网关
Mercado Pago Terminal 会将一笔销售发送到 Mercado Pago Point 终端。顾客在终端上付款,Mercado Pago 确认后,收银机会记录这笔付款。
本页从收银机上的操作讲起。店铺管理员可在设置 Mercado Pago Terminal中了解访问令牌、Webhook、终端以及如何检查设置是否成功。
Mercado Pago Terminal 需要 WCPOS Pro 2.0 或更高版本,以及 1.0 或更高版本的扩展。
1.0 版本尚未在真实的 Point 终端或 Mercado Pago 账户上运行过。 向顾客收取银行卡付款前,请先用自己的银行卡收取一笔小额付款并退款。 1.0 版本已使用根据 Mercado Pago 文档构建的模拟服务进行测试。0.1 版本曾在正式账户和真实的 Point Smart 上测试,能够列出终端、将其中一台切换为 PDV 模式,并创建和取消付款。两个版本都尚未测试以下情况:银行卡付款成功、付款被拒、在终端上取消付款、Mercado Pago 通知、退款以及 Mercado Pago 沙盒。已测试和未测试的内容
收取银行卡付款
启用 开启和关闭收银 后,收银机在收银台关闭时不会记录付款;已收取的银行卡款项则必须退款。设置说明请参阅收银台。
- 在购物车中按 结账,然后点按 付款方式 选项卡中的 Mercado Pago Terminal 磁贴。店铺可能为它设置了其他名称。
- 查看数字键盘上方。如果看到 选择终端,请点按柜台上的终端。如果看到 终端: 和一个名称,表示此收银机正在使用该终端;按 更改 可选择其他终端。收银机会记住你的选择。
- 如需用银行卡支付部分余额,请输入金额。剩余金额仍需通过另一笔付款结清。按 全部余额 可填入全部金额。
- 按 发送 … 到 Mercado Pago Terminal。收银机会显示 等待顾客在终端上操作。
- 顾客在终端上付款。收款完成且没有剩余应付金额时,会打开收据。如果仍有未付金额,请使用另一种付款磁贴收取。
收银机上各步骤的含义
付款过程中,收银机会依次点亮 已发送、终端处理中 和 已扣款。已扣款 表示款项已收取。Mercado Pago 会在一个步骤中直接收款,因此 已批准 不会亮起。
终端不会打印小票。请照常打印或通过电子邮件发送 POS 收据;请参阅结账时的收据。终端不支持小费。
取消付款
在收银机上按 在终端上取消。只有在付款显示于终端屏幕之前才能这样取消。顾客看到付款后,收银机就无法撤回:
- 如果顾客已经看到金额,请直接在 Mercado Pago 终端上取消付款,或请顾客不要付款。
- 等待收银机处理。收银机检查期间可能会停留在 正在取消 — 等待终端确认。终端取消之前,顾客仍可付款,因此此时不要改用其他方式收款。
- 终端取消后,收银机会显示 付款已取消。如果无人取消,Mercado Pago 会在 5 分钟后撤销付款,收银机则会显示 付款失败:终端等待超时。
如果收银机改为提供 释放此笔付款,在管理员检查 Mercado Pago 之前不要按它:请参阅“其他消息”中的收银机提供“释放此笔付款”。
出现问题时
顾客可能已经付款时
在以下情况下,银行卡可能已经扣款。管理员应先检查 Mercado Pago 账户,付款会以 订单 # 和订单编号列出。
银行卡已扣款,但订单尚未完成。 Mercado Pago 已收款,但收银机未能完成订单。请勿再次扣款。重新加载应用后,收银机会再次尝试完成销售;如果订单仍未完成,请由管理员完成。请参阅银行卡已扣款,订单尚未完成。
付款失败:终端确认的金额不一致。 终端收取的金额与收银机发送的金额不同,因此收银机没有记录这笔付款,但银行卡可能已扣款。请让管理员在 Mercado Pago 中找到这笔付款,并与订单核对。
付款期间收银机关闭或断开连接。 请勿在另一台收银机上重新发送付款。如果管理员已设置 Webhook,即使收银机已关闭,店铺也会记录付款。打开订单查看:如果仍显示未付款,请让管理员先检查 Mercado Pago,再决定是否收款。
其他消息
付款失败:银行卡被拒
按 重试 再次将付款发送到终端,或按 选择其他方式 使用另一种付款磁贴收款。
付款失败:后面附有代码
Mercado Pago 拒绝了付款并返回一个收银机无法翻译的原因,因此显示的是 Mercado Pago 自己的代码。按 重试,或按 选择其他方式。如果反复出现相同代码,请连同订单编号发送支持信息包。
终端仍在处理之前的订单
终端上还有另一笔待处理付款。请在终端上完成或取消该付款,然后按 重试。
付款失败:终端等待超时
5 分钟内无人付款。请检查终端,然后按 重试。
收银机提供“释放此笔付款”
Mercado Pago 已接受取消请求,但尚未确认。释放不代表已取消:只有管理员检查 Mercado Pago 账户并确认该订单没有已批准的付款后,才能按此按钮。之后即可改用其他方式支付订单。
Mercado Pago Terminal 磁贴呈灰色或未显示
磁贴下方会说明原因。所有原因请参阅无法使用付款磁贴时。
- 被订单 #… 占用 — 终端正忙于处理另一笔订单的付款。请完成或取消该笔付款,或者按 更改 并选择其他终端。
- 需要连接 — 收银机处于离线状态。终端付款需要经过店铺,请改用其他付款方式或等待网络恢复。
- 尚未为 Mercado Pago Terminal 设置终端 — 你的终端都不在 PDV 模式。请让管理员将终端切换为 PDV。
- 完全没有付款磁贴 — 网关未设置访问令牌,或尚未在 WCPOS 中启用。请让管理员检查设置。
退还 Mercado Pago 付款
退款会通过 Mercado Pago 退回顾客的银行卡,可以退还全部金额或部分金额。
- 在 POS 中打开订单的退款界面。请参阅退款。
- 选择 退还至 Mercado Pago Terminal,然后按 处理退款。
- 店铺会向 Mercado Pago 请求退款,并将结果添加到订单备注中。
在 WP Admin 中使用 WooCommerce 的 通过 Mercado Pago Terminal 退款 … 按钮办理退款,操作也相同。使用 0.1 版本收取的款项也可按相同方式退款。
退款仍处于待处理状态
Mercado Pago 回复时尚未完成退款,店铺也可能不会自动更新状态。再次退款前,请先在 Mercado Pago 账户中查找这笔退款:如果退款已成功,顾客已经收到款项。
Mercado Pago 拒绝退款
某些银行卡收单机构只允许在终端上退款。请在 Point 终端或 Mercado Pago 账户中退款,然后在 WooCommerce 中使用 手动退款 … 记录退款。
我已在终端或 Mercado Pago 中退款
店铺不会收到在这些地方办理的退款通知,因此订单仍显示全额付款。请在 WooCommerce 中使用 手动退款 … 记录退款,避免重复退款。
设置 Mercado Pago Terminal
管理员只需在 WP Admin 中为每个店铺设置一次,然后在每台收银机上选择终端。店铺通过互联网经由 Mercado Pago 连接各终端,因此无需配对,任何收银机都可以使用你的任意一台终端。
所需条件
如果你的币种没有分,例如智利比索,请在 WooCommerce > 设置 > General 下将 小数位数 设为 0。Mercado Pago 会拒绝这些账户中带小数的金额。
安装扩展
打开 WP Admin > POS > 设置 > 扩展,找到 Mercado Pago Terminal for WooCommerce,安装并启用。需要 1.0 或更高版本;0.1 版本适用于 WCPOS 2.0 之前的版本。请参阅扩展。
你也可以从 GitHub 发布页面下载插件 zip 文件(不是源代码 zip 文件),然后在 插件 > Add Plugin > 上传插件 中上传。
如果没有 WCPOS Pro 2.0,WP Admin 会显示 Mercado Pago Terminal requires WooCommerce POS Pro 2.0 or newer.,并且不会添加此网关。
输入访问令牌
使用卖家账户登录 Mercado Pago Developers,然后打开 你的集成。如果尚无应用,请先创建一个,然后打开该应用。在 正式环境凭据 下复制 访问令牌:令牌以 APP_USR- 开头。这是用于真实付款的令牌。测试凭据 下的令牌只能访问 Mercado Pago 沙盒,本扩展尚未使用沙盒进行测试。
然后转到 WP Admin > WooCommerce > 设置 > 支付,打开 Mercado Pago Terminal。

点击 保存更改。
添加 Webhook
Webhook 让 Mercado Pago 能在付款结束时立即通知店铺。即使没有 Webhook,付款仍可正常处理,因为收银机和店铺会持续向 Mercado Pago 查询;但请设置 Webhook,以便即使收银机关闭,已付款的订单也能完成。
- 从 Webhook 密钥 下方的描述中复制 Webhook URL。其末尾为
wp-json/wcpos/v2/payments/webhook?provider=mercadopago。 - 在 Mercado Pago Developers 中打开 你的集成、你的应用,然后打开 Webhook。添加 URL 并选择 订单(Mercado Pago) 事件。
- 复制 Mercado Pago 显示的 签名密钥,粘贴到 Webhook 密钥 中,然后点击 保存更改。
店铺会拒绝所有未使用此密钥签名的通知,因此未设置密钥的 Webhook 不会起作用。
将终端切换为 PDV 模式
Point 终端出厂时处于 STANDALONE 模式,无法接收收银机发起的付款。只有处于 PDV 模式的终端才会在结账时提供。
- 如果尚未登录,请在每台终端上使用同一个 Mercado Pago 账户登录。
- 重新加载 Mercado Pago Terminal 设置页面。Mercado Pago 诊断信息 下方的表格会列出每台终端的 ID、终端名称和 模式。
- 对每台处于 STANDALONE 模式的终端点击 切换为 PDV,然后重启该终端。Mercado Pago 要求重启。
此表格最多列出 50 台终端。
在 WCPOS 中启用
转到 WP Admin > POS > 设置 > 结账,在 网关 表格中找到 Mercado Pago Terminal,然后打开 已启用。该页面会自动保存更改,无需点击保存按钮。

- Mercado Pago Terminal — 此扩展在 网关 表格中的一行。
- 已启用 — 网关 ID 旁边的开关;请将其打开。收银机重新加载后会显示 Mercado Pago Terminal 磁贴。
保持 WooCommerce 设置页面上的 启用 处于关闭状态。只要在此处打开 已启用,POS 就会使用此网关,无论 WooCommerce 中是否勾选该选项。请参阅收银台设置。
为每台收银机选择终端
在每台收银机上打开 设置 > 刷卡器。你的终端会按 Mercado Pago 提供的名称列在 智能刷卡器 下。标记为 离线 的终端尚未切换模式:请参阅将终端切换为 PDV 模式。在柜台对应的终端上按 使用此刷卡器;该行会显示 已选择。收银员仍可在结账时按 更改。
如果只有一台终端处于 PDV 模式,则无需选择:所有收银机上都已自动显示为 已选择。请参阅选择智能刷卡器。
检查设置是否成功
-
在 Mercado Pago Terminal 设置页面中,Mercado Pago 诊断信息 下方会显示一条消息:
凭据已接受。切换到 PDV 后,请重启终端。
这表示 Mercado Pago 已接受访问令牌。如果显示 Mercado Pago access token is missing.,则尚未保存令牌;其他文本则是 Mercado Pago 对令牌的回复。
-
你要使用的每台终端,其 模式 下方都应显示 PDV。
-
在收银机上重新加载 POS 并按 结账。Mercado Pago Terminal 磁贴会出现在付款方式中,数字键盘上方会列出你的终端。
-
用自己的银行卡完成一笔小额销售,然后退款。
从 0.1 版本升级
- 先将 WCPOS、WCPOS Pro 和应用更新到 2.0,然后再更新扩展。
- 添加新的 Webhook 及其密钥:请参阅添加 Webhook。0.1 版本的 Webhook 地址已失效,未签名的通知会被拒绝。
- 升级过程中正在处理的付款会继续保留,不会重复扣款。
- 以下 0.1 设置已移除:默认终端、已启用终端、锁定终端选择、结账调试日志 和 日志级别。现在可在每台收银机的 设置 > 刷卡器 中选择终端。
- 模式 不再决定使用哪个环境:请确认已保存的访问令牌符合你的用途。
- 现在通过 付款方式 选项卡处理付款。旧版 选项卡仍可使用,但只能支付全部余额。
- 使用 0.1 版本收取的款项仍可照常退款:请参阅退还 Mercado Pago 付款。
设置参考
位于 WP Admin > WooCommerce > 设置 > 支付 > Mercado Pago Terminal:
| 设置 | 作用 |
|---|---|
| 启用 | 在网店的结账页面提供此网关。请保持关闭;POS 有自己的开关,位于 POS > 设置 > 结账 |
| 标题 | 收银机上付款磁贴的名称。默认为 Mercado Pago Terminal |
| 描述 | 默认为 Pay in person on a Mercado Pago Point terminal. |
| 模式 | 测试(默认)或 正式。请设为 正式,以匹配正式环境令牌。此项仅为标签:无论字段自身的描述如何,付款是否真实由访问令牌决定 |
| 访问令牌 | Mercado Pago Developers → 你的集成 → 你的应用 → 正式环境凭据。保存后不会再完整显示,只显示末尾字符;留空即可保留现有令牌。更换前请先处理完所有未完成的付款 |
| Webhook 密钥 | 来自 Mercado Pago 应用 Webhook 的签名密钥。其描述会显示店铺的 Webhook URL。保存和显示方式与令牌相同 |
日志和支持信息包
设置页面底部有支持信息包、诊断信息行和日志链接。

- 诊断信息行 — 此店铺尚未设置,因此显示 Mercado Pago access token is missing.。你的页面应显示 Credentials accepted.,下方列出你的终端。
- 查看日志 — 打开
WooCommerce > Status > 日志,来源为mercadopago-terminal。 - 下载支持信息包 — 用于联系 WCPOS 支持的文件。
日志会记录向 Mercado Pago 发出的每个请求及其回复,并移除令牌和银行卡号。
付款出错时,点击 下载支持信息包,并将文件连同订单编号发送给 WCPOS 支持。此按钮由 WCPOS Pro 添加;信息包涵盖网站上的所有 POS 付款提供方,并移除密钥和银行卡号。信息包还会注明店铺最后一次收到带签名 Webhook 的时间。
不支持的功能
- 小费,或先授权、稍后扣款。
- 在终端上打印小票。
- 在处于 STANDALONE 模式的终端上收款。
- 记录在终端或 Mercado Pago 中办理的退款。
- 转换币种:店铺和 Mercado Pago 账户必须使用相同币种。
- 每个账户超过 50 台终端。
- 在 WP Admin 中设置全店默认终端,或限制收银机可使用的终端。每台收银机自行选择终端。
- HPOS(WooCommerce 的订单表):此扩展尚未声明支持。
开发者参考:工作原理
此网关通过 WCPOS Pro 的付款提供方使用 Mercado Pago 面向 Point 的 订单 API(POST /v1/orders,参数为 type: point)。每笔付款都会按收银机上的金额创建 Mercado Pago 订单,并附上终端 ID、print_on_terminal: no_ticket、付款的外部引用和幂等键,以确保重试不会重复扣款。订单会在 5 分钟后过期(过滤器 mptfwc_order_expiration_time)。
收银机每 2 秒查询一次状态。Webhook wp-json/wcpos/v2/payments/webhook?provider=mercadopago 必须携带有效的 x-signature(使用 Webhook 密钥进行 HMAC-SHA256 签名);系统不会信任其正文,而是再次从 Mercado Pago 获取订单。WooCommerce POS 会每 10 分钟检查一次尚未收到回复的付款,作为后备检查。
终端列表来自 /terminals/v1/list;只有处于 PDV 模式的终端才视为在线。0.1 版本中的过滤器 mptfwc_order_payload 和 mptfwc_poll_interval_ms 已移除。
相关文档
- 刷卡器
- 旧版选项卡
- 退款
- 收银台设置
- 在 GitHub 上报告问题。有关账户、凭据和终端的问题,请联系 Mercado Pago。