开放 API v1 · 接入说明

开放 API 面向你自己的业务后端:JSON 请求、HMAC-SHA256 签名、时间戳 + nonce 防重放,支付成功后以 JSON POST 回调。易支付兼容接口仍然保留,两套可同时使用。

基本约定

项目	说明
请求地址	POST {站点地址}/api/v1/... 全部为 POST
请求体	Content-Type: application/json,UTF-8;无参数接口可传 {}
金额	单位元,字符串,最多两位小数,如 "9.90"(也接受数字)
时间	Unix 时间戳(秒)
返回	{"code":0,"msg":"success","data":{...}},code≠0 表示失败

鉴权请求头

请求头	说明
X-AiPay-Pid	商户 ID
X-AiPay-Timestamp	当前 Unix 秒,与服务器相差不超过 300 秒
X-AiPay-Nonce	8-64 位随机串(字母/数字/_/-),每次请求不同
X-AiPay-Signature	签名,见下

签名算法

canonical = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + BODY
signature = hex( HMAC_SHA256( 商户密钥, canonical ) )   // 小写十六进制

示例: POST /api/v1/order/query
canonical = "POST\n/api/v1/order/query\n1760320000\nab12cd34ef56\n{\"out_trade_no\":\"A1001\"}"

PATH 不含域名和查询串;BODY 为实际发送的原始字节,签名后不要再重新序列化。商户密钥在「商户中心 → 商户信息」查看。

错误码

code	HTTP	含义
40001	400	参数错误
40101 / 40102	401	缺少鉴权头 / 签名错误
40103 / 40104	401	时间戳过期 / nonce 重复(重放)
40301	403	商户被封禁
40401	404	订单或接口不存在
40901	409	订单状态不允许该操作(如重复支付、关闭已支付订单)
42901	429	请求过于频繁(单 IP 每分钟 120 次)
50001	500	服务器内部错误

联调

POST /api/v1/ping 请求体 {},签名正确时返回 {"pid":...,"server_time":...}。仓库 sdk/ 目录提供 Python / PHP / Node.js / Go 客户端,均已封装签名、回调验签与全部接口。