WPMP · 商户工作台

订单数量—全部收银订单

已绑定设备—等待获取状态

当日订单金额—按北京时间创建日期统计

当月订单金额—含待处理、取消和超时订单

连接新设备

下载安卓 APP（1.0.0）
支持 Android 10 及以上。安装后在此生成绑定码。

绑定码5分钟有效，仅能使用一次。

请在客户端输入此绑定码

理解设备状态

设备在线，只代表最近收到了心跳。

通知访问权限: 系统是否允许客户端读取通知
采集服务状态: 监听器是否连接、是否支持当前环境
支付来源可见性: 是否观察到微信或支付宝来源；不代表收款模板已通过
本地待传队列: 仍在设备上等待服务端确认的线索

Android 手机直接上报服务端，无需 Windows 客户端。最近在线不保证期间没有漏通知；后台省电可能延迟上报。

我的设备

删除后设备立即停止上传，绑定收款码自动暂停；历史通知保留。

操作记录

查看商户创建、绑定和撤销等最近操作。

回调配置

新通知入库后投递事件，回调不确认支付或结算。

地址变更、停用或更换密钥会取消尚未发送的旧投递；正在发送的请求可能已经送达原地址。

签名与联调

首次保存或更换密钥时只显示一次。业务系统须按原始请求体验签，并按投递编号去重。

只有对方返回 2xx 才标为“已确认接收”。网络错误、超时、429 和服务端错误会重试；投递至少一次，可能重复，业务系统必须去重。所有通知线索始终未经支付核验。

投递记录

最近结果与逐次尝试日志。详情不包含签名密钥。

上传收款码

分配规则

同一支付渠道、同一采集手机、同一金额只能有一个正在展示的订单，其余排队。不同真实账户和采集手机可并行。

展示两分钟后过期，排队最多三十分钟。多个码会轮流分配，但同一账户的多个码无法区分到账。

页面过期不能使静态码失效，迟付仍可能误匹配新订单。这里只做未经核验的金额关联。

我的收款码

创建收银订单

请先在“业务回调”中启用订单金额匹配事件。

业务系统接入

任何后端语言均可通过 HTTP/JSON 接入。请求体只需订单号和金额；接口密钥放在请求头，不能放入客户页面。

更换后旧接口密钥立即失效；已创建的收银链接不变。

1. 接入准备

适用于 PHP、Java、C#、Python、Node.js 等所有支持 HTTP 的服务端。先绑定 Android 手机、上传并启用收款码，再在“业务回调”填写 URL，启用并订阅“订单金额匹配”。

以下接口路径相对于当前 WPMP 站点地址。线上接入使用 HTTPS。

订单接口密钥以 capi_ 开头，在上方生成，只显示一次。回调签名密钥以 whsec_ 开头，在“业务回调”保存或更换时显示。两种密钥用途不同，均仅保存在业务后端，禁止放入网页、APP 或 URL。

2. 创建订单

POST /api/v1/cashier-orders
Authorization: Bearer capi_你的订单接口密钥
Content-Type: application/json

{"orderNo":"SHOP_20261102_001","amount":"1.00","channel":"ALIPAY","returnUrl":"https://merchant.example/result"}

orderNo：1–64 位字母、数字、下划线或横线，商户内唯一。amount：金额单位为元，支持字符串或数字，必须大于零、最多两位小数，最大 10000000 元。推荐字符串避免浮点误差。channel为WECHAT或ALIPAY，省略默认微信。可选returnUrl为业务系统HTTPS返回页。无需传收款码或异步回调URL，服务端按渠道及已保存配置分配。

HTTP 201
{
  "id":"订单UUID",
  "orderNo":"SHOP_20261102_001",
  "amountMinor":100,
  "currency":"CNY",
  "status":"WAITING_PAYMENT",
  "cashier_url":"http://192.168.0.2:5080/cashier/co_随机令牌",
  "expiresAt":"2026-11-02T02:02:00Z",
  "payment_state":"UNKNOWN",
  "settlement_state":"UNKNOWN"
}

示例仅列主要字段。把 cashier_url 提供给客户打开；它是单笔订单的访问凭证，持有者可查看及取消该单，请勿公开或记录完整链接。客户核对实际收款方并手动输入页面金额。

同订单号、同金额重复请求返回 HTTP 200 和原订单；不同金额返回 409。重复调用不会重新计时；过期后须使用新订单号。同采集来源、同金额已有展示订单时返回 QUEUED，客户页面自动等待；分配后展示两分钟，排队最多三十分钟。

3. 查询订单与页面返回

收银台检测到金额匹配后，约1.2秒跳转到创建订单时传入的returnUrl，并提供手动返回链接。附带wpmp_order_no、wpmp_order_id、wpmp_channel、wpmp_order_state。此为浏览器同步返回，不带支付成功证明；业务后端应验签异步回调或使用接口密钥查询。页面关闭或网络中断可能无法跳转。

同号重试必须保持金额、channel和returnUrl一致，修改渠道或返回地址返回409 ORDER_REQUEST_CONFLICT。返回地址不接受HTTP、javascript、相对路径、回环IP或账号信息。旧订单没有returnUrl时仍停留在结果页。

GET /api/v1/cashier-orders/SHOP_20261102_001
Authorization: Bearer capi_你的订单接口密钥

返回与创建订单相同结构；GET /api/v1/cashier-orders 返回商户最近 100 单。订单状态如下：

status	含义
QUEUED	等待收款码分配
WAITING_PAYMENT	正在展示收款码，等待金额通知
AMOUNT_MATCHED_UNVERIFIED	检测到来源、金额及时间匹配的通知；工作台显示“金额匹配”
EXPIRED	展示两分钟超时；后续延迟上传的窗口内通知仍可能关联
QUEUE_EXPIRED	排队三十分钟超时
CANCELED	客户取消，或收款码删除
SOURCE_UNAVAILABLE	采集设备删除或停用

4. 接收订单回调

金额匹配后 POST JSON 到商户配置的 URL。默认要求公网 HTTPS 443，禁止内网、保留地址及重定向；内网接收器只有运维显式设置唯一测试地址后可用。

X-WPMP-Event: cashier.order_matched
X-WPMP-Delivery-Id: 投递UUID
X-WPMP-Timestamp: Unix秒时间戳
X-WPMP-Signature: v1=64位小写十六进制签名
Content-Type: application/json

{
  "event_id":"订单UUID",
  "event_type":"cashier.order_matched",
  "occurred_at":"2026-11-02T02:01:00Z",
  "data":{
    "order_id":"订单UUID",
    "order_no":"SHOP_20261102_001",
    "amount_minor":100,
    "currency":"CNY",
    "collection_code_id":"收款码UUID",
    "observation_id":"通知UUID",
    "order_state":"AMOUNT_MATCHED_UNVERIFIED",
    "risk":{"static_qr_can_still_receive":true,"recent_same_amount_slot_reuse":false},
    "verification":{"notification_state":"OBSERVED_UNVERIFIED","payment_state":"UNKNOWN","settlement_state":"UNKNOWN"}
  }
}

创建/查询响应采用 orderNo、amountMinor 等字段，回调采用 order_no、amount_minor，注意区别。notification.test 仅用于测试，不处理为订单；若同时订阅 notification.observed，则还会收到独立通知事件。

5. 验签、去重与应答

签名原文 = timestamp + "\n" + deliveryId + "\n" + 原始HTTP请求体
签名 = HMAC-SHA256(UTF-8回调签名密钥, UTF-8签名原文)
请求头 = "v1=" + 小写十六进制(签名)

必须使用收到的原始请求体字节，不可先解析 JSON 再序列化；密钥为完整 whsec_ 字符串，不做 Base64 解码。校验时间戳与当前时间相差不超过 300 秒，用恒定时间比较签名，并校验事件头与正文 event_type 一致。

验签后在同一数据库事务中检查并保存 X-WPMP-Delivery-Id（唯一键）和本地业务处理结果，提交后返回任意 2xx；重复投递返回 2xx，不重复处理。不要只按时间戳去重；投递重试保留相同编号和正文，但更新时间戳及签名。

自动最多尝试六次；网络异常、超时、408、429 和 5xx 会重试，常规间隔为 5、30、120、600、3600 秒，Retry-After 最多延至一小时。3xx 不跟随，其他 4xx 停止。失败后可在投递记录手动重试，业务系统仍须按编号去重。接收器应尽快持久化并返回，服务端请求超时十秒。

更改 URL、订阅事件、停用或更换签名密钥会取消旧配置尚未发送的投递；已经开始发送的请求可能送达。接口密钥轮换立即使旧 capi_ 密钥失效，不改变已有收银链接。

6. 积分计费、常见错误与统计口径

自然月使用费按北京时间收取，积分不足返回402 MONTHLY_FEE_DUE，只暂停新订单；充值后自动尝试缴费。已缴费月份和已有订单价格锁定。下级订单实际扣费后，费率差价自动逐级记入代理积分，未实际扣费不结算收益。

1元充值兑换1积分。商户订单服务费＝订单金额（元）×费率（百分比），向上取整到0.01积分；创建时预留，金额匹配后扣除，取消/超时释放。费率在创建时锁定。余额不足返回409 INSUFFICIENT_POINTS；有待补扣费用返回409 POINTS_ARREARS，充值后自动补扣。停用商户返回403 MERCHANT_SUSPENDED。创建/查询响应新增 feePoints、feeState、feeRatePercent，回调 data.fee 包含 points、state、rate_percent。

401：订单接口密钥无效或失效；404：订单不存在或不属于当前商户；409 ORDER_AMOUNT_CONFLICT：同号金额不同；422 NO_COLLECTION_CODES：无可用绑定收款码；422 ORDER_CALLBACK_NOT_READY：未启用订单回调；422 INVALID_ORDER：订单号或金额格式错误；429：请求过快或待处理订单超过限制。错误体含 code、message、request_id、retryable。请求超时后使用相同订单号和金额重试，避免重复下单。

概览按北京时间（Asia/Shanghai）和订单创建时间统计，金额是所有状态的订单金额合计，包括排队、取消和超时订单，不是实际到账金额；统计覆盖全部历史订单，不限最近 100 单。

金额匹配来自设备通知，不是微信官方支付证明；payment_state、settlement_state 保持 UNKNOWN。静态码超时、暂停或删除后仍可能被截图付款，迟付、重复通知或账户绑定错误可能误关联。业务系统应结合订单风险决定后续处理。

7. 五种语言接入示例

在业务后端设置 WPMP_BASE_URL（站点 HTTPS 地址，末尾不加斜杠）、WPMP_API_KEY（capi_）和 WPMP_WEBHOOK_SECRET（whsec_）。创建时传入订单号、整数分金额和支付渠道，例如 DEMO-001、100、ALIPAY，从响应取 cashier_url 跳转到收银台。用同一订单号查询。

将接收方法接到 POST 回调路由并传入原始请求体字节。验签失败返回 400。验签通过后，以投递编号为唯一键，在事务中记录订单匹配事件，提交成功或确认已处理时返回 204，持久化失败返回 503。notification.test 可直接应答 204，业务仅处理 cashier.order_matched。金额匹配不代表官方支付核验。

查看代码

选择语言下载示例

总积分—1元兑换1积分

可用积分—扣除订单预留部分

预留积分—取消或超时自动释放

商户费率—

充值积分

积分规则

充值1元兑换1积分，充值到平台收款码，通知金额匹配后自动入账。充值前核对收款人和金额，不要向商户自己的收款码支付。

服务费积分＝订单金额（元）×商户费率，向上取整到0.01积分。创建订单预留积分，金额匹配后扣除；取消或超时释放预留。延迟匹配可能产生待补扣服务费，充值后自动补扣。

充值采用个人收款通知匹配，不等于官方到账核验；静态码迟付或账户绑定错误可能误关联。自动入账保留通知编号和充值流水，遇到差异请联系平台。

自然月使用费

按北京时间自然月收费，首月全额、不按天折算；余额不足仅暂停新订单，充值后自动尝试缴费。

充值记录

积分明细

展示最近100条；预留与释放不改变账面余额。

常见问题

登录公告

发布后，用户下次登录会看到公告。取消勾选并保存即可下线。

常见问题管理

平台充值与计费设置

平台充值收款配置

以总后台账号在“设备管理”绑定平台采集手机，再到“收款码”上传平台收款码。商户充值统一使用这些收款码，不使用商户自己的收款码。平台充值不依赖外部业务回调。

多个独立收款账户可并行，同来源同额充值会排队；收银页面展示两分钟。充值额度在创建时锁定，更改费率只影响新订单。

普通注册账号不会自动成为管理员。停用商户会注销其会话、阻止接口和设备上传，并关闭其待处理订单；重新启用后须重新登录。

此入口连接系统自己的积分充值，不填写业务回调URL。会员和代理从“我的积分”创建充值，平台手机的通知匹配后自动入账，重复通知不会重复加分。

商户管理

平台充值记录

全部商户积分流水

最近200条，包含手动充值、自动充值及订单扣费。

修改登录密码

商户、代理和总后台均在这里修改自己的密码。修改成功后保留当前登录，其他登录会话立即失效；设备及订单接口密钥独立管理。

我的身份—

我的费率成本—

我的月费成本—

累计差价收益—实际扣费后自动入积分

新增下级账号

分级价格与差价

代理可以管理直属商户和直属代理；下级订单费率及月费不得低于自己的成本价。总后台可设置任意代理的成本和归属，代理不能修改自己的成本或转移下级归属。

订单费率、上级链和差价在创建订单时锁定，月费在首次生成本月账单时锁定。实际扣费成功后，差价逐级自动记入代理积分；重复通知或重试不会重复结算。

月费按北京时间自然月收取，首月收整月费用，不按天折算；不补扣以前未使用月份。修改价格不改变已有账单或订单。当月未缴费或积分不足，不能创建新收银订单；充值、历史查询仍可使用。

存在下级时不能直接降为普通商户；上调代理成本前须先调整下级价格。停用代理会阻止其整条下级链使用，独立停用的下级不会随上级恢复而自动启用。