易支付对接指南

服务根地址：https://pay.strcpy.cn。当前只支持支付宝（alipay）。

本页与 AI 对接 Skill 均无需登录。商户 PID、商户 KEY 从管理员提供的网站接入信息中获取，每个网站使用独立凭据。商户 KEY 用于易支付签名，与支付宝应用私钥不同。

1. 配置接入网站

管理员在「接入网站」创建网站，选择收款应用，登记通知与返回地址。接入方填写：

通知与返回地址登记时不带查询参数。实际请求可带查询参数，但协议、域名、端口、路径必须与登记值一致；路径末尾斜杠也要一致。通知必须公网可达，网关不跟随通知重定向，不向本机、内网及保留地址发送通知。

NewAPI

在 NewAPI 的易支付设置中填写以上根地址、PID、KEY，并启用支付宝。后台网站类型选择 NewAPI。

常用通知路径：/api/user/epay/notify、/api/subscription/epay/notify；订阅返回路径：/api/subscription/epay/return。充值返回路径因版本而异，例如 /console/log 或 /usage-logs。以实际版本下单请求里的完整地址为准，在支付后台登记；不要照搬其他站点的域名。

Sub2API

支付服务商选择 EasyPay，API 地址填写根地址，PID 和 PKey 填写网站凭据，支付方式选择 alipay，通道 ID 留空。本后台网站类型选择「通用易支付」。常用通知路径为 /api/v1/payment/webhook/easypay，返回路径为 /payment/result。

Sub2API 返回地址中的 order_id、out_trade_no、resume_token、status 查询参数在签名时原样保留。返回链接带有 status=success 不代表网关已确认付款，接入方仍需验签并查单或处理异步通知。

2. 接口与请求格式

三个接口同时支持 /xpay/epay/ 前缀，例如 /xpay/epay/submit.php。POST 下单使用 Content-Type: application/x-www-form-urlencoded；不接受 JSON 下单。POST 参数放在请求体中，不混入 URL 查询参数。相同一级参数不得重复。

下单参数

金额不要使用浮点数计算后再直接拼接。有效期截止时间按分钟向上取整，可能额外增加不足 60 秒。同一网站订单号重复提交返回 HTTP 409；发生超时先查原订单，不要直接生成另一笔订单。

3. MD5 签名与字段扩展

1. 取表单解码一次后的所有一级字段，排除一级 sign、sign_type 及值为空字符串的字段。
2. 按字段名升序排列，拼接为 key=value&key=value，字段名大小写保留。
3. 在拼接字符串末尾直接追加商户 KEY，不加 &key=。
4. 对 UTF-8 字节计算 MD5，输出小写十六进制。
5. 将签名加入参数后，再用标准表单编码生成请求体或查询字符串。

一级新增字段自动参与签名。URL、JSON 或 N 层嵌套数据作为一个完整字符串参与签名，不递归展开，不重新排序，也不再次解码。不要只签固定的几个字段；验签也必须包含收到的所有非空一级字段。

V1 对原始值使用 & 拼接，存在边界歧义。网关会拒绝值中 &字段名= 与同名保留字段取值冲突的请求。保留字段为 pid、type、money、out_trade_no、trade_no、trade_status、name、param、notify_url、return_url、expiry_minutes、sign、sign_type（边界检查不区分大小写）。普通 R&D、uid=5&plan=pro、非保留字段或重复值相同的合法参数可以使用。Sub2API 返回地址重复相同的 out_trade_no 可以通过。

回跳参数也不能与网关支付字段冲突。对于有歧义的业务数据，优先改用结构化 JSON 放入 param，或调整字段名；若必须对内层值编码，接入方需约定同一编码方式，不能对整个请求反复编码。

Python 下单示例

以下示例只生成请求体，不创建订单。将环境变量设为该网站实际配置后，将输出通过服务端 POST 发给 /mapi.php。PAY_RETURN_URL 可带接入网站需要的查询参数。

import hashlib
import os
from urllib.parse import urlencode

def epay_sign(fields, key):
    pairs = [f"{k}={fields[k]}" for k in sorted(fields)
             if k not in ("sign", "sign_type") and fields[k] != ""]
    return hashlib.md5(("&".join(pairs) + key).encode("utf-8")).hexdigest()

fields = {
    "pid": os.environ["PAY_PID"],
    "type": "alipay",
    "out_trade_no": os.environ["PAY_ORDER_NO"],
    "name": "API 额度充值",
    "money": "10.06",
    "notify_url": os.environ["PAY_NOTIFY_URL"],
    "return_url": os.environ["PAY_RETURN_URL"],
    "param": '{"user_id":"42","plan":"pro"}',
    "sign_type": "MD5",
}
fields["sign"] = epay_sign(fields, os.environ["PAY_KEY"])
print(urlencode(fields))

下单响应

/mapi.php 成功：

{"code":1,"msg":"success","trade_no":"CPexample","payurl":"https://pay.strcpy.cn/checkout/CPexample","money":"10.06"}

跳转用户到 payurl 完成付款。trade_no 是网关支付订单号，并非支付宝交易号。获得链接仅代表网关创建了待支付订单。

下单失败返回非 2xx HTTP 状态，响应体为文本。常见情况：400 参数、金额或回调地址错误；401 PID 或签名无效；409 订单重复或收款应用不可用；415 下单 POST 使用了错误 Content-Type。接入方先判断 HTTP 状态，再解析成功 JSON。

4. 异步通知与付款后返回

网关确认付款后，POST 表单到订单原始 notify_url，包含 pid、trade_no、out_trade_no、type、name、money、trade_status=TRADE_SUCCESS、sign_type=MD5、sign；非空 param 也包含在内。

接入网站按以下顺序处理：

1. 拒绝重复一级参数，按本站 KEY 验证全部一级字段签名。
2. 验证 PID、网站订单号、金额、支付方式和 TRADE_SUCCESS；金额按整数分比较。
3. 在数据库事务内将订单标记为已支付并完成余额或订阅更新。以订单号做唯一约束，重复通知不重复入账。
4. 事务成功提交后返回 HTTP 200，响应体为纯文本 success。已处理的合法重复通知也返回 success。

通知失败会自动重试，间隔逐步增加；管理员也可手动重试。不要在写入失败时返回 success。

用户回跳为 GET，网关会将付款参数与原 return_url 查询参数合并并重新签名。验签必须包含所有合并后的非空一级字段。浏览器跳转本身不能证明付款，也不能仅靠 status=success、前端状态或收银台链接给用户入账。

付款状态与通知状态独立：已付款但通知失败仍是已付款。异步通知只发送付款结果，不提供退款扣回事件；退款需人工核对，业务系统自行处理退款后的余额和权益。

5. 订单查询

服务端 POST 到 https://pay.strcpy.cn/api.php，使用表单字段：

成功返回 code=1、msg、pid、trade_no、out_trade_no、name、money、type、status、trade_status。只查询当前 PID 的订单。此接口返回网关已记录的付款状态，不实时调用支付宝。

查单业务错误使用 HTTP 200、code=-1、msg。因此 HTTP 200 不等于业务成功。退款待核对订单也返回 code=-1（订单存在退款，请人工核对），不能当作可再次发货的已支付订单。没有退款、提现或修改订单接口。

6. 联调与常见问题

• 在管理员 Playground 模拟下单，核对请求参数、签名、响应、收银台和通知结果。首次真实付款需接入方按其测试安排完成。
• “易支付签名无效”：检查 PID / KEY 是否属于同一网站，是否签了全部非空一级字段，是否在签名后才进行表单编码。
• “通知或返回地址未在网站配置中登记”：对比实际协议、域名、端口、路径，去掉查询参数后与后台登记值逐项核对。
• 已付款但网站未入账：查看独立的通知状态，检查接入网站验签、事务及纯文本 success 响应，再重试通知。
• 请求超时或订单重复：用原 out_trade_no 查单，不重新发起另一笔充值。
• “参数边界”错误：检查字段值中的 &保留字段=，不要更改已经签名的值，参照第 3 节调整内层数据。

本页描述当前服务实现。接入资料中的网站凭据、账号权限及支付宝应用资料仍由管理员管理，公开文档不包含它们。