金牛支付开放平台

商户收款 API · 与金牛钱包同一账户体系 · 收款直接入账钱包余额 · ← 返回官网

一、接入流程

1. 使用金牛ID登录 金牛钱包 → 「开放平台」→「申请接入」,填写应用名称与 notify_url(https 必填)、return_url(可选)。
2. 平台管理员审批通过后签发 AppID 与 AppSecret(仅商户本人可见,可随时重置)。
3. 服务端持 AppSecret 签名调用下列接口。密钥严禁下发至前端。

二、签名规则(MD5)

将除 hash 外的非空参数按参数名 ASCII 升序(ksort)拼接为 a=1&b=2 形式,末尾直接拼接 AppSecret,取 MD5(32位小写)得到 hash:

$params = ['appid'=>..., 'trade_order_id'=>..., 'total_fee'=>..., 'title'=>..., 'time'=>time(), 'nonce_str'=>...];
ksort($params);
$str = urldecode(http_build_query($params)) . $appSecret;
$params['hash'] = md5($str);

回调验签同理:对收到的参数(除 hash)重算 MD5,与 hash 一致后方可入账,并原样应答 success,否则平台将重试(最多 5 次)。

三、接口

POST/payment/do.html · 收款下单

参数	必填	说明
appid	是	应用 AppID
trade_order_id	是	商户侧订单号(唯一,幂等键)
total_fee	是	金额,单位元,如 1.00
title	是	商品标题(展示于收银台)
time	是	Unix 时间戳(秒),偏差须在 ±10 分钟内
nonce_str	是	随机字符串
notify_url / return_url	否	覆盖应用默认配置
hash	是	MD5 签名

响应:

{"errcode":0,"errmsg":"success!","open_order_id":"WO260801-1001",
 "trade_order_id":"YOUR-ORDER-1","status":"WP","total_fee":"1.00",
 "url":"https://pay.jnqj.net/pay/cashier?id=WO260801-1001",
 "url_qrcode":"https://pay.jnqj.net/pay/cashier?id=WO260801-1001"}

把 url(移动端)或 url_qrcode(PC,本身即二维码图片,无需再次编码)交给付款人即可。

付款人无需注册或登录金牛钱包 —— 收银台默认走支付宝(经官方渠道清算); 若付款人恰好是金牛钱包用户,也可选择用钱包余额支付。两种方式都在支付成功后回调您的 notify_url。

POST/payment/query.html · 订单查询

参数:appid + out_trade_order(商户单号)或 open_order_id(平台单号)+ time + nonce_str + hash。

{"errcode":0,"open_order_id":"WO…","trade_order_id":"…","status":"OD",
 "total_fee":"1.00","refunded_fee":"0.00","transaction_id":"1000…","paid_at":"2026-08-01 12:00:00"}

POST/payment/refund.html · 原路退款

参数:appid + trade_order_id 或 open_order_id + refund_fee(元,可部分退,累计不可超原单)+ time + nonce_str + hash。退款自商户钱包余额原路冲回付款人余额。

POST支付回调(平台 → 商户 notify_url)

trade_order_id=YOUR-ORDER-1&open_order_id=WO…&order_title=…&total_fee=1.00
&transaction_id=1000…&status=OD&appid=JN…&time=…&nonce_str=…&hash=…

验签一致且 status=OD 时给用户发货/入账,并应答 success。

四、订单状态

状态	含义
WP	待支付
OD	已支付(部分退款仍为 OD)
RD	退款中
CD	已退款(全额退完)
UD	退款失败

五、付款人体验

收银台(/pay/cashier?id=…)对付款人提供两条路径:

方式	是否需要金牛钱包账号	资金来源
支付宝支付(默认)	不需要	付款人支付宝,官方清算
金牛钱包余额	需要,金牛ID授权登录	付款人钱包余额

两种方式到账后商户均得净额(已扣手续费),并收到同一份 status=OD 异步回调。 注意:商户本人不能用自身余额支付自己应用的收款单(防自刷),但支付宝支付不受此限。

六、费率与合规

每笔收款按平台费率(默认 3% + ¥1.00,最低 ¥1.00)收取手续费,入账时扣除;退款不退手续费。全部调用写入 API 日志与审计哈希链,可供监管审查。沙箱联调请使用钱包内「开放平台 → 沙箱」,不产生真实资金流。