跳到主内容
版本: 2.x

PayPal Reader(Zettle)网关

收银设备将订单总额发送到 PayPal Reader,客户在读卡器上感应或插入银行卡,读卡器报告付款完成后,销售会自动完成。本页分为两部分:在收银设备上收款,以及在 WP Admin 中进行设置。

Pro 功能

无论是从扩展目录安装 PayPal Reader 扩展,还是在收银设备上使用它,都需要 WCPOS Pro。

收款​

开始之前
  • 收银设备和店铺均已联网。付款在 POS 内的店铺自身支付页面上进行。
  • 具有 WP Admin 访问权限的人员已设置网关并配对读卡器。
  • 如果店铺使用 开启和关闭收银机,请确保收银机已开启。收银机关闭时,收银设备不会记录付款。参阅收银机。
  1. 将商品加入购物车,然后点击 结账。

  2. 打开 传统支付 选项卡。店铺的支付页面会在 POS 内打开。参阅传统支付选项卡。

  3. 选择 PayPal Reader。店铺可能为它设置了其他名称。面板先显示 正在加载读卡器…,随后显示 模式:测试。已准备好开始付款。 (店铺上线后则显示 模式:正式。)。

  4. 选择读卡器。每台已配对的读卡器都有一个标有其名称的按钮,例如 前台(就绪),默认选中第一台。要改用其他读卡器,请点击对应按钮。

    警告

    面板顶部的 测试模式 只是一个标签。读卡器仍可能扣取真实款项。参阅测试模式与上线。

  5. 点击 开始读卡器付款。面板先显示 正在连接读卡器…,随后显示 读卡器已就绪。正在请求付款…,订单的全部金额会发送到该读卡器。

  6. 客户在读卡器上感应或插入银行卡。读卡器处理付款时,面板显示 正在付款…,括号内显示读卡器当前执行的步骤。

  7. 读卡器报告付款完成后,面板显示 付款完成。正在提交订单…,POS 随即进入收据页面。

无需点击传统支付选项卡底部的 处理付款,销售会自动完成。如果在读卡器完成付款前点击该按钮,POS 会提示 请先完成 PayPal Reader 付款,再提交订单。

按钮下方的深色框会逐行记录每个步骤及其时间。如果付款中途停止,请查看此处。

读卡器始终收取整个订单的款项,因此无法与其他方式共同支付一笔销售。订单一旦收到付款,传统支付 选项卡就会显示 仅限整单付款,且无法使用;请先取消该笔付款。

停止付款​

付款过程中点击 取消付款。这会请求读卡器取消付款,并让收银设备停止接收读卡器的消息,面板显示 付款已取消。

再次收款前请检查读卡器

点击 取消付款 后,或在读卡器处理付款时关闭或重新加载支付页面后,收银设备将不再接收读卡器的消息。如果读卡器仍显示付款已获批准,说明客户已经付款,请勿再次扣款。请使用 支付 选项卡中的 银行卡 卡片记录该笔付款,并在 Zettle 账户中核对。

确认客户未被扣款后,点击 开始读卡器付款 重试,或关闭选项卡并使用其他方式收款。

销售完成后​

订单会标记为已付款,其 交易 ID 为 Zettle 中该笔银行卡付款的 ID,便于在 Zettle 账户中找到同一笔付款。订单备注会记录付款开始的时间和使用的读卡器(以关联 ID 标识),以及付款完成、因金额不符被拒绝或通过 取消付款 取消的时间。

退款​

此扩展无法通过 Zettle 退款,因此无法使用 退款至 PayPal Reader。

警告

请勿向客户退还现金。银行卡退款需要在 Zettle 中操作,通过现金退款 仅在 WCPOS 中记录退款。如果收银机已开启,此操作还会将钱箱的预期现金余额减去相同金额。参阅现金退款与钱箱。

  1. 在 Zettle 账户中将款项退回银行卡。
  2. 使用 通过现金退款 在订单中记录退款。参阅退款去向。

出现问题时​

尚未配对任何读卡器。请让店铺管理员配对一台… Zettle 账户尚未配对读卡器,因此 开始读卡器付款 按钮会保持灰色。需要具有 WP Admin 访问权限的人员配对读卡器,参阅进行设置中的 配对读卡器。

面板一直显示正在连接读卡器… 读卡器尚未准备好收款,可能处于休眠、关机、离线状态,或正在处理其他操作。请唤醒读卡器,确保其显示主屏幕且已联网。点击 取消付款,按停止付款中的说明确认读卡器未收取款项,然后再次点击 开始读卡器付款。

付款已取消。 付款已在读卡器上取消,或通过 取消付款 取消。如果点击了 取消付款,请先按停止付款中的说明检查读卡器,然后重新开始付款,或改用其他方式。

付款失败。银行卡是否已扣款?​

付款失败。 后面的提示可帮助判断客户是否已付款,以及能否再次收款。找到对应提示后,按相应情况处理:

付款金额不符:已扣款,请先退款​

银行卡是否已扣款:是。 面板显示 付款失败。付款金额不符。 读卡器已收取款项,但付款开始后订单总额发生了变化,因此订单被拒绝,仍为未付款状态。请在 Zettle 账户中退还该笔款项,然后按正确的总额发起新付款。为避免此情况,请勿在读卡器处理付款时修改购物车;应先点击 取消付款,再修改购物车,然后发起新付款。

括号内显示原因:未扣款,请重试​

银行卡是否已扣款:否。 面板显示 付款失败。 并在括号内注明原因。读卡器或 Zettle 未收取款项,例如银行卡交易被拒绝。请点击 开始读卡器付款,或改用其他方式收款。

仅显示付款失败,或显示未列出的提示:重试前先核实​

银行卡是否已扣款:无法确定。 面板仅显示 付款失败。 收银设备与 Zettle 的连接已断开,无法确定银行卡是否已扣款。如果显示本页未列出的提示,也请按此方式处理。检查读卡器和 Zettle 账户中的付款列表。如果存在该笔付款,请按停止付款中的说明记录。只有确认未收取款项后才能重新开始;如果无法确定,请先咨询 Zettle 账户的管理人员,再决定是否再次收款。

请求失败或此处列出的其他提示:已扣款,请记录付款​

此情况仅适用于 付款失败。 后出现以下提示:请求失败。 、服务器响应无效。 、请求无效。 和 订单访问无效。 对于其他提示,请按仅显示付款失败中的说明处理。

银行卡是否已扣款:是。 只有在读卡器报告付款完成后,面板才会显示这些提示:读卡器已收取款项,但店铺未能记录,因此订单仍为未付款状态。请在 Zettle 账户中找到该笔付款,并按停止付款中的说明记录。如果 Zettle 账户中没有该笔付款,请按仅显示付款失败中的说明处理,在确认前不要再次收款。

其他提示​

尚未配置 Zettle 凭据。 Zettle 客户端 ID 或 Zettle 断言 为空。请让网关设置人员填写,参阅进行设置中的 填写网关设置。

以 Zettle OAuth 交换返回 HTTP … 开头的提示 表示 Zettle 拒绝了凭据。请让网关设置人员检查 Zettle 客户端 ID 和 Zettle 断言。

面板显示按钮,但始终未显示正在加载读卡器… 支付页面的脚本未能加载。参阅网关支付页面显示异常。

设置过程中出现的提示

配对读卡器前,请先保存上方的 Zettle 客户端 ID 和断言。 已配对的读卡器 部分需要两项凭据均已填写。请输入并保存。

请先输入配对码。 配对码 输入框为空。请查看读卡器上的配对码并输入。

无法加载已配对的读卡器: 后面会显示 Zettle 的回复。设置页面无法连接 Zettle,或 Zettle 拒绝了凭据。请检查凭据并重新保存。

配对读卡器时显示以 Zettle API 返回 HTTP … 开头的提示 表示 Zettle 拒绝了配对码。在读卡器上打开 设置 → 与开发者关联,获取新的配对码,按显示内容准确输入,并确认读卡器已联网。如果仍然失败,请检查 Zettle 客户端 ID 和 Zettle 断言 是否已保存。

PayPal Reader:模拟读卡器已启用。 开发者设置 PRWC_USE_MOCK_READER 已在 wp-config.php 中定义。启用此设置时不会收取真实款项。请让开发者或托管服务商移除该设置。

进行设置​

本部分面向负责店铺 WP Admin 的人员,共五个步骤,涵盖从安装扩展到为 POS 启用扩展的整个过程。

安装扩展、输入凭据、配对读卡器并为 POS 启用
1

安装扩展

打开 WP Admin > POS > 设置 > 扩展,找到 PayPal Reader for WooCommerce,点击 安装,然后点击 启用。参阅安装扩展。

如果不使用扩展目录,请从 GitHub 发布页面下载 插件 zip 压缩包(不是源码 zip 压缩包),然后通过 插件 > Add Plugin,点击 上传插件 进行上传。WooCommerce 必须已启用。

2

获取 Zettle 凭据

在 Zettle 开发者门户中,为 Zettle 账户获取 客户端 ID 和 断言(JWT)。如果要试用网关而不收取真实款项,请先使用 Zettle 开发者(测试)商户账户。

可使用的 PayPal Reader 型号和国家或地区由 Zettle 账户决定,而非 WCPOS。购买读卡器前请向 PayPal 确认。

3

填写网关设置

  1. 前往 WP Admin > WooCommerce > 设置 > 支付,打开 PayPal Reader。
  2. 使用测试账户试用时,请保持 启用测试模式 为默认的勾选状态。
  3. 输入 Zettle 客户端 ID 和 Zettle 断言。
  4. 可选:更改收银员在支付页面上选择的 标题 及其 描述。
  5. 保存。
4

配对读卡器

  1. 向下滚动到同一设置页面底部的 已配对的读卡器。两项凭据均保存后,此部分才会出现。
  2. 在 PayPal Reader 上打开 设置 → 与开发者关联。读卡器会显示配对码。
  3. 在 配对新读卡器 下,输入 配对码 和 读卡器名称,例如 Front counter。如果未填写名称,则使用 WCPOS PayPal Reader。
  4. 点击 配对读卡器。页面显示 读卡器已配对。,读卡器会加入列表。

每台收银设备都能看到与该 Zettle 账户配对的所有读卡器,收银员可在结账时选择其中一台。要移除读卡器,请点击其旁边的 取消配对 并确认。

5

为 POS 启用

前往 WP Admin > POS > 设置 > 结账,找到 PayPal Reader,打开 已启用 开关。参阅启用网关。

注意

请勿勾选 为网站结账启用 PayPal Reader(WCPOS 无需此设置)。此选项仅用于在网店中列出该网关;在此处为 POS 启用后,POS 即可使用它。

测试模式与上线​

测试模式 不会将读卡器切换到沙盒环境。Zettle 的测试付款和真实付款使用同一组地址,是否发生真实资金流转取决于凭据对应的账户。测试模式只会更改支付面板上的标签:测试模式 标识,以及状态行中的 模式:测试。

上线步骤:

  1. 将 Zettle 客户端 ID 和 Zettle 断言 替换为正式 Zettle 账户的对应凭据。
  2. 取消勾选 启用测试模式,然后保存。
  3. 检查 已配对的读卡器。此列表来自 Zettle 账户,因此不会显示与测试账户配对的读卡器;请按进行设置中的 配对读卡器 步骤重新配对。
  4. 收取一笔小额真实付款,然后在 Zettle 中退款。

设置参考​

设置位于 WP Admin > WooCommerce > 设置 > 支付 > PayPal Reader。上面的步骤已涵盖必需的设置;展开列表可查看每项设置及其默认值。

全部 6 项设置及配对面板
设置作用
启用/禁用为网站结账启用 PayPal Reader(WCPOS 无需此设置)。在网店中列出该网关。请保持关闭:在线上,此网关仅适用于已有订单的支付页面。默认关闭。POS 在 POS > 设置 > 结账 下有独立开关
标题收银员在支付页面上选择的名称。默认为 PayPal Reader
描述标题下方显示的文字。默认为 Pay in person using PayPal Reader.
测试模式启用测试模式。在支付面板上显示 测试模式 标识。默认开启。此设置不会改变付款的处理环境
Zettle 客户端 ID从 Zettle 开发者门户获取的 Zettle OAuth 客户端 ID
Zettle 断言Zettle OAuth 断言(JWT)。像密码一样隐藏保存

设置下方的 已配对的读卡器 按名称和 关联 ID 列出每台读卡器,并提供 取消配对 按钮。配对新读卡器 中需要填写 配对码 和 读卡器名称。

日志​

请先查看订单备注:付款开始、完成或因金额不符被拒绝,以及在收银设备上点击 取消付款,都会记录在对应订单中。交易被拒绝、在读卡器上取消付款或连接断开则不会记录,请查看支付页面上的日志框。

当 Zettle 的读卡器服务拒绝请求或无法连接时,扩展还会在 WP Admin > WooCommerce > Status > 日志 中记录日志,来源为 paypal-reader-for-woocommerce。寻求帮助时,请提供该日志和 订单编号。

使用要求​

Zettle 账户: PayPal Zettle 商户账户,以及从 Zettle 开发者门户获取的客户端 ID 和断言(JWT)
读卡器: 与该账户配对的 PayPal Reader。可用型号和国家或地区取决于 Zettle 账户
网络连接: 仅支持在线使用。收银设备通过互联网经由 Zettle 与读卡器通信,因此收银设备、读卡器和店铺均需联网
WCPOS: WCPOS Pro
服务器: WordPress 5.2 或更高版本、WooCommerce,以及 PHP 7.4 或更高版本

不支持的功能​

  • 从 WooCommerce 或 POS 通过 Zettle 退款。
  • 在读卡器上收取小费。
  • 部分付款:读卡器始终收取整个订单的款项。
  • 支付页面关闭或重新加载后继续处理原付款。
  • 网店的常规结账流程。在线上,此网关仅适用于已有订单的支付页面。
工作原理(面向开发者)

店铺使用 JWT-bearer OAuth 授权方式登录 Zettle(oauth.zettle.com),并缓存访问令牌,直到其到期前 30 秒。配对、读卡器列表和付款会话均使用 Zettle 的 Reader Connect API(reader-connect.zettle.com/v1/integrator):配对时使用读卡器的配对码认领关联请求,每台读卡器对应一个关联。

开始读卡器付款 会请求店铺为所选关联创建会话。随后,支付页面建立与 Zettle 的 WebSocket 连接,查询读卡器状态,并在读卡器就绪后发送按订单总额收款且不含小费的付款请求。进度通过同一连接返回。取消付款 会通过该连接发送取消请求。

读卡器报告 COMPLETED 后,页面会将结果发送给店铺;只有金额与订单总额一致时,店铺才会接受结果。店铺将 Zettle 的银行卡付款 ID 保存为交易 ID,并提交订单。订单必须通过此检查后才能提交。

在自动化测试中,PRWC_USE_MOCK_READER(或 paypal_reader_for_woocommerce_use_mock_reader 过滤器)与 PRWC_MOCK_CANCEL_BEHAVIOR 配合使用,可用模拟读卡器替代 Zettle。此功能不会显示在设置中,启用时 WP Admin 会显示警告。