本页目录资金流 create_order 返回的支付三字段按宿主形态呈现付款成功的感知支付失败的常见情形退款去哪了

支付与收银台

用户的钱怎么付、付给谁、agent 在其中的角色。核心原则：agent 引荐交易，但永不碰钱。

资金流

用户 ──微信支付──▶ 源头淘自营主体（收款方）        agent 只拿到 pay_url 与订单状态
                     └─平台按分销价与商家结算      用户/商家都不与 agent 发生资金关系

这个结构的三个含义：用户不用担心 agent 拿回扣乱推荐；商家不用担心 agent 假单（真实收货地址+真实付款）；agent 开发者不触碰支付合规（收单、退款、结算全部由平台完成，佣金分账走平台台账）。

create_order 返回的支付三字段

字段	含义
`pay_url`	微信收银台链接（`weixin://...`）
`render_hint`	呈现方式：`qrcode`=渲染二维码；`redirect`=跳转链接
`expire_in_minutes`	支付窗口（30 分钟），超时订单自动关闭

按宿主形态呈现

桌面/终端宿主（WorkBuddy、ZCode、CLI）——render_hint=qrcode

把 pay_url 渲染成二维码展示，用户掏手机微信扫码。任何能画图的环境一行代码：

node

// 终端二维码：npm install qrcode-terminal
const qrcode = require('qrcode-terminal');
qrcode.generate(order.pay_url, { small: true });
console.log(`请用微信扫码支付 ¥${(order.amount / 100).toFixed(2)}`);

python

# pip install qrcode pillow
import qrcode
img = qrcode.make(order['pay_url'])
img.save('pay.png')
print(f"请用微信扫码支付 ¥{order['amount'] / 100:.2f}（已生成 pay.png）")

手机宿主（App / 移动 Web）——render_hint=redirect（或按 qrcode 自行降级）

不要让用户扫自己手机上的二维码——直接跳转：

node

// WebView / 浏览器环境
window.location.href = order.pay_url;

NOTE 当前阶段 pay_url 为微信 Native 串，手机宿主可先按二维码降级呈现；平台上线 H5/APP 通道后 render_hint 自动变为 redirect，你的代码按字段分支即可、无需预判。

付款成功的感知

两种方式：

轮询（当前可用）：5-10 秒间隔调 get_order_status，看到 status 离开 pending_payment（进入 paid 及之后）即支付成功。
事件时间线：响应里的 events 数组按序记录 paid → merchant_accepted → shipped → delivered，可直接转述给用户。

WARNING 不要假设支付立即成功——用户可能放弃支付。30 分钟未付订单自动 closed，此时再对该单轮询会得到终态，应引导用户重新下单。

支付失败的常见情形

现象	原因	处理
用户扫码后提示订单已关闭	超过 30 分钟窗口	重新 `create_order`（新 Idempotency-Key）
`PAY_EXPIRED`	同上（程序侧感知）	重新下单
用户付了但状态未变	回调延迟（秒级）	轮询等待 10-30 秒再判断
金额对不上	转述时忘了分转元	`amount / 100`，保留两位小数

退款去哪了

原路退回用户微信（见售后与退款）。退款到账时间以微信侧为准（通常 1-3 个工作日，小额实时）。