【后端接口】pullpay：充值下单接口与订单标记的幂等设计

实战应用：用在哪里

pullpay 是服务端主动发起的充值接口：游戏内触发支付流程（拉起收银台、生成订单），配合订单标记实现从下单到发货的全链路收口。与被动等回调的充值不同，主动下单让游戏内可以直接卖金额明确的商品。

接口签名与下单

---发起充值 actor:玩家 money:金额 type:支付方式 flagid:订单标记
function pullpay(actor, money, type, flagid) end

-- 游戏内购买月卡：下单 30 元微信支付
function Shop.buyMonthCard(actor)
    local orderId = "MC" .. os.time() .. actor:GetUserId()
    pullpay(actor, 30, 3, 0)
    pendingOrders[orderId] = { item = "月卡", at = os.time() }
    return true
end

money 是下单金额，type 区分支付方式（1 支付宝、2 花呗、3 微信），flagid 关联业务标记。下单后支付平台唤起收银台，支付结果通过回调触发发货，订单的本地登记让每一笔待支付的状态可查。

回调的发货收口

-- 充值回调里的订单发货
function OnPayCallback(order)
    local rec = pendingOrders[order.id]
    if not rec then return false end
    if rec.delivered then return true end
    rec.delivered = true
    giveitem(actor, rec.item, 1, 0, "内购订单")
    TradeLog.write("pay", order.id, rec.item)
    return true
end

回调的发货用 delivered 标记保证幂等：支付平台的重复通知不会造成重复发货。发货失败（背包满）走邮件兜底，邮件的附件在领取前受系统保护。订单的超时清理：30 分钟未支付的订单关闭并释放，关闭的订单若后续支付成功（延迟到账），发货流程重新激活而不是拒绝。

验证与监控

下单量、支付成功率、发货成功率三个漏斗指标按日监控，任一环节的断崖都是资损或体验的前兆。

踩坑记录

金额的单位在支付平台（分）与游戏内（元）曾经换算错位，1 元的商品被扣成 0.01 元，单位的换算函数统一封装后根治。订单号的生成用时间戳加随机数，纯时间戳在高峰期的碰撞让两笔订单共享一个标记，随机段的加入让订单号唯一。

上线要点

pullpay 的调用入口收敛到商城模块，业务侧不允许随意拉起收银台。支付方式的可用性配置化：某通道故障时下架对应选项，玩家看到的支付选项永远可用。订单的本地登记与支付平台的订单对账每日执行，差异订单在 24 小时内处理完毕。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。