汇花支付 API 文档 #

基础信息 #

请求方式： POST

请求头： Content-Type: application/json

认证方式： 所有接口需要进行签名验证（appkey + sign）

签名算法 #

所有开放接口都需要进行签名验证以确保请求的安全性。

签名生成步骤 #

1. 准备参数：将所有请求参数（除 sign 外）按参数名的字母升序排序
2. 拼接字符串：按 key=value 格式拼接，多个参数用 & 连接
3. 添加密钥：在拼接字符串末尾添加 &secret=您的密钥（secret 通过 appkey 在管理后台查询）
4. MD5 加密：对拼接后的字符串进行 MD5 加密，并转为小写

签名示例 #

假设请求参数为：

{
  "appkey": "abc123",
  "money": 100,
  "notify_url": "http://example.com/notify"
}

假设通过 appkey 查询到的 secret 为：def456

步骤 1：参数排序（按字母顺序）

appkey, money, notify_url

步骤 2：拼接字符串

appkey=abc123&money=100&notify_url=http://example.com/notify

步骤 3：添加密钥

appkey=abc123&money=100&notify_url=http://example.com/notify&secret=def456

步骤 4：MD5 加密（小写）

sign = md5("appkey=abc123&money=100&notify_url=http://example.com/notify&secret=def456")

最终请求参数：

{
  "appkey": "abc123",
  "money": 100,
  "notify_url": "http://example.com/notify",
  "sign": "生成的MD5签名（小写）"
}

注意事项 #

1. 响应码说明：返回的 code 只有 0 表示成功，其他任何值均表示失败
2. AppKey 安全：请妥善保管 AppKey，建议在服务端调用接口
3. 金额单位：所有金额单位均为分，不是元
4. 订单有效期：订单创建后 3 分钟内未支付会自动关闭
5. 异步通知：支付完成后会向 notify_url 发送通知
6. 回调响应：接收异步通知后，必须返回纯文本 ok（小写），否则系统会自动重试，总共尝试 5 次
7. 查询方式：日常查询使用缓存查询，关键节点使用实时查询
8. 退款限制：只有已支付订单可退款，退款不可撤销
9. 时间格式：时间戳单位为毫秒

响应格式 #

{
  "code": 0,          // 0-成功, 其他值-失败
  "msg": "操作成功",   // 提示信息
  "data": {}          // 返回数据
}

订单状态说明 #

1. 创建订单 #

接口地址： /api/v1/open/create_order

请求参数 #

请求示例 #

{
  "appkey": "xxxxxxxxxxxxxxxx",
  "money": 100,
  "notify_url": "http://your-domain.com/notify",
  "sign": "生成的MD5签名"
}

响应示例 #

成功：

{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "pay_url": "https://payment.example.com/pay/xxxxx",
    "order_no": "1046033486053982208"
  }
}

失败：

{
  "code": 1,
  "msg": "下单金额必须大于0",
  "data": null
}

常见错误 #

• 无效的 appkey - AppKey 不存在
• 账户已被禁用 - 商户账户被禁用
• 签名验证失败 - 签名不正确，请检查签名算法
• 缺少 sign 参数 - 请求中未包含签名
• 下单金额必须大于0 - 订单金额小于等于 0
• 当前暂无空闲账号 - 系统繁忙，稍后重试

2. 查询订单 #

接口地址： /api/v1/open/query_order

请求参数 #

请求示例 #

{
  "appkey": "xxxxxxxxxxxxxxxx",
  "order_no": "1046033486053982208",
  "type": 1,
  "sign": "生成的MD5签名"
}

响应示例 #

成功：

{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "userId": 2,
    "userName": "商户名称",
    "orderId": "1046033486053982208",
    "thirdOrderNo": "28c20392d99a4bebabf6bebd3a3961a2",
    "buyerLogonId": "152*******74",
    "money": 100,
    "status": 1,
    "createTime": 1732592077000,
    "updateTime": 1732592244000
  }
}

响应字段说明 #

查询类型说明 #

• 不传 type 或 type=0：缓存查询，从数据库查询，速度快，适合日常查询
• type=1：实时查询，从支付渠道查询，速度较慢但最准确，适合支付完成确认

常见错误 #

• 无效的 appkey - AppKey 不存在
• 账户已被禁用 - 商户账户被禁用
• 签名验证失败 - 签名不正确，请检查签名算法
• 订单不存在 - 订单号不存在

3. 订单退款 #

接口地址： /api/v1/open/refund

请求参数 #

请求示例 #

{
  "appkey": "xxxxxxxxxxxxxxxx",
  "order_no": "1046033486053982208",
  "sign": "生成的MD5签名"
}

响应示例 #

成功：

{
  "code": 0,
  "msg": "操作成功",
  "data": null
}

失败：

{
  "code": 1,
  "msg": "当前订单状态无法退款",
  "data": null
}

退款条件 #

• 订单状态必须为已支付（status = 1）
• 退款金额为订单原金额，不支持部分退款
• 退款操作不可撤销

常见错误 #

• 无效的 appkey - AppKey 不存在
• 账户已被禁用 - 商户账户被禁用
• 签名验证失败 - 签名不正确，请检查签名算法
• 订单不存在 - 订单号不存在
• 当前订单状态无法退款 - 订单状态不是已支付

异步通知说明 #

当订单支付成功后，系统会向创建订单时提供的 notify_url 发送异步通知。

通知格式 #

系统会以 POST 方式发送 JSON 数据到您的通知地址：

{
  "order_no": "1046033486053982208",
  "status": 1,
  "money": 100,
  "pay_time": 1732592244000,
  "sign": "生成的MD5签名"
}

响应要求 #

重试机制 #

• 总尝试次数：5 次
• 时间线：
  • 0 分钟：第 1 次尝试（支付成功后立即发送）
  • 1 分钟：第 2 次尝试（距第 1 次后 1 分钟）
  • 3 分钟：第 3 次尝试（距第 2 次后 2 分钟）
  • 6 分钟：第 4 次尝试（距第 3 次后 3 分钟）
  • 10 分钟：第 5 次尝试（距第 4 次后 4 分钟）
• 停止条件：收到正确的 ok 响应或尝试 5 次后停止

签名验证 #

回调通知中的签名使用与请求接口相同的算法生成：

1. 将参数（order_no, status, money, pay_time）按字母排序
2. 拼接：money=100&order_no=xxx&pay_time=xxx&status=1
3. 添加密钥：money=100&order_no=xxx&pay_time=xxx&status=1&secret=您的密钥
4. MD5 加密（小写）

Python 验证示例：

import hashlib

def verify_callback_sign(params, secret):
    """验证回调签名"""
    # 提取 sign
    received_sign = params.pop('sign', None)
    if not received_sign:
        return False
    
    # 生成签名
    sorted_params = sorted(params.items(), key=lambda x: x[0])
    param_str = '&'.join([f'{k}={v}' for k, v in sorted_params])
    sign_str = f'{param_str}&secret={secret}'
    calculated_sign = hashlib.md5(sign_str.encode('utf-8')).hexdigest().lower()
    
    return received_sign == calculated_sign

# 在回调接口中使用
@app.route('/notify', methods=['POST'])
def notify():
    params = request.get_json()
    secret = "your_secret"  # 您的密钥
    
    # 验证签名
    if not verify_callback_sign(params.copy(), secret):
        return "sign error", 400
    
    # 处理业务逻辑
    order_no = params['order_no']
    status = params['status']
    # ... 处理订单
    
    return "ok"

通知处理建议 #

1. 验证签名：首先验证签名，确保通知来源可信
2. 验证订单：收到通知后，建议调用查询订单接口二次确认订单状态
3. 防重处理：做好防重处理，避免重复处理同一订单
4. 快速响应：尽快返回 ok，避免超时
5. 异步处理：将业务逻辑异步处理，不要在通知接口中执行耗时操作

文档版本： v1.0.0
更新日期： 2025-11-26