柯达集团 开发文档

开发文档

本文档说明如何接入 柯达集团 的收款接口:发起支付、接收支付结果、查询订单和申请退款。接口使用 MD5 签名,文中的示例代码都实际运行验证过。

接口一览

用途路径方式身份校验
页面跳转支付/submit.phpGET / POST签名
API 接口支付/mapi.phpPOST签名
支付结果通知你下单时传的 notify_urlGET(平台请求你)签名,由你校验
单笔订单查询/api.php?act=orderGETpid + key
批量订单查询/api.php?act=ordersGETpid + key
商户信息查询/api.php?act=queryGETpid + key
结算记录查询/api.php?act=settleGETpid + key
申请退款/api.php?act=refundPOSTpid + 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 与商户密钥。

接入流程

  1. 拿到凭证和对接地址。在商户后台「API 凭证」页查看 pid 和 key,并向平台索取对接地址。
  2. 选一种下单方式。想让用户跳到平台的支付页,用 页面跳转支付;想自己展示二维码或支付链接,用 API 接口支付。
  3. 生成签名并下单。按 签名规则 计算 sign。结果对不上时,用 签名调试工具 逐步核对。
  4. 实现通知地址。按 支付结果通知 的要求验签、核对金额、更新订单,然后返回 success。订单是否付款只以通知或查询结果为准。
  5. 加上查单兜底,再用小金额走通一笔。通知可能因为网络原因收不到,建议对迟迟没有结果的订单调用 单笔订单查询。通道是否可用,可以先在商户后台「测试支付」页确认。

签名规则

下单请求要带签名,平台发给你的支付结果通知也带签名,两边用的是同一套规则:

  1. 取出全部参数,去掉 sign 和 sign_type,再去掉值为空的参数。
  2. 按参数名的 ASCII 码从小到大排序。
  3. 写成 参数名=值,用 & 连接。值用原始内容,不要做 URL 编码。
  4. 在末尾直接接上商户密钥(中间不加 &,也不加 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会员&notify_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);
}
最常见的四个错误
  • 把 sign、sign_type 或空值参数也拼进去了。
  • 对值做了 URL 编码,例如把 https:// 写成 https%3A%2F%2F。
  • 密钥前面多加了 & 或 &key=。
  • 提交时又改动了参数,例如签名用 100.00,实际提交 100。

签名调试工具

把参数和密钥填进来,可以看到待签名字符串和签名结果,方便和你的程序逐步对比。计算只在你的浏览器里进行,不会发送到任何服务器。

值里本身带有 & 时(例如通知地址带查询参数),请用每行一个的写法。参数里如果带了 sign,工具会顺便告诉你它和计算结果是否一致。

页面跳转支付

适合网站收银。你把用户的浏览器带到这个地址,用户在平台的支付页完成付款,付完后回到你的页面。

POSTGET<对接地址>/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>';

API 接口支付

适合 App、小程序后端或想自己控制支付界面的网站。由你的服务器请求这个接口,拿到支付链接或二维码内容,再展示给用户。

POST<对接地址>/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,不参与签名。

返回结果

字段说明
code1 表示下单成功,其它值都是失败,含义见 返回码。
msg失败原因,成功时没有这个字段。
trade_no平台订单号。请保存下来,查单和对账都用得到。
payurl支付链接,让用户在浏览器里打开。
qrcode二维码内容,由你生成二维码图片给用户扫。
urlschemeApp 唤起链接,在手机上直接跳转。

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']
}

支付结果通知

用户付款成功后,平台会用 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

上面这条示例沿用了 签名规则 里的密钥,可以拿来测试你的验签代码。

你需要做的事

  1. 验签。用收到的参数按 签名规则 重新计算,和 sign 一致才继续。必须用收到的原始值计算,不要先把 100 改写成 100.00。
  2. 核对订单。按 out_trade_no 找到你的订单,确认 trade_status 是 TRADE_SUCCESS,并且金额和订单一致(按数值比较)。
  3. 幂等处理。同一笔订单的通知可能收到多次。订单已经是已支付时,直接回复成功,不要重复发货。
  4. 回复 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';

浏览器跳转 return_url

付款完成后,用户的浏览器会带着同样的参数跳到 return_url。你可以在这个页面里验签后展示“支付成功”,但不要在这里更新订单:用户可能中途关掉页面,这次跳转也不保证发生。付款完成超过 5 分钟后再打开支付页,会停留在平台的成功提示页,不再跳回你的网站。

支付方式与设备类型

支付方式(type)

下面是平台当前开放的支付方式。你的商户实际能用哪些、各自的金额范围是多少,以商户后台为准。

type 取值支付方式
alipay支付宝
wxpay微信支付

设备类型(device)

只有 API 接口支付 用得到。它告诉平台用户在什么环境里付款,平台据此返回合适的支付形式。

device 取值用户所在的环境
pc电脑浏览器(默认)
mobile手机浏览器
wechat微信内置浏览器
alipay支付宝客户端
qq手机 QQ 内置浏览器
jump不区分环境,只要一个支付跳转链接(返回 payurl)

单笔订单查询

主动查询一笔订单是否已付款。建议作为通知的补充:订单长时间没有收到通知时查一次。

GET<对接地址>/api.php?act=orderpid + key
参数必填说明
pid必填商户 ID。
key必填商户密钥。
trade_no二选一平台订单号。两个都传时以它为准。
out_trade_no你的订单号。
cURL
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,并且不要把完整的请求地址写进日志。

批量订单查询

按时间从新到旧分页拉取订单,适合对账。

GET<对接地址>/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,以此判断已经取完。

商户信息查询

查询账户余额、商户状态和订单数量。

GET<对接地址>/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今天 / 昨天支付成功的订单数。

结算记录查询

按时间从新到旧分页查询结算记录。

GET<对接地址>/api.php?act=settlepid + key
参数必填说明
pid / key必填商户 ID 和商户密钥。
limit可选每次返回多少条,默认 10,最多 50。
offset可选从第几条开始,默认 0。

成功时 code 为 1,data 是结算记录数组;没有数据时 data 是空数组。每条记录常用的字段如下,其余字段供平台内部使用,可能调整,请不要依赖。

字段说明
id结算记录编号。
money结算金额,单位元。
realmoney扣除结算手续费后的实际结算金额,单位元。
realusdt实际下发的 USDT 数量。
addtime / endtime结算生成时间 / 完成时间。
status0 待结算,1 已打款,2 打款中,3 打款失败。
transfer_no打款的链上交易号,打款完成后才有。

申请退款

为一笔已支付的订单提交退款申请。退款不是即时完成的:接口只负责创建申请,由平台客服人工审核和处理。

POST<对接地址>/api.php?act=refundpid + key
需要先开通

这个接口要由平台为商户开通「订单退款 API」后才能使用,未开通时返回 code=-2。

参数必填说明
pid / key必填商户 ID 和商户密钥。
trade_no二选一平台订单号。两个都传时以它为准。
out_trade_no你的订单号。
money必填申请退款的金额,单位元,不能超过订单剩余可退的金额。
refund_no可选你系统里的退款单号。建议传:同一个 refund_no 重复提交只会得到同一张申请,网络超时后可以放心重试。
reason可选退款原因,客服处理时能看到。
cURL
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。
当前订单已退款订单已经全部退完。
退款工单创建失败:订单尚未支付…未支付的订单不能退款。用户已付款但订单仍是未支付时,请在商户后台「工单中心」提交掉单申请。

常见问题

下单时提示签名校验失败,怎么排查?

先用 签名规则 里的例子验证你的签名函数:同样的参数和密钥,应当算出 a8177dededc32736ebc5448dba323bcc。函数没问题的话,把实际提交的参数和密钥填进 签名调试工具,对比待签名字符串,通常能看出是哪个参数不一样。最常见的原因是签名之后又改了参数,或者把空值、sign_type 拼了进去。

通知的签名总是验不过?

通常是金额格式的问题。通知里的 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。