开发文档

V3 是这套网关自己的协议：请求体 JSON、应答 JSON、金额用分的整数、签名是 HMAC-SHA256， 再配幂等键和每请求一个 request_id。它不改动任何资金与订单口径——打的是同一套订单、同一本账， 所以 V1 下出去的单可以在 V3 查、在 V3 退。

V3 比 V1/V2 多的东西

公共请求头

应答信封

{"code":0,"message":"success","request_id":"req_2f6b9c41d0a53e17","data":{ … }}

V3 不吃 V1/V2 那把商户密钥，用的是单独发放的接入凭据。一个商户号下可以开多个接入号， 每个接入号一把密钥、一份权限、一份 IP 白名单——哪个程序泄露了就停用哪个，其它业务照跑。

轮换（换密钥不断单）

点「重置密钥」后，新密钥即刻可用，旧密钥再保留 24 小时：这期间两把都能验签， 你可以先把一部分服务器切过去、再切剩下的，不用停机也不用两边同时改配置。24 小时一过旧密钥作废。

应答验签（可选）

每个 V3 应答都额外带两个响应头，用同一个 AppSecret 可验证应答确实来自平台、没被中间人改过：

X-Spay-Resp-Timestamp: 1761370001
X-Spay-Resp-Sign:      HMAC-SHA256("v3." + timestamp + "
" + request_id + "
" + sha256_hex(应答体), AppSecret)

查单、对账这类动钱的调用建议验；普通的下单请求看一眼 code 也够用。

待签名串是三行拼成的一个字符串，下面的 \n 是真正的换行符：

v3.<timestamp>
<nonce>
<sha256_hex(请求体原始字节)>

1. 第一段固定前缀 v3.，timestamp 与 nonce 取请求头里的原值；
2. 第三段是请求体原始字节的 SHA-256 十六进制小写：不是按字段排序、不是格式化后的 JSON。算完签名就不要再重新序列化一次；
3. 签名 = HMAC-SHA256(待签名串, 该接入号的 AppSecret)，输出 64 位十六进制小写，放 X-Spay-Sign；
4. 异步通知用同一套算法，密钥是这笔下单时所用接入号的那把 AppSecret（通知体里的 app_id 会告诉你是哪个接入号）， 只是签名方换成平台，请求侧和验签侧代码共用一份；
5. 应答头里的 X-Spay-Resp-Sign 也用它，见「V3 接入凭据」；轮换窗口内旧 AppSecret 仍可验签，新签出来的永远用当前这把。

import hashlib, hmac, json, time, uuid, requests

BASE   = "https://pay.your-site.com"
APP_ID = "app_6f1c2d3e4a5b6c7d"      # 商户中心「API 信息」页发的接入号
SECRET = "spayv3_...40位十六进制..."   # 与它配对的 AppSecret，只放服务器

body = json.dumps({"out_trade_no": "P202610250001", "amount": 1234,
                   "subject": "VIP会员", "pay_type": "alipay",
                   "notify_url": "https://your.site/pay/notify"},
                  separators=(',', ':')).encode('utf-8')
ts, nonce = str(int(time.time())), "n-" + uuid.uuid4().hex[:12]
content = "v3.%s\n%s\n%s" % (ts, nonce, hashlib.sha256(body).hexdigest())
sign = hmac.new(SECRET.encode(), content.encode(), hashlib.sha256).hexdigest()

resp = requests.post(BASE + "/v3/pay/create", data=body, headers={
    "X-Spay-App-Id": APP_ID, "X-Spay-Timestamp": ts,
    "X-Spay-Nonce": nonce, "X-Spay-Sign": sign,
    "Content-Type": "application/json",
    "Idempotency-Key": str(uuid.uuid4())})
print(resp.json())   # 先判 code == 0，再取 data

服务端对服务端下单。带 pay_type 时直接拿到买家要用的收款信息；不带时落平台收银台，让买家自己选支付方式。

请求参数

返回参数（data）

pay_mode 怎么用

请求示例

curl -X POST https://spay.dlam.cc/v3/pay/create \
  -H "Content-Type: application/json" \
  -H "X-Spay-App-Id: app_6f1c2d3e4a5b6c7d" -H "X-Spay-Timestamp: 1761370000" \
  -H "X-Spay-Nonce: n-8f3c1a2b9d" -H "X-Spay-Sign: 64位十六进制" \
  -H "Idempotency-Key: 2f6b9c41-d0a5-4b1e-9a37-1c0d7e5f2a44" \
  -d '{"out_trade_no":"P202610250001","amount":1234,"subject":"VIP会员","pay_type":"alipay","notify_url":"https://your.site/pay/notify"}'

返回示例

{"code":0,"message":"success","request_id":"req_2f6b9c41d0a53e17",
 "data":{"trade_no":"202610250751412050917c98acfe03","out_trade_no":"P202610250001",
   "amount":1234,"status":"paying","pay_mode":"jump",
   "pay_info":"https://…","cashier_url":"https://spay.dlam.cc/pay/202610250751412050917c98acfe03",
   "created_at":"2026-10-25 07:51:41"}}

下单、退款、关单三个写接口支持 Idempotency-Key，解决的是同一件事： 请求发出去了、响应没收到（超时、连接被切断、网关 502），你不知道服务端到底做没做。

• key 用 UUID 或你的雪花号，至少 8 位、最长 64 位；每个 key 只在服务端保留 24 小时。
• 一个 key 只能用在同一个端点：服务端把它连同端点一起存，拿 pay/create 用过的 key 去打 pay/refund 直接判 40901——否则回的会是那次建单的应答，等于替你确认了一笔没做的退款。换端点请换 key。
• 重试要三个数都不变：Idempotency-Key、请求体、商户号；请求体变了就是另一次业务，服务端会拒绝而不是替你猜。
• key 只管「同一次业务调用别执行两遍」，订单唯一性仍由 out_trade_no 兜底——两道都在，缺一道理赔都说不清。
• 不带 key 也能调通，只是超时后你只能先查单确认，再决定要不要重下。

查单笔订单，只查得到自己商户的单。请求体两个单号任填其一，都填时按 trade_no。

请求参数

返回参数（data）

status 取值

V1/V2 的 status 是 0/1/2 三个数字（0 未支付、1 已支付、2 已退款，closed 与 failed 都折进 0）； V3 直接回上面这些字符串，判「钱到了」用 paid / notified / settled 三个。

返回示例

{"code":0,"message":"success","request_id":"req_7c1f0a9e5b2d4318",
 "data":{"trade_no":"202610250751412050917c98acfe03","out_trade_no":"P202610250001",
   "merchant_no":"1001","subject":"VIP会员","pay_type":"alipay",
   "amount":1234,"real_amount":1234,"get_amount":1180,"refund_amount":0,
   "status":"paid","channel_trade_no":"20261025075141001","bill_trade_no":"202610252200…",
   "buyer":"","param":"uid=88",
   "created_at":"2026-10-25 07:51:41","paid_at":"2026-10-25 08:02:11"}}

商户自助退款，从商户余额扣回，需要商户开通退款权限。支持部分退款，每一笔都是独立退款单。

请求参数

请求头还必须带 Idempotency-Key：退款是唯一「不带就拒」的写接口，缺了回 40001，因为超时重试时它是第二个凭据——out_refund_no 由你自己生成， Idempotency-Key 证明「这条报文就是我刚才那条」。两个都带才是稳的。

返回参数（data）

返回示例

{"code":0,"message":"success","request_id":"req_3a8e5d2c1b047f96",
 "data":{"refund_no":"20261025081122331156","out_refund_no":"R20261025001",
   "trade_no":"202610250751412050917c98acfe03","out_trade_no":"P202610250001",
   "amount":1234,"reduced_amount":1210,"refunded_amount":1234,"status":"refunded",
   "deduplicated":false}}

关闭一笔未支付订单。先让上游关，上游关掉了本地才落 closed—— 不会本地一关了之，否则上游二维码还活着，买家随后付成功就成了没人认领的收款。

请求参数

成功回 {code:0,message:"success",request_id:"…",data:{trade_no,status:"closed"}}。 已支付或已退款的单不可关，回 42201 / BUSINESS_REJECTED； 聚合类上游没有关单接口，回 42201 且 message 说明「当前支付插件不支持关闭订单」。

两个接口都无业务参数，请求体传空对象 {}（仍要正常签名）。

data · /v3/merchant/info

data · /v3/merchant/balance

余额口径与商户中心「资金账户」页完全一致：三个数是三本账，加起来不等于「今天收了多少」， 因为结算周期会把今天的收入压到明天才放出 available。

V3 下的单发 V3 通知：JSON POST 到你的 notify_url，签名在请求头上，正文里没有 sign 字段。 V1/V2 下的单仍按各自那一代的格式发（见「支付结果通知」）。判定送达的方式变了：HTTP 状态码 2xx 就算收到， 不需要再输出 success 这个字。

通知请求头

通知正文

验签与响应

raw = 请求原始字节                       // 不要用解析后再序列化的 JSON
content = "v3." + X-Spay-Timestamp + "\n" + X-Spay-Nonce + "\n" + sha256_hex(raw)
signOK  = hmac_sha256_hex(merchantKey, content) == X-Spay-Sign
match   = body.out_trade_no == 本地单号 and body.amount == 本地应收(分)
      and body.merchant_no == 我的商户号 and body.event == 'trade.paid'
if signOK and match and not already_paid(body.out_trade_no): 发货 / 加余额
return 200                                 # 重复通知同样回 200

重试与 V1/V2 同一套：最多 8 次，按 15 秒、30 秒、2 分钟、5 分钟、15 分钟、30 分钟、1 小时退避。 用完仍未拿到 2xx 时任务转终态不再发送——钱不会因此退回，订单仍是已收款，靠查单接口兜底或请后台手工补发。

失败时 code 是下面这五个数字之一，error_code 是它的机读名；HTTP 状态码与 code 同源， 所以网关和 CDN 后面的排障也能对上。message 是给人看的中文，可能措辞微调，不要判它。

由买家浏览器提交表单，验签通过后把人送到上游或平台收银台。也可以拼成 URL 直接跳转，但走 GET 时整套参数都得在查询串里： 系统按老 PHP 的口径取参数，pid 出现在查询串就整份按查询串验签，这时 POST 体里的字段一律不参与签名，混着传必然对不上。 页面单可以不传 type——留空时买家在收银台自己选支付方式。

请求参数

返回说明

成功返回一段自动跳转页，把买家送到收款页，没有 JSON。失败返回一张错误提示页，正文是那句中文原因； 缺参数的判定顺序与老接口一致（先「订单号(out_trade_no)不能为空」，再 notify_url、return_url、name、money）。 完全没带 pid 时回纯文本「你还未配置支付接口商户！」——老收银台插件靠这句话判断自己没配好。

请求示例

<form method="post" action="https://spay.dlam.cc/submit.php" id="pay">
  <input type="hidden" name="pid" value="1001">
  <input type="hidden" name="out_trade_no" value="202610250001">
  <input type="hidden" name="type" value="alipay">
  <input type="hidden" name="name" value="VIP会员">
  <input type="hidden" name="money" value="12.34">
  <input type="hidden" name="notify_url" value="https://your.site/pay/notify">
  <input type="hidden" name="return_url" value="https://your.site/order/1">
  <input type="hidden" name="sign_type" value="MD5">
  <input type="hidden" name="sign" value="算出来的签名">
</form>
<script>document.getElementById('pay').submit()</script>

V2 等价入口：POST /api.php?s=pay/submit（或 /api/pay/submit），参数相同另加 timestamp 与 sign； 区别是失败回 {code:-1,msg} 的 JSON 而不是提示页——调用方是服务器时更好处理。

服务器对服务器下单，返回 JSON，由你自己的页面渲染二维码或跳转。

请求参数

返回参数

请求示例

curl -d "pid=1001&out_trade_no=202610250001&type=alipay&name=VIP会员&money=12.34" \
     -d "notify_url=https://your.site/pay/notify&clientip=1.2.3.4" \
     -d "sign_type=MD5&sign=算出来的签名" \
     https://spay.dlam.cc/mapi.php

返回示例

{"code":1,"trade_no":"202610250751412050917c98acfe03","payurl":"https://…"}

推荐的下单方式：真签名、带时间戳防重放、应答带平台签名。等价写法 POST /api/pay/create（不需要 nginx 重写）。

请求参数

返回参数

请求示例

params = {pid: 1001, timestamp: now(), sign_type: 'RSA',
          out_trade_no: '202610250001', type: 'alipay',
          name: 'VIP会员', money: '12.34', clientip: '1.2.3.4',
          notify_url: 'https://your.site/pay/notify'}
params.sign = base64(sha256WithRSA(sign_content(params), merchantPrivateKey))
// POST 表单到 https://spay.dlam.cc/api.php?s=pay/create

返回示例

{"code":0,"trade_no":"202610250751412050917c98acfe03","pay_type":"jump",
 "pay_info":"https://…","timestamp":"1761370001","sign_type":"RSA","sign":"…"}

查单笔订单。V1 等价入口：GET /api.php?act=order（pid + 明文 key，字段平铺在顶层、无 data 层）。

请求参数

返回参数

请求示例

curl -d "pid=1001&timestamp=1761370000&out_trade_no=202610250001&sign_type=MD5&sign=…" \
     https://spay.dlam.cc/api.php?s=pay/query
# V1：curl "https://spay.dlam.cc/api.php?act=order&pid=1001&key=商户密钥&out_trade_no=202610250001"

到账后由平台主动通知你的服务器。先记三句话：通知是 GET，参数拼在 notify_url 的查询串上（地址已带 ? 就用 & 续）； 响应正文含 success（不区分大小写）才算送达；重复通知是常态，必须按订单号幂等。

通知参数

签名口径（跟着下单入口那一代走）

重试与验签示例

最多 8 次，按 15 秒、30 秒、2 分钟、5 分钟、15 分钟、30 分钟、1 小时退避。 用完仍未收到 success 时任务转终态不再发送——但钱不会因此退回：订单仍是已支付，靠查单接口兜底，或请后台在订单详情页手工补发。

p = 请求的查询参数                       // 通知是 GET 查询串
signOK = p.sign_type == 'RSA'
  ? rsaVerifyWithPlatformKey(sign_content(p), p.sign)
  : p.sign == md5(sign_content(p) + merchantKey)
match  = p.out_trade_no == 本地单号 && p.money == 本地应付金额
      && p.trade_status == 'TRADE_SUCCESS' && p.pid == 我的商户号
if signOK && match && 本地单未入账 { 发货 / 加余额 }
response 'success'                       // 重复通知也一样回 success

商户自助退款，从商户余额扣回。V1 等价入口 GET /api.php?act=refund，只有那里 code=0 算成功。

请求参数

返回参数

返回示例

{"code":0,"refund_no":"202610250811223311","trade_no":"20261025075141…",
 "money":"12.34","reducemoney":"12.10","msg":"退款成功！退款金额¥12.34", …}

查一笔退款单。数据源是退款流水表，部分退款的每一笔都查得到。

请求参数

返回参数

关闭一笔未支付订单。先让上游关，上游关掉了本地才落关闭——不会本地一关了之， 否则上游二维码还活着，买家随后付成功就成了没人认领的收款。

请求参数

返回说明

成功 {"code":0,"msg":"订单关闭成功"}。业务失败回带签名的 {code:-1,msg}，三句话各管一档： 「当前订单不存在！」/「当前支付插件不支持关闭订单」（聚合类上游没有关单接口）/「该订单状态不支持关闭！」。

商户资料、余额与单量统计。V1 等价入口 GET /api.php?act=query（会原样回显明文 key，老脚本拿它做配置自检）。

请求参数

无业务参数，带公共鉴权参数即可。

返回参数

分页拉自己的订单。V1 等价入口 GET /api.php?act=orders（多回 count 与 total）。

请求参数

返回参数

code=0，data 为订单数组，元素字段与「订单查询」一致 （trade_no / out_trade_no / api_trade_no / type / pid / addtime / endtime / name / money / param / buyer / clientip / status / refundmoney）。

结算记录 = 提现申请到打款完成的那本账（手动申请与每日自动结算都写在这里）。只支持 V1 入口。

请求参数

返回参数（data 数组元素）

修改收款账户 POST /api.php?s=merchant/settle

每次修改写一条审计日志。成功回 {code:0,msg:"提现信息已保存",settle_type,settle_account,settle_name}。

用商户余额付给第三人。

请求参数

返回参数

请求参数

返回参数

请求参数同转账查询（biz_no）。当前出款为人工转账、没有上游电子回单， 接口直说：回 {code:-1,msg:"当前为人工转账，暂无电子回单，请凭打款流水号核对"}——不会回一个空链接让人以为系统坏了。 打款流水号用转账查询的 pay_order_no 拿。

返回参数

商户在商户中心「聚合收款」页生成一条固定链接和一张收款码海报：任何人打开都能自己输入金额付款， 钱直接进该商户余额，订单在商户中心正常出现（标为聚合收款）。链接自带签名商户令牌，别贴到不想收款的地方。

• 收款方名称可在商户中心自定义，改完立即生效；留空显示商户名称。
• 海报在浏览器里现画：三族模板 × 每族四套版式 × 九套配色，手机长按图片可存、也能打印贴柜台。
• 买家能用的支付方式与限额，和该商户正常下单一致。

平台收银台地址是 https://spay.dlam.cc/pay/{trade_no}：页面单没指定支付方式时买家落在这里， 页面持续查单、付完不用手动刷新；它也是 payurl 的兜底值，可以直接发给买家。

1. 服务器时间已同步（V2 偏差超 300 秒直接拒单）。
2. 签名串剔除了 sign、sign_type 和空值，参数按 key 升序，值未编码。
3. notify_url 公网可达且用 HTTPS，且不会因重复通知重复发货。
4. 通知里校验签名、pid、金额与订单号，成功只回 success。
5. 下单失败按 msg 那句中文提示买家，而不是笼统一句「支付失败」。
6. 掉单兜底：定时查 pay/query（或 V1 act=order），别只等通知。
7. 退款按「上限 = 入账金额」设计，全额退的差额自己补。
8. 密钥只在服务端，前端页面与 App 里都不出现。
9. （V3）确认金额单位是分：下单 1 元传 100，不是 "1.00"。
10. （V3）写接口带 Idempotency-Key，超时后用同一个 key、同一个请求体重试；40901 先查单再决定重下。
11. （V3）失败判 error_code 与 HTTP 状态码，不要判 message 的中文。
12. （V3）排障记下 request_id，找平台时报这一个号。

接口疑问请带上 trade_no 来问，比发截图快。

三种语言的签名与验签参考实现，复制即可跑。签名拼串规则见「签名规则」一节。

PHP（MD5 下单 + 验回调）

function sign_content(array $p): string {
    unset($p['sign'], $p['sign_type']);
    $p = array_filter($p, fn($v) => trim((string)$v) !== '');
    ksort($p);
    $s = '';
    foreach ($p as $k => $v) $s .= $k . '=' . $v . '&';
    return rtrim($s, '&');
}
$params = ['pid'=>1001,'type'=>'alipay','out_trade_no'=>'202610250001',
    'notify_url'=>'https://your.site/pay/notify','return_url'=>'https://your.site/order/1',
    'name'=>'VIP会员','money'=>'12.34','sign_type'=>'MD5'];
$params['sign'] = md5(sign_content($params) . $key);

// 回调验签（notify.php）
$ok = $_GET['sign'] === md5(sign_content($_GET) . $key)
   && $_GET['trade_status'] === 'TRADE_SUCCESS'
   && $_GET['pid'] == $pid && $_GET['money'] == $local_amount;
if ($ok && !already_paid($_GET['out_trade_no'])) { deliver($_GET['out_trade_no']); }
exit('success');

Go（V2 RSA 下单）

func signContent(p map[string]string) string {
    keys := make([]string, 0, len(p))
    for k, v := range p {
        if k == "sign" || k == "sign_type" || strings.TrimSpace(v) == "" { continue }
        keys = append(keys, k)
    }
    sort.Strings(keys)
    var b strings.Builder
    for i, k := range keys {
        if i > 0 { b.WriteByte('&') }
        b.WriteString(k + "=" + p[k])
    }
    return b.String()
}
h := sha256.Sum256([]byte(signContent(p)))
sig, _ := rsa.SignPKCS1v15(rand.Reader, priv, crypto.SHA256, h[:])
p["sign"] = base64.StdEncoding.EncodeToString(sig)
// POST 表单到 API + "/api.php?s=pay/create"

PHP（V3 签名与下单）

$appId = 'app_6f1c2d3e4a5b6c7d';   // 接入号
$appSecret = 'spayv3_...';             // 它对应的 AppSecret
$base = 'https://pay.your-site.com';

$body = json_encode([
    'out_trade_no' => 'P202610250001', 'amount' => 1234,   // 分
    'subject' => 'VIP会员', 'pay_type' => 'alipay',
    'notify_url' => 'https://your.site/pay/notify',
], JSON_UNESCAPED_UNICODE);                                  // 签完名就原样发出去，别再动它
$ts = (string) time();
$nonce = 'n-' . bin2hex(random_bytes(8));
$content = "v3.$ts\n$nonce\n" . hash('sha256', $body);
$sign = hash_hmac('sha256', $content, $appSecret);

$ch = curl_init($base . '/v3/pay/create');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_POSTFIELDS => $body,
 CURLOPT_HTTPHEADER => ["Content-Type: application/json", "X-Spay-App-Id: $appId",
   "X-Spay-Timestamp: $ts", "X-Spay-Nonce: $nonce", "X-Spay-Sign: $sign",
   "Idempotency-Key: $uuid"],
 CURLOPT_RETURNTRANSFER => true]);
$res = json_decode(curl_exec($ch), true);
if ($res['code'] !== 0) { /* 判 $res['error_code']，别判 $res['message'] */ }

JavaScript（验 V2 应答与 RSA 通知）

// 用平台公钥验应答/通知；timestamp 参与拼串
const ok = crypto.verify(
  'SHA256', Buffer.from(signContent(body)),
  crypto.createPublicKey(platformPubPem),
  Buffer.from(body.sign, 'base64'));
// body 为应答或通知的原始字段（去掉 sign 本身不参与拼串，sign_type 同样剔除）