API文档 - API服务

快速开始

欢迎使用API接口服务。以下是完整的接入流程，帮助您在5分钟内完成首次调用。

第一步：注册开发者账号

前往注册页面创建您的开发者账号。注册成功后自动获得体验版套餐，每日可调用 1,000 次。

第二步：获取凭证

登录后在 开发者中心 → 凭证管理 获取您的 AppKey（应用标识）和密钥（Key）。请妥善保管密钥，不要泄露给他人。

第三步：发起API调用

参考下方接口文档构造请求，传入订单号和金额参数，即可完成服务调用。

POST /web/create HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "appkey": "YOUR_APPKEY",
  "trade_no": "T2026091200001",
  "amount": 100.00,
  "notify_url": "https://your-domain.com/callback"
}

第四步：接收异步通知

服务完成后，系统将 POST 通知您配置的回调地址。请参考异步通知文档验证签名并处理业务逻辑。

接口概述

本服务提供 RESTful API 接口，遵循 JSON 标准格式，支持 HTTPS 安全传输。

环境	接口地址	说明
正式环境	https://web.example.com	生产环境，用于正式业务
测试环境	https://sandbox.example.com	沙箱环境，可免费无限调用

通用请求头

参数名	类型	说明
Content-Type	string	固定值：application/json
Authorization	string	签名值，格式：Bearer {签名}
User-Agent	string	标识来源，建议包含应用名称和版本

认证鉴权

所有 API 请求都需要携带签名信息，通过 AppKey 和密钥计算 HMAC-SHA256 签名。

签名算法：
sign = HMAC-SHA256(appkey + trade_no + amount, key)
       .toUpperCase()

请求示例：
https://web.example.com/web/create?appkey=YOUR_APPKEY&sign=ABCD1234...

具体签名步骤请参考签名说明章节。

服务创建 / 创建订单

调用此接口创建一个新的服务订单，系统返回支付链接或二维码。

请求参数

参数名	类型	必填	说明
appkey	string	必填	应用的唯一标识
trade_no	string	必填	商户自定义订单号，最大32位字母数字
amount	float	必填	金额，单位：元，最小0.01
notify_url	string	选填	异步通知回调地址，需公网可访问
return_url	string	选填	支付完成后跳转地址
subject	string	选填	订单标题，显示在支付页面
sign	string	必填	请求签名，详见签名说明

返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "trade_no": "T2026091200001",
    "pay_url": "https://..."
  }
}

订单查询

通过订单号查询服务的当前状态和详细信息。

请求参数

参数名	类型	必填	说明
appkey	string	必填	应用的唯一标识
trade_no	string	必填	订单号
sign	string	必填	签名

返回状态码

状态码	说明
0	待处理（Pending）
1	已完成（Success）
2	已失败（Failed）
-1	已取消（Cancelled）

异步通知

服务完成后，系统会向您配置的 notify_url 发送 POST 通知。请务必验证签名后再处理业务。

通知格式（POST，application/x-www-form-urlencoded）：
trade_no=YOUR_TRADE_NO&status=1&sign=ABCD1234...

请自行解析参数并验证 sign 是否匹配。

收到通知后请返回 success 表示接收成功。如返回其他内容，系统将在 24 小时内多次重试通知。

签名说明

所有请求都需要携带签名，签名基于 HMAC-SHA256 算法，确保请求不被篡改。

签名步骤

将所有请求参数按字典序排列（sign 本身除外）
拼接成 key1=value1&key2=value2 格式的字符串
将上一步结果作为待签名字符串
使用 HMAC-SHA256，以密钥 key 为密钥进行签名
将签名结果转为十六进制大写

PHP 签名示例：
$params = ['appkey' => $appkey, 'trade_no' => $trade_no, 'amount' => $amount];
ksort($params);
$str = http_build_query($params);
$sign = strtoupper(hash_hmac('sha256', $str, $key));

SDK下载

我们提供多种语言的 SDK，帮助您快速接入。

PHP SDK

适用于 PHP 5.6+ 项目

下载

Python SDK

适用于 Python 3.6+ 项目

下载

Java SDK

适用于 JDK 1.8+ 项目

下载

Node.js SDK

适用于 Node.js 12+ 项目

下载

示例代码

以下是 PHP 调用示例，完整示例请下载 SDK 后查看。

// 1. 构造请求参数
$params = [
    'appkey'   => 'YOUR_APPKEY',
    'trade_no' => 'T' . time(),
    'amount'   => 100.00,
    'notify_url' => 'https://your-domain.com/callback',
    'subject'  => 'API服务',
];
$params['sign'] = sign($params, 'YOUR_KEY');

// 2. 发送POST请求
$ch = curl_init('https://web.example.com/web/create');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

// 3. 解析响应
$result = json_decode($response, true);
if ($result['code'] == 0) {
    // 跳转支付
    header('Location: ' . $result['data']['pay_url']);
}