支付网关 API 文档

版本 v1 · 基础地址 https://p.paysphere.cn

简介

本平台提供 RESTful 支付接口，商户使用 AppID / AppSecret 签名调用。

签名规则

除 sign 外，所有非空参数按 key 升序
拼接 k1=v1&k2=v2
使用 AppSecret 计算 HMAC-SHA256
十六进制结果转大写作为 sign

$str  = 'app_id=xxx&amount=1.00&...';
$sign = strtoupper(hash_hmac('sha256', $str, $appSecret));

基础信息

协议	HTTPS
编码	UTF-8
方法	POST (application/x-www-form-urlencoded)
响应	JSON

创建订单

POST /api/v1/order/create

参数	必填	说明
app_id	是	AppID
merchant_order_no	是	商户订单号（唯一）
amount	是	金额（元）
pay_type	是	alipay / wechat
subject	否	商品标题
notify_url	否	异步通知
return_url	否	同步跳转
sign	是	签名

{
  "code": 0,
  "data": {
    "order_no": "20240101123456",
    "pay_url": "https://p.paysphere.cn/pay/20240101123456?auto=1"
  }
}

查询订单

POST /api/v1/order/query

参数：app_id、order_no 或 merchant_order_no、sign

关闭订单

POST /api/v1/order/close

异步通知

支付成功后 POST 到 notify_url：

{
  "order_no": "...",
  "merchant_order_no": "...",
  "amount": "1.00",
  "trade_no": "...",
  "status": 1,
  "paid_at": "2024-01-01 12:00:00",
  "sign": "..."
}

返回 success 表示接收成功。

同步跳转

支付完成后跳转 return_url。

返回码

code	说明
0	成功
400	参数错误
401	签名错误
403	商户禁用/冻结
404	订单不存在

PHP 示例

<?php
$params = [
    'app_id'            => 'AKxxx',
    'merchant_order_no' => 'ORD_' . time(),
    'amount'            => '1.00',
    'pay_type'          => 'alipay',
    'subject'           => '测试商品',
];
ksort($params);
$str = implode('&', array_map(fn($k, $v) => $k . '=' . $v, array_keys($params), $params));
$params['sign'] = strtoupper(hash_hmac('sha256', $str, 'your_secret'));

$ch = curl_init('https://p.paysphere.cn/api/v1/order/create');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query($params),
    CURLOPT_RETURNTRANSFER => true,
]);
print_r(json_decode(curl_exec($ch), true));