开发文档
本文档说明如何接入 柯达集团 的收款接口:发起支付、接收支付结果、查询订单和申请退款。接口使用 MD5 签名,文中的示例代码都实际运行验证过。
接口一览
| 用途 | 路径 | 方式 | 身份校验 |
|---|---|---|---|
| 页面跳转支付 | /submit.php | GET / POST | 签名 |
| API 接口支付 | /mapi.php | POST | 签名 |
| 支付结果通知 | 你下单时传的 notify_url | GET(平台请求你) | 签名,由你校验 |
| 单笔订单查询 | /api.php?act=order | GET | pid + key |
| 批量订单查询 | /api.php?act=orders | GET | pid + key |
| 商户信息查询 | /api.php?act=query | GET | pid + key |
| 结算记录查询 | /api.php?act=settle | GET | pid + key |
| 申请退款 | /api.php?act=refund | POST | pid + key |
通用约定
| 接口地址 | 由平台单独提供,本文写作 <对接地址>。例如对接地址是 https://example.com(末尾不带 /),页面跳转支付的完整地址就是 https://example.com/submit.php。example.com 只是示例,不能用于生产。 |
| 请求格式 | 表单,即 application/x-www-form-urlencoded。接口不接收 JSON 请求体。 |
| 返回格式 | JSON。页面跳转支付例外,它直接输出支付页面。 |
| 字符编码 | UTF-8 |
| 金额 | 单位是元,最多两位小数,例如 100.00。平台单笔上限 10000 元;各支付方式另有自己的金额范围,见商户后台「测试支付」页。 |
| 签名 | MD5,32 位小写,规则见 签名规则。 |
对接凭证
对接需要两样东西,都在商户后台「API 凭证」页:pid(商户 ID)和 key(商户密钥)。
拿到密钥就能以你的名义下单、查询和申请退款。不要把它写进网页、App 或小程序的前端代码,也不要通过聊天工具发送。怀疑泄露时,在「API 凭证」页重置。
一个商户下可以有多个应用(商户后台「API 凭证」页的应用管理)。下单时 pid 也可以填应用的 appid,签名用该应用的密钥;应用没有单独重置过密钥时,用的就是商户密钥。查询和退款接口只认商户 ID 与商户密钥。
接入流程
签名规则
下单请求要带签名,平台发给你的支付结果通知也带签名,两边用的是同一套规则:
- 取出全部参数,去掉
sign和sign_type,再去掉值为空的参数。 - 按参数名的 ASCII 码从小到大排序。
- 写成
参数名=值,用&连接。值用原始内容,不要做 URL 编码。 - 在末尾直接接上商户密钥(中间不加
&,也不加key=),对整串内容计算 MD5,取 32 位小写。
算一遍
假设商户密钥是 0123456789abcdefABCDEF0123456789,要提交这些参数:
pid=1001
type=alipay
out_trade_no=20261117153000001
notify_url=https://shop.example.com/pay/notify
return_url=https://shop.example.com/pay/return
name=VIP会员
money=100.00排序并连接后,待签名字符串是:
money=100.00&name=VIP会员¬ify_url=https://shop.example.com/pay/notify&out_trade_no=20261117153000001&pid=1001&return_url=https://shop.example.com/pay/return&type=alipay在它后面接上密钥再算 MD5,得到的 sign 是 a8177dededc32736ebc5448dba323bcc。你的代码用同样的参数和密钥算出这个值,就说明签名实现是对的。
参考实现
/**
* 生成签名。$params 为全部请求参数,$key 为商户密钥。
*/
function make_sign(array $params, string $key): string
{
unset($params['sign'], $params['sign_type']);
ksort($params);
$parts = [];
foreach ($params as $name => $value) {
// 空值不参与签名
if ($value === null || is_array($value) || trim((string)$value) === '') continue;
$parts[] = $name . '=' . $value;
}
return md5(implode('&', $parts) . $key);
}import hashlib
def make_sign(params: dict, key: str) -> str:
"""生成签名。params 为全部请求参数,key 为商户密钥。"""
parts = []
for name in sorted(params):
value = params[name]
# sign、sign_type 和空值不参与签名
if name in ("sign", "sign_type") or value is None or str(value).strip() == "":
continue
parts.append(f"{name}={value}")
return hashlib.md5(("&".join(parts) + key).encode("utf-8")).hexdigest()const crypto = require('crypto');
/** 生成签名。params 为全部请求参数,key 为商户密钥。 */
function makeSign(params, key) {
const text = Object.keys(params)
// sign、sign_type 和空值不参与签名
.filter((name) => name !== 'sign' && name !== 'sign_type')
.filter((name) => params[name] !== null && params[name] !== undefined && String(params[name]).trim() !== '')
.sort()
.map((name) => `${name}=${params[name]}`)
.join('&');
return crypto.createHash('md5').update(text + key, 'utf8').digest('hex');
}import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Map;
import java.util.TreeMap;
public class PaySign {
/** 生成签名。params 为全部请求参数,key 为商户密钥。 */
public static String makeSign(Map<String, String> params, String key) throws Exception {
StringBuilder text = new StringBuilder();
for (Map.Entry<String, String> entry : new TreeMap<>(params).entrySet()) {
String name = entry.getKey();
String value = entry.getValue();
// sign、sign_type 和空值不参与签名
if (name.equals("sign") || name.equals("sign_type") || value == null || value.trim().isEmpty()) continue;
if (text.length() > 0) text.append('&');
text.append(name).append('=').append(value);
}
byte[] digest = MessageDigest.getInstance("MD5")
.digest((text + key).getBytes(StandardCharsets.UTF_8));
StringBuilder hex = new StringBuilder();
for (byte b : digest) hex.append(String.format("%02x", b));
return hex.toString();
}
}- 把
sign、sign_type或空值参数也拼进去了。 - 对值做了 URL 编码,例如把
https://写成https%3A%2F%2F。 - 密钥前面多加了
&或&key=。 - 提交时又改动了参数,例如签名用
100.00,实际提交100。
签名调试工具
把参数和密钥填进来,可以看到待签名字符串和签名结果,方便和你的程序逐步对比。计算只在你的浏览器里进行,不会发送到任何服务器。
值里本身带有 & 时(例如通知地址带查询参数),请用每行一个的写法。参数里如果带了 sign,工具会顺便告诉你它和计算结果是否一致。
页面跳转支付
适合网站收银。你把用户的浏览器带到这个地址,用户在平台的支付页完成付款,付完后回到你的页面。
<对接地址>/submit.php签名校验请求参数
| 参数 | 必填 | 说明 |
|---|---|---|
pid | 必填 | 商户 ID,或应用的 appid。 |
type | 可选 | 支付方式,取值见 支付方式。不传则进入收银台,由用户自己选。 |
out_trade_no | 必填 | 你系统里的订单号,同一商户内不能重复。只能包含字母、数字和 . _ - |。 |
notify_url | 必填 | 接收 支付结果通知 的地址,必须能从公网访问。 |
return_url | 必填 | 用户付完后浏览器跳回的页面,只用于展示结果。 |
name | 必填 | 商品名称,超过 127 字节会被截断。 |
money | 必填 | 订单金额,单位元,最多两位小数。 |
param | 可选 | 自定义内容,通知时原样带回。 |
sign | 必填 | 按 签名规则 计算的签名。 |
sign_type | 可选 | 固定填 MD5,不参与签名。 |
行为说明
- 参数无误时浏览器直接进入支付页;有问题时显示一个错误提示页,不是 JSON,所以这个接口只能由浏览器访问,不要在服务器端请求它。
- 同一个
out_trade_no可以重复发起:10 天内参数完全一致时继续支付原来那笔订单,不会生成新订单。金额、商品名、通知地址、跳转地址或param有任何变化都会被拒绝,这时请换一个订单号。已经付过款的订单不能再发起。 - 付款完成后,浏览器会带着和通知相同的参数回到
return_url。这次跳转只用来给用户看结果,订单状态以 支付结果通知 为准。
示例
示例里的 make_sign / makeSign / PaySign.makeSign 就是上面 签名规则 里的参考实现。示例用到的语法需要 PHP 7.0、Python 3.6、Node.js 18、Java 11 或更高版本。
$apiBase = '<对接地址>'; // 平台单独提供,末尾不带 /
$key = '你的商户密钥';
$params = [
'pid' => '1001',
'type' => 'alipay', // 不传则进入收银台,由用户自己选
'out_trade_no' => date('YmdHis') . mt_rand(1000, 9999),
'notify_url' => 'https://你的域名/pay/notify',
'return_url' => 'https://你的域名/pay/return',
'name' => 'VIP会员',
'money' => '100.00',
];
$params['sign'] = make_sign($params, $key);
$params['sign_type'] = 'MD5';
// 输出一个自动提交的表单,用户的浏览器随即跳转到支付页
echo '<form id="pay" action="' . $apiBase . '/submit.php" method="post">';
foreach ($params as $name => $value) {
echo '<input type="hidden" name="' . $name . '" value="' . htmlspecialchars($value, ENT_QUOTES) . '">';
}
echo '</form><script>document.getElementById("pay").submit();</script>';import time
import urllib.parse
API_BASE = "<对接地址>" # 平台单独提供,末尾不带 /
KEY = "你的商户密钥"
params = {
"pid": "1001",
"type": "alipay", # 不传则进入收银台,由用户自己选
"out_trade_no": time.strftime("%Y%m%d%H%M%S") + "0001",
"notify_url": "https://你的域名/pay/notify",
"return_url": "https://你的域名/pay/return",
"name": "VIP会员",
"money": "100.00",
}
params["sign"] = make_sign(params, KEY)
params["sign_type"] = "MD5"
# 让用户的浏览器跳转到这个地址(例如 Flask 里 return redirect(pay_url))
pay_url = API_BASE + "/submit.php?" + urllib.parse.urlencode(params)
print(pay_url)const API_BASE = '<对接地址>'; // 平台单独提供,末尾不带 /
const KEY = '你的商户密钥';
const params = {
pid: '1001',
type: 'alipay', // 不传则进入收银台,由用户自己选
out_trade_no: `${Date.now()}0001`,
notify_url: 'https://你的域名/pay/notify',
return_url: 'https://你的域名/pay/return',
name: 'VIP会员',
money: '100.00',
};
params.sign = makeSign(params, KEY);
params.sign_type = 'MD5';
// 让用户的浏览器跳转到这个地址(例如 Express 里 res.redirect(payUrl))
const payUrl = `${API_BASE}/submit.php?${new URLSearchParams(params)}`;
console.log(payUrl);import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.StringJoiner;
public class SubmitDemo {
static final String API_BASE = "<对接地址>"; // 平台单独提供,末尾不带 /
static final String KEY = "你的商户密钥";
public static void main(String[] args) throws Exception {
Map<String, String> params = new LinkedHashMap<>();
params.put("pid", "1001");
params.put("type", "alipay"); // 不传则进入收银台,由用户自己选
params.put("out_trade_no", System.currentTimeMillis() + "0001");
params.put("notify_url", "https://你的域名/pay/notify");
params.put("return_url", "https://你的域名/pay/return");
params.put("name", "VIP会员");
params.put("money", "100.00");
params.put("sign", PaySign.makeSign(params, KEY));
params.put("sign_type", "MD5");
StringJoiner query = new StringJoiner("&");
for (Map.Entry<String, String> entry : params.entrySet()) {
query.add(entry.getKey() + "=" + URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}
// 让用户的浏览器跳转到这个地址(例如 Spring MVC 里 return "redirect:" + payUrl)
String payUrl = API_BASE + "/submit.php?" + query;
System.out.println(payUrl);
}
}API 接口支付
适合 App、小程序后端或想自己控制支付界面的网站。由你的服务器请求这个接口,拿到支付链接或二维码内容,再展示给用户。
<对接地址>/mapi.php签名校验请求参数
| 参数 | 必填 | 说明 |
|---|---|---|
pid | 必填 | 商户 ID,或应用的 appid。 |
type | 必填 | 支付方式,取值见 支付方式。 |
out_trade_no | 必填 | 你系统里的订单号,规则同 页面跳转支付。 |
notify_url | 必填 | 接收 支付结果通知 的地址。 |
return_url | 可选 | 用户付完后浏览器跳回的页面。 |
name | 必填 | 商品名称,超过 127 字节会被截断。 |
money | 必填 | 订单金额,单位元,最多两位小数。 |
clientip | 必填 | 付款用户的 IP 地址,不是你服务器的 IP。 |
device | 可选 | 用户所在的环境,默认 pc,取值见 设备类型。 |
param | 可选 | 自定义内容,通知时原样带回。 |
sign | 必填 | 按 签名规则 计算的签名。 |
sign_type | 可选 | 固定填 MD5,不参与签名。 |
返回结果
| 字段 | 说明 |
|---|---|
code | 1 表示下单成功,其它值都是失败,含义见 返回码。 |
msg | 失败原因,成功时没有这个字段。 |
trade_no | 平台订单号。请保存下来,查单和对账都用得到。 |
payurl | 支付链接,让用户在浏览器里打开。 |
qrcode | 二维码内容,由你生成二维码图片给用户扫。 |
urlscheme | App 唤起链接,在手机上直接跳转。 |
payurl、qrcode、urlscheme 每次只会返回其中一个,返回哪个取决于支付方式和 device,按实际收到的字段处理即可。指定的支付方式暂时不可用时,会返回一个收银台的 payurl,用户可以在那里改选其它方式。
{
"code": 1,
"trade_no": "2026111715300112345",
"payurl": "<对接地址>/pay/submit/2026111715300112345/"
}{
"code": -3,
"msg": "MD5签名校验失败"
}同一个 out_trade_no 重复请求时的处理方式,和 页面跳转支付 一样。
示例
$apiBase = '<对接地址>'; // 平台单独提供,末尾不带 /
$key = '你的商户密钥';
$params = [
'pid' => '1001',
'type' => 'alipay',
'out_trade_no' => date('YmdHis') . mt_rand(1000, 9999),
'notify_url' => 'https://你的域名/pay/notify',
'return_url' => 'https://你的域名/pay/return',
'name' => 'VIP会员',
'money' => '100.00',
'clientip' => $_SERVER['REMOTE_ADDR'], // 付款用户的 IP,不是你服务器的 IP
'device' => 'mobile',
];
$params['sign'] = make_sign($params, $key);
$params['sign_type'] = 'MD5';
$ch = curl_init($apiBase . '/mapi.php');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($params),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
]);
$result = json_decode((string)curl_exec($ch), true);
if (isset($result['code']) && $result['code'] == 1) {
// 先保存 $result['trade_no'],再按返回的字段展示给用户
if (!empty($result['payurl'])) {
// 支付链接:让用户打开
} elseif (!empty($result['qrcode'])) {
// 二维码内容:生成二维码图片让用户扫
} elseif (!empty($result['urlscheme'])) {
// App 唤起链接:在手机端直接跳转
}
} else {
// 下单失败,原因在 $result['msg']
}import json
import time
import urllib.parse
import urllib.request
API_BASE = "<对接地址>" # 平台单独提供,末尾不带 /
KEY = "你的商户密钥"
def create_order(client_ip: str) -> dict:
params = {
"pid": "1001",
"type": "alipay",
"out_trade_no": time.strftime("%Y%m%d%H%M%S") + "0001",
"notify_url": "https://你的域名/pay/notify",
"return_url": "https://你的域名/pay/return",
"name": "VIP会员",
"money": "100.00",
"clientip": client_ip, # 付款用户的 IP,不是你服务器的 IP
"device": "mobile",
}
params["sign"] = make_sign(params, KEY)
params["sign_type"] = "MD5"
request = urllib.request.Request(
API_BASE + "/mapi.php",
data=urllib.parse.urlencode(params).encode("utf-8"),
)
with urllib.request.urlopen(request, timeout=15) as response:
result = json.loads(response.read().decode("utf-8"))
if result.get("code") != 1:
raise RuntimeError("下单失败:" + str(result.get("msg")))
# 先保存 result["trade_no"],再按返回的字段展示给用户:
# payurl 支付链接 / qrcode 二维码内容 / urlscheme App 唤起链接
return resultconst API_BASE = '<对接地址>'; // 平台单独提供,末尾不带 /
const KEY = '你的商户密钥';
async function createOrder(clientIp) {
const params = {
pid: '1001',
type: 'alipay',
out_trade_no: `${Date.now()}0001`,
notify_url: 'https://你的域名/pay/notify',
return_url: 'https://你的域名/pay/return',
name: 'VIP会员',
money: '100.00',
clientip: clientIp, // 付款用户的 IP,不是你服务器的 IP
device: 'mobile',
};
params.sign = makeSign(params, KEY);
params.sign_type = 'MD5';
// Node.js 18 及以上自带 fetch;body 传 URLSearchParams 会按表单格式提交
const response = await fetch(`${API_BASE}/mapi.php`, {
method: 'POST',
body: new URLSearchParams(params),
signal: AbortSignal.timeout(15000),
});
const result = await response.json();
if (result.code !== 1) throw new Error(`下单失败:${result.msg}`);
// 先保存 result.trade_no,再按返回的字段展示给用户:
// payurl 支付链接 / qrcode 二维码内容 / urlscheme App 唤起链接
return result;
}import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.StringJoiner;
public class MapiDemo {
static final String API_BASE = "<对接地址>"; // 平台单独提供,末尾不带 /
static final String KEY = "你的商户密钥";
/** 返回接口的 JSON 字符串;clientIp 是付款用户的 IP,不是你服务器的 IP。 */
public static String createOrder(String clientIp) throws Exception {
Map<String, String> params = new LinkedHashMap<>();
params.put("pid", "1001");
params.put("type", "alipay");
params.put("out_trade_no", System.currentTimeMillis() + "0001");
params.put("notify_url", "https://你的域名/pay/notify");
params.put("return_url", "https://你的域名/pay/return");
params.put("name", "VIP会员");
params.put("money", "100.00");
params.put("clientip", clientIp);
params.put("device", "mobile");
params.put("sign", PaySign.makeSign(params, KEY));
params.put("sign_type", "MD5");
StringJoiner form = new StringJoiner("&");
for (Map.Entry<String, String> entry : params.entrySet()) {
form.add(entry.getKey() + "=" + URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}
HttpRequest request = HttpRequest.newBuilder(URI.create(API_BASE + "/mapi.php"))
.timeout(Duration.ofSeconds(15))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form.toString()))
.build();
// 用项目里的 JSON 库(Jackson、Gson 等)解析返回值:
// code 为 1 表示成功,先保存 trade_no,再按 payurl / qrcode / urlscheme 展示给用户
return HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString()).body();
}
}支付结果通知
用户付款成功后,平台会用 GET 方式请求你下单时传的 notify_url,参数接在地址后面。这是判断订单已付款的唯一可靠依据,用户跳回 return_url 不能作为入账依据。
通知参数
| 参数 | 说明 |
|---|---|
pid | 下单时使用的 pid。 |
trade_no | 平台订单号。 |
out_trade_no | 你的订单号。 |
type | 实际使用的支付方式,例如 alipay。 |
name | 固定为 product,不是下单时的商品名称,请不要依赖它。 |
money | 订单金额,单位元。末尾的 0 会被省略:下单时的 100.00 在这里是 100,9.90 是 9.9。 |
trade_status | 固定为 TRADE_SUCCESS,表示支付成功。 |
param | 下单时传的 param;下单时没传就没有这个参数。 |
sign | 签名,校验方法见下。 |
sign_type | 固定为 MD5。 |
GET https://shop.example.com/pay/notify?pid=1001&trade_no=2026111715300112345&out_trade_no=20261117153000001&type=alipay&name=product&money=100&trade_status=TRADE_SUCCESS&sign=2e25d1100cb6e20310a5f1b3bc6b662d&sign_type=MD5上面这条示例沿用了 签名规则 里的密钥,可以拿来测试你的验签代码。
你需要做的事
- 验签。用收到的参数按 签名规则 重新计算,和
sign一致才继续。必须用收到的原始值计算,不要先把100改写成100.00。 - 核对订单。按
out_trade_no找到你的订单,确认trade_status是TRADE_SUCCESS,并且金额和订单一致(按数值比较)。 - 幂等处理。同一笔订单的通知可能收到多次。订单已经是已支付时,直接回复成功,不要重复发货。
- 回复
success。处理完成后返回 HTTP 200,响应内容只有success这七个字母。
- 必须在 10 秒内返回 HTTP 200,并且响应内容只有
success。带上 HTML、调试输出或其它文字都可能被判定为失败。 - 通知地址如果会重定向(例如从 http 跳到 https),平台最多跟随 5 次。建议直接填最终地址。
- 判定失败后,平台大约在 1 分钟、3 分钟、20 分钟、1 小时后各重试一次,共 4 次。之后不再自动重试。
- 每次通知的时间、HTTP 状态码和你返回的内容,都可以在商户后台「订单明细」的订单详情里看到。排查完问题后,可以在那里手动重新发送。
示例
$key = '你的商户密钥';
$params = $_GET; // 平台用 GET 请求,直接拿收到的原始参数验签
// 1. 验签
if (empty($params['sign']) || !hash_equals(make_sign($params, $key), (string)$params['sign'])) {
exit('sign error');
}
// 2. 只处理支付成功的通知
if (($params['trade_status'] ?? '') !== 'TRADE_SUCCESS') {
exit('fail');
}
// 3. 按 $params['out_trade_no'] 找到本地订单,核对金额。
// 通知里的金额可能是 100 而不是 100.00,要按数值比较:
// if ((int)round($params['money'] * 100) !== (int)round($order['money'] * 100)) exit('money error');
// 4. 幂等:订单已经是“已支付”就跳过;否则标记为已支付并发货
// 5. 全部处理完再输出,而且只输出 success
echo 'success';import hmac
KEY = "你的商户密钥"
def handle_notify(params: dict) -> str:
"""params 是通知地址收到的全部 GET 参数(已解码)。返回值原样作为响应体输出。"""
# 1. 验签
expected = make_sign(params, KEY).encode("utf-8")
if not hmac.compare_digest(expected, str(params.get("sign", "")).encode("utf-8")):
return "sign error"
# 2. 只处理支付成功的通知
if params.get("trade_status") != "TRADE_SUCCESS":
return "fail"
# 3. 按 params["out_trade_no"] 找到本地订单,核对金额。
# 通知里的金额可能是 100 而不是 100.00,要按数值比较:
# if Decimal(params["money"]) != Decimal(order_money): return "money error"
# 4. 幂等:订单已经是“已支付”就跳过;否则标记为已支付并发货
# 5. 全部处理完再返回,而且只返回 success
return "success"
# Flask 接入示例:
# @app.route("/pay/notify")
# def pay_notify():
# return handle_notify(request.args.to_dict()), 200, {"Content-Type": "text/plain"}// 需要上文「签名规则」里的 crypto 和 makeSign
const NOTIFY_KEY = '你的商户密钥';
/** query 是通知地址收到的全部 GET 参数(已解码)。返回值原样作为响应体输出。 */
function handleNotify(query) {
// 1. 验签
const expected = Buffer.from(makeSign(query, NOTIFY_KEY));
const received = Buffer.from(String(query.sign || ''));
if (expected.length !== received.length || !crypto.timingSafeEqual(expected, received)) {
return 'sign error';
}
// 2. 只处理支付成功的通知
if (query.trade_status !== 'TRADE_SUCCESS') return 'fail';
// 3. 按 query.out_trade_no 找到本地订单,核对金额。
// 通知里的金额可能是 100 而不是 100.00,要按数值比较:
// if (Math.round(Number(query.money) * 100) !== Math.round(Number(order.money) * 100)) return 'money error';
// 4. 幂等:订单已经是“已支付”就跳过;否则标记为已支付并发货
// 5. 全部处理完再返回,而且只返回 success
return 'success';
}
// Express 接入示例:
// app.get('/pay/notify', (req, res) => res.type('text/plain').send(handleNotify(req.query)));import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Map;
public class NotifyHandler {
static final String KEY = "你的商户密钥";
/** params 是通知地址收到的全部 GET 参数(已解码)。返回值原样作为响应体输出。 */
public static String handle(Map<String, String> params) throws Exception {
// 1. 验签
String received = params.getOrDefault("sign", "");
boolean signOk = MessageDigest.isEqual(
PaySign.makeSign(params, KEY).getBytes(StandardCharsets.UTF_8),
received.getBytes(StandardCharsets.UTF_8));
if (!signOk) return "sign error";
// 2. 只处理支付成功的通知
if (!"TRADE_SUCCESS".equals(params.get("trade_status"))) return "fail";
// 3. 按 params.get("out_trade_no") 找到本地订单,核对金额。
// 通知里的金额可能是 100 而不是 100.00,要按数值比较:
// if (new BigDecimal(params.get("money")).compareTo(orderMoney) != 0) return "money error";
// 4. 幂等:订单已经是“已支付”就跳过;否则标记为已支付并发货
// 5. 全部处理完再返回,而且只返回 success
return "success";
}
}
// Spring MVC 接入示例:
// @GetMapping(value = "/pay/notify", produces = "text/plain")
// public String payNotify(@RequestParam Map<String, String> params) throws Exception {
// return NotifyHandler.handle(params);
// }浏览器跳转 return_url
付款完成后,用户的浏览器会带着同样的参数跳到 return_url。你可以在这个页面里验签后展示“支付成功”,但不要在这里更新订单:用户可能中途关掉页面,这次跳转也不保证发生。付款完成超过 5 分钟后再打开支付页,会停留在平台的成功提示页,不再跳回你的网站。
支付方式与设备类型
支付方式(type)
下面是平台当前开放的支付方式。你的商户实际能用哪些、各自的金额范围是多少,以商户后台为准。
| type 取值 | 支付方式 |
|---|---|
alipay | 支付宝 |
wxpay | 微信支付 |
设备类型(device)
只有 API 接口支付 用得到。它告诉平台用户在什么环境里付款,平台据此返回合适的支付形式。
| device 取值 | 用户所在的环境 |
|---|---|
pc | 电脑浏览器(默认) |
mobile | 手机浏览器 |
wechat | 微信内置浏览器 |
alipay | 支付宝客户端 |
qq | 手机 QQ 内置浏览器 |
jump | 不区分环境,只要一个支付跳转链接(返回 payurl) |
单笔订单查询
主动查询一笔订单是否已付款。建议作为通知的补充:订单长时间没有收到通知时查一次。
<对接地址>/api.php?act=orderpid + key| 参数 | 必填 | 说明 |
|---|---|---|
pid | 必填 | 商户 ID。 |
key | 必填 | 商户密钥。 |
trade_no | 二选一 | 平台订单号。两个都传时以它为准。 |
out_trade_no | 你的订单号。 |
curl "<对接地址>/api.php?act=order&pid=1001&key=你的商户密钥&out_trade_no=20261117153000001"{
"code": 1,
"msg": "succ",
"trade_no": "2026111715300112345",
"out_trade_no": "20261117153000001",
"api_trade_no": "4200002611202611171234567890",
"bill_trade_no": null,
"type": "alipay",
"pid": 1001,
"addtime": "2026-11-17 15:30:01",
"endtime": "2026-11-17 15:30:42",
"name": "VIP会员",
"money": "100.00",
"param": null,
"buyer": null,
"status": 1,
"payurl": null
}| 字段 | 说明 |
|---|---|
status | 订单状态:0 未支付,1 已支付,2 已退款(包括只退了一部分),3 已冻结。 |
trade_no / out_trade_no | 平台订单号 / 你的订单号。 |
api_trade_no | 支付渠道一侧的订单号,没有时为空。 |
bill_trade_no / buyer / payurl | 付款账单上的交易号、付款账号、支付链接。只有部分支付渠道提供,没有时为空。 |
type | 支付方式。 |
addtime / endtime | 下单时间 / 付款时间。 |
name / money / param | 下单时的商品名称、金额和自定义内容。 |
金额始终以字符串返回(如 "100.00")。status 这类数字字段请按数值判断,不要写成只认 1 或只认 "1" 的严格比较。
查询类接口用 GET 传 key,请只从你的服务器发起,全程使用 HTTPS,并且不要把完整的请求地址写进日志。
批量订单查询
按时间从新到旧分页拉取订单,适合对账。
<对接地址>/api.php?act=orderspid + key| 参数 | 必填 | 说明 |
|---|---|---|
pid / key | 必填 | 商户 ID 和商户密钥。 |
limit | 可选 | 每次返回多少条,默认 10,最多 50。 |
offset | 可选 | 从第几条开始,默认 0。翻页时每次加上 limit。 |
status | 可选 | 只返回某个状态的订单,取值同 单笔订单查询 的 status。 |
{
"code": 1,
"msg": "查询订单记录成功!",
"count": 1,
"data": [
{
"trade_no": "2026111715300112345",
"out_trade_no": "20261117153000001",
"type": "alipay",
"pid": 1001,
"addtime": "2026-11-17 15:30:01",
"endtime": "2026-11-17 15:30:42",
"name": "VIP会员",
"money": "100.00",
"param": null,
"buyer": null,
"status": 1
}
]
}count 是本次返回的条数,不是订单总数。翻到没有数据时返回 "count": 0 和空的 data,以此判断已经取完。
商户信息查询
查询账户余额、商户状态和订单数量。
<对接地址>/api.php?act=querypid + key参数只有 pid 和 key。
{
"code": 1,
"pid": 1001,
"key": "你的商户密钥",
"active": 1,
"money": "1234.56",
"type": 1,
"account": "结算账号",
"username": "结算户名",
"orders": 2329,
"orders_today": 6,
"orders_lastday": 18
}| 字段 | 说明 |
|---|---|
active | 商户状态:1 正常,0 已封禁。 |
money | 账户余额,单位元。 |
type / account / username | 平台登记的结算方式编号、结算账号和户名。 |
orders | 累计订单数(含未支付)。 |
orders_today / orders_lastday | 今天 / 昨天支付成功的订单数。 |
结算记录查询
按时间从新到旧分页查询结算记录。
<对接地址>/api.php?act=settlepid + key| 参数 | 必填 | 说明 |
|---|---|---|
pid / key | 必填 | 商户 ID 和商户密钥。 |
limit | 可选 | 每次返回多少条,默认 10,最多 50。 |
offset | 可选 | 从第几条开始,默认 0。 |
成功时 code 为 1,data 是结算记录数组;没有数据时 data 是空数组。每条记录常用的字段如下,其余字段供平台内部使用,可能调整,请不要依赖。
| 字段 | 说明 |
|---|---|
id | 结算记录编号。 |
money | 结算金额,单位元。 |
realmoney | 扣除结算手续费后的实际结算金额,单位元。 |
realusdt | 实际下发的 USDT 数量。 |
addtime / endtime | 结算生成时间 / 完成时间。 |
status | 0 待结算,1 已打款,2 打款中,3 打款失败。 |
transfer_no | 打款的链上交易号,打款完成后才有。 |
申请退款
为一笔已支付的订单提交退款申请。退款不是即时完成的:接口只负责创建申请,由平台客服人工审核和处理。
<对接地址>/api.php?act=refundpid + key这个接口要由平台为商户开通「订单退款 API」后才能使用,未开通时返回 code=-2。
| 参数 | 必填 | 说明 |
|---|---|---|
pid / key | 必填 | 商户 ID 和商户密钥。 |
trade_no | 二选一 | 平台订单号。两个都传时以它为准。 |
out_trade_no | 你的订单号。 | |
money | 必填 | 申请退款的金额,单位元,不能超过订单剩余可退的金额。 |
refund_no | 可选 | 你系统里的退款单号。建议传:同一个 refund_no 重复提交只会得到同一张申请,网络超时后可以放心重试。 |
reason | 可选 | 退款原因,客服处理时能看到。 |
curl -X POST "<对接地址>/api.php?act=refund" \
-d "pid=1001" \
-d "key=你的商户密钥" \
-d "out_trade_no=20261117153000001" \
-d "money=100.00" \
-d "refund_no=R20261117001" \
--data-urlencode "reason=用户取消订单"这个接口成功时 code 是 0,和其它接口不同:
{
"code": 0,
"msg": "退款工单已创建,等待人工处理",
"ticket_no": "TK20261117154528004821",
"status": "pending",
"money": "100.00"
}| 字段 | 说明 |
|---|---|
ticket_no | 退款申请的编号,在商户后台「工单中心」可以用它找到这张申请。 |
status | 申请当前的状态:pending 待处理,processing 处理中,completed 已完成,rejected 已驳回,withdrawn 已撤回。 |
money | 这张申请的退款金额。 |
规则
- 只有已支付的订单可以申请。一笔订单可以分多次退:部分退款完成后,剩下的金额还能继续申请,直到退完。
- 不传
refund_no时,一笔订单同时只保留一张未结束的申请。申请还没处理完就再次调用,返回的是原来那张申请(msg为“退款工单已存在”),金额以原申请为准。 - 申请的进度和结果在商户后台「工单中心」查看,还没开始处理的申请可以在那里撤回。退款完成后,订单查询 返回的
status会变成2。
返回码与常见报错
返回码
| code | 下单接口(mapi.php) | 查询与退款接口(api.php) |
|---|---|---|
1 | 成功 | 成功(退款接口除外) |
0 | — | 仅退款接口:申请已受理 |
-1 | 参数缺失或不合法、商户状态异常等,原因见 msg | 订单不存在、金额不合法等,原因见 msg |
-2 | 订单已创建,但支付渠道下单失败,原因见 msg | 商户未开通订单退款 API |
-3 | 签名校验失败 | 商户 ID 不存在,或密钥错误 |
-4 | 没有收到 POST 参数 | 没有传订单号 |
-5 | — | act 参数不正确 |
下单时的常见报错
页面跳转支付把这些文字显示在错误提示页上,API 接口支付放在 msg 里。
| 提示 | 原因与处理 |
|---|---|
| MD5签名校验失败 | 签名不一致。对照 签名规则 检查,或用 签名调试工具 核对。 |
| 缺少签名参数 | 没有传 sign。 |
| 订单号(out_trade_no)格式不正确 | 订单号里有不允许的字符。只能用字母、数字和 . _ - |。 |
| 该订单…支付参数有变化,请更换订单号重新发起支付 | 这个订单号之前用过,但这次的金额、商品名、通知地址、跳转地址或 param 和上次不同。换一个订单号。 |
| 该订单…已完成支付,请勿重复发起支付 | 这个订单号对应的订单已经付过款。 |
| 金额不合法 / 最大支付金额是…元 / 最小支付金额是…元 | 金额格式不对,或超出平台的单笔限额。 |
| 实际支付金额低于(超过)当前通道单笔最小(最大)限额… | 金额不在这个支付方式允许的范围内,范围见商户后台「测试支付」页。 |
| 用户IP地址(clientip)不能为空 | API 接口支付没有传 clientip。 |
| 支付方式(type)不能为空 | API 接口支付没有传 type。 |
| 商户已被封禁,无法支付!/ 商户未通过审核,无法支付! | 商户状态异常,请联系平台。 |
申请退款时的常见报错
| 提示 | 原因与处理 |
|---|---|
| 商户未开启订单退款API接口 | 联系平台开通「订单退款 API」。 |
| 当前订单不存在! | 订单号不对,或者订单不属于这个商户。 |
| 退款金额不能超过订单剩余可退金额 | 金额大于订单还能退的部分,或小于等于 0。 |
| 当前订单已退款 | 订单已经全部退完。 |
| 退款工单创建失败:订单尚未支付… | 未支付的订单不能退款。用户已付款但订单仍是未支付时,请在商户后台「工单中心」提交掉单申请。 |
常见问题
下单时提示签名校验失败,怎么排查?
通知的签名总是验不过?
通常是金额格式的问题。通知里的 money 会省略末尾的 0,例如 100 而不是 100.00;验签要用收到的原始值,不要自己重新格式化。另外通知里的 name 固定是 product,不是下单时的商品名。参数直接取框架解码后的值即可,不需要再做 URL 编码或解码。
用户已经付款,但没有收到通知?
在商户后台「订单明细」打开这笔订单的详情,可以看到每次通知的时间、HTTP 状态码和你的服务器返回的内容。常见原因:
- 通知地址从公网访问不到,或者被防火墙、WAF 拦截。
- 处理时间超过 10 秒。
- 返回的内容不是单独的
success,例如带了 HTML 或调试输出。
修好之后在订单详情里手动重新发送。平时建议配合 单笔订单查询 做兜底。
同一笔订单会收到多次通知吗?
会。网络超时引起的重试、手动重新发送都会让同一笔订单的通知到达多次。请按 out_trade_no 判断订单是否已经处理过,处理过就直接返回 success。
API 接口支付里的 clientip 应该填什么?
填付款用户的 IP,不是你服务器的 IP,也不能留空。你的服务在反向代理或 CDN 后面时,从代理传来的请求头里取真实的用户 IP。
用户没付款就关掉了,能用同一个订单号再发起吗?
可以。10 天内用同一个 out_trade_no、完全相同的参数再次下单,会继续支付原来那笔订单。金额等参数变了就需要换一个订单号。
提交退款后多久到账,怎么知道结果?
退款由平台客服人工处理,没有固定的到账时间。进度在商户后台「工单中心」查看;退款完成后,订单查询接口返回的 status 会变成 2。
pid 和 appid 有什么区别?
pid 是商户 ID。一个商户下可以建多个应用,每个应用有自己的 appid,平台可以为不同应用配置不同的费率和支付通道。下单时把 pid 换成 appid 即可,通知里的 pid 也会是这个 appid。查询和退款接口仍然使用商户 ID 和商户密钥。
本文档对应 V1 接口(MD5 签名)。最后更新:2026-11-17。