佳梦支付 · 开放 API 文档

四川佳梦云网络科技有限公司 · V1 · 网关地址 https://ai.avuoo.com · 演示环境当前运行 Demo 模拟通道

安全规范

签名: HMAC-SHA256。待签名串为全部请求参数(除 sign 与空值)按 key ASCII 升序 k=v&... 末尾拼 &key=appSecret, 对其取 HMAC-SHA256 十六进制小写。
时间戳: timestamp 秒级, 与服务端偏差 ±300 秒内。
防重放: nonce 随机串, 6 分钟内不可重复。
金额: 单位统一为「分」(整数)。
限流: 开放接口默认不限支付频率; 如需启用应用级限流(60 次/分钟), 由平台在参数配置中开启。

密钥仅在商户后台创建/重置时显示一次。响应与回调同样携带 sign, 请务必验签后再入账。

接口列表

接口	路径	说明
POST	/api/open/v1/pay/unifiedorder	统一下单(`pay_way=CASHIER` 返回收银台 URL)
POST	/api/open/v1/pay/query	订单查询(order_no 或 out_trade_no)
POST	/api/open/v1/pay/close	关闭待支付订单
POST	/api/open/v1/pay/refund	申请退款(全额/部分)
POST	/api/open/v1/pay/refund/query	退款查询
POST	/api/open/v1/transfer/apply	代付申请(平台复核后执行)
POST	/api/open/v1/transfer/query	代付查询
POST	/api/open/v1/complaint/list	投诉列表(需开通投诉 API)
POST	/api/open/v1/complaint/rate	近 7 天投诉率(需开通投诉 API)
POST	/api/callback/{pluginId}	渠道回调网关(平台内部, 通道插件验签)

统一下单示例

Node.js

// npm i crypto (内置)
const crypto = require('crypto');
const SECRET = '<appSecret>';
function sign(params) {
  const qs = Object.keys(params).filter(k => k !== 'sign' && params[k] !== '').sort()
    .map(k => `${k}=${params[k]}`).join('&') + `&key=${SECRET}`;
  return crypto.createHmac('sha256', SECRET).update(qs).digest('hex');
}
const params = {
  app_id: '<appId>', out_trade_no: 'T' + Date.now(),
  amount: 9900, subject: '订单标题', pay_way: 'CASHIER',
  notify_url: 'https://your.app/notify', consumer_phone_tail: '1234',
  timestamp: Math.floor(Date.now()/1000), nonce: crypto.randomUUID().replace(/-/g,''),
};
params.sign = sign(params);
const resp = await fetch('https://ai.avuoo.com/api/open/v1/pay/unifiedorder', {
  method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify(params) }).then(r=>r.json());
// resp.data.cashier_url -> 跳转收银台

PHP

<?php
// 统一下单(收银台模式)
function jm_sign(array $p, string $secret): string {
  unset($p['sign']); $p = array_filter($p, fn($v) => $v !== '' && $v !== null);
  ksort($p);
  $qs = urldecode(http_build_query($p)) . "&key={$secret}";
  return hash_hmac('sha256', $qs, $secret);
}
$params = [
  'app_id' => '<appId>', 'out_trade_no' => 'T'.time(),
  'amount' => 9900, 'subject' => '订单标题', 'pay_way' => 'CASHIER',
  'notify_url' => 'https://your.app/notify',
  'timestamp' => time(), 'nonce' => bin2hex(random_bytes(8)),
];
$params['sign'] = jm_sign($params, '<appSecret>');
$ch = curl_init('https://ai.avuoo.com/api/open/v1/pay/unifiedorder');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($params),
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_RETURNTRANSFER => true]);
echo curl_exec($ch); // data.cashier_url

异步通知(商户侧验签)

// 平台 POST form-urlencoded 回调: order_no,out_trade_no,amount,status,paid_at,timestamp,nonce,sign
// 验签通过后请返回字符串 success (不区分大小写), 否则平台按 15s/30s/1m/... 阶梯重试至多 12 次

pay_way 支付方式

值	含义
CASHIER	聚合收银台(返回 cashier_url, 平台自有品牌)
WECHAT_JSAPI / WECHAT_NATIVE / WECHAT_H5	微信 JSAPI / 扫码 / H5
ALIPAY_QR / ALIPAY_WAP	支付宝扫码 / H5
UNIONPAY_QR / QQ_QR	云闪付 / QQ 钱包(经汇付/富友聚合通道)

错误码

code	说明
SIGN_ERROR	签名验证失败
TIMESTAMP_EXPIRED	时间戳超出 ±5 分钟
NONCE_REPLAY	nonce 重复(防重放拦截)
ORDER_DUPLICATE	商户订单号已存在
ORDER_STATE_ERROR	订单状态不允许此操作
REFUND_ERROR	退款金额超过可退金额
NO_CHANNEL	暂无可用支付通道
RATE_LIMITED	请求过于频繁
MERCHANT_FROZEN	商户冻结或未过审

沙箱联调

演示环境全部订单经 channel-demopay 模拟通道: 下单返回收银台 URL, 打开后选择任一支付方式, 页面将跳转「Demo 模拟银行」, 点击确认付款即触发全量回调链路(订单状态、商户异步通知、分润记账、统计)。

投诉链路: 收银台支付成功页 → 「对本次订单投诉」进入消费者服务页提交; 渠道侧投诉可用平台后台「立即同步」拉取模拟投诉。