返回主页

代收下单接口文档

接口说明

请求URL：https://api.openpayhub.com/api/order/intent

请求方式：POST

请求类型：application/json 或 application/x-www-form-urlencoded

认证方式：Header 认证（X-Api-Key + X-Api-Secret）

请求头参数

字段名 变量名 必填 类型 描述
API密钥 X-Api-Key 是 String 商户API密钥，用于身份认证
API密钥 X-Api-Secret 是 String 商户API密钥，用于身份认证（MD5加密后对比）

请求参数

字段名 变量名 必填 类型 示例值 描述
订单金额 amount 是 float 100.00 订单金额，必须为正数
手机号 phone 是 String 9876543210 用户手机号，必须为10位数字
邮箱 email 是 String user@example.com 用户邮箱地址
姓名 name 是 String John Doe 用户姓名
商户订单号 orderId 是 String ORDER20240315001 商户生成的唯一订单号，长度6-32位
异步通知地址 notifyUrl 是 String https://www.xxx.com/notify 支付结果异步回调URL，必须是有效的HTTP/HTTPS地址

请求示例

curl --location 'https://api.openpayhub.com/api/order/intent' \
--header 'X-Api-Key: your_api_key' \
--header 'X-Api-Secret: your_api_secret' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 100.00,
    "phone": "9876543210",
    "email": "user@example.com",
    "name": "John Doe",
    "orderId": "ORDER20240315001",
    "notifyUrl": "https://www.xxx.com/notify"
}'

返回参数

字段名 变量名 必填 类型 示例值 描述
返回状态码 code 是 int 0 0-处理成功，其他-处理有误
返回信息 message 否 String success 具体返回信息
返回数据 data 否 Object {} 返回数据对象

data数据格式

变量名 必填 类型 示例值 描述
PaymentLink 是 String https://pay.xxx.com/... H5支付链接
UpiLink 否 String upi://pay?... UPI深度链接（需在商户后台开启deeplink功能）
amount 是 float 100.00 订单金额
orderId 是 String ORDER20240315001 商户订单号
tmId 是 String HZ1234567890 平台订单号

成功返回示例

{
    "code": 0,
    "message": "success",
    "data": {
        "PaymentLink": "https://pay.xxx.com/h5/abc123",
        "UpiLink": "upi://pay?pa=xxx@upi&pn=Merchant&am=100.00",
        "amount": 100.00,
        "orderId": "ORDER20240315001",
        "tmId": "HZ1234567890"
    }
}

错误返回示例

// 请求数据为空
{
    "code": 400,
    "message": "Empty data",
    "data": ""
}

// 金额为空
{
    "code": 400,
    "message": "Empty amount",
    "data": ""
}

// 金额格式无效
{
    "code": 400,
    "message": "amount invalid",
    "data": ""
}

// 手机号格式错误
{
    "code": 400,
    "message": "phone must be 10 number",
    "data": ""
}

// 邮箱格式错误
{
    "code": 400,
    "message": "Email is invalid",
    "data": ""
}

// 通知地址格式错误
{
    "code": 400,
    "message": "NotifyUrl is invalid",
    "data": ""
}

// 订单号长度错误
{
    "code": 400,
    "message": "orderId length must between 6 and 32",
    "data": ""
}

// API Key 无效
{
    "code": 400,
    "message": "X-Api-Key Is Invalid",
    "data": ""
}

// API Key 未授权
{
    "code": 401,
    "message": "X-Api-Key Is unauthrized",
    "data": ""
}

// API Secret 未授权
{
    "code": 401,
    "message": "X-Api-Secret Is unauthrized",
    "data": ""
}

// 商户不存在
{
    "code": 404,
    "message": "Merchant Not Found",
    "data": ""
}

// IP 不在白名单中
{
    "code": 403,
    "message": "Ip not allowed-192.168.1.1",
    "data": ""
}

// 代收未开通
{
    "code": 403,
    "message": "Payin not open",
    "data": ""
}

// 请求过于频繁
{
    "code": 429,
    "message": "Frequent requests",
    "data": ""
}

// 重复订单
{
    "code": 400,
    "message": "Double order",
    "data": ""
}

// 代收已关闭
{
    "code": 403,
    "message": "payin is closed",
    "data": ""
}

// 金额超出限制
{
    "code": 400,
    "message": "Amount must between 10 and 100000",
    "data": ""
}

// 未配置代收方案
{
    "code": 400,
    "message": "No default channel",
    "data": ""
}

// 无可用渠道
{
    "code": 400,
    "message": "No channel",
    "data": ""
}

// 渠道类不存在
{
    "code": 404,
    "message": "Not found channel",
    "data": ""
}

// 渠道异常
{
    "code": 500,
    "message": "Additional exceptions",
    "data": ""
}

错误码说明

错误码 说明
0 请求成功
400 请求参数错误（数据为空、格式错误、长度不符等）
401 未授权（API Key 或 Secret 验证失败）
403 禁止访问（IP 不在白名单、代收未开通、代收已关闭等）
404 资源不存在（商户不存在、渠道类不存在）
429 请求过于频繁（超出 QPS 限制）
500 服务器内部错误（渠道异常等）

注意事项

重要提示
  • 调用接口前请确保已在后台配置 IP 白名单
  • X-Api-Secret 需要进行 MD5 加密后与数据库中的 iv 字段对比
  • 建议在生产环境使用 HTTPS 协议
  • 接口会记录请求日志，包含请求 IP 和 API Key
  • 订单号 orderId 必须唯一，重复提交会返回 "Double order" 错误
  • 同一订单号在 60 秒内不能重复提交
  • 商户需要在后台开通代收功能（payin_status = 1）
  • 平台代收功能开启时才能正常下单
  • 金额必须在平台配置的最小和最大金额范围内
  • 手机号必须为 10 位纯数字
  • 通知地址必须是有效的 HTTP/HTTPS URL

QPS 限制说明

限流规则
  • 每个商户可以配置独立的 QPS 限制（payin_qps）
  • 当请求频率超过限制时，会返回 "Frequent requests" 错误
  • 限流统计周期为 1 秒
  • 建议合理控制请求频率，避免触发限流

业务流程说明

  1. 验证请求参数是否完整（amount、phone、email、name、orderId、notifyUrl）
  2. 验证请求头中 X-Api-Key 和 X-Api-Secret
  3. 获取客户端真实 IP 地址
  4. 记录请求日志
  5. 验证金额格式（必须为正数）
  6. 验证订单号长度（6-32位）
  7. 验证手机号格式（10位纯数字）
  8. 验证邮箱格式
  9. 验证通知地址格式（有效的 HTTP/HTTPS URL）
  10. 根据 X-Api-Key 查询商户密钥信息
  11. 验证 X-Api-Secret（MD5 加密后对比）
  12. 查询商户信息并验证 IP 白名单
  13. 验证商户代收功能是否开通
  14. 检查 QPS 限流
  15. 检查重复订单（60秒内不能重复提交同一订单号）
  16. 验证平台代收功能状态
  17. 验证金额是否在允许范围内
  18. 根据金额自动分配支付渠道
  19. 生成平台订单号
  20. 调用渠道支付接口
  21. 返回支付链接（H5链接和UPI深度链接）

渠道分配规则

分配逻辑
  1. 优先检查是否有金额区间配置（根据商户ID和金额匹配）
  2. 如有金额区间配置，使用该配置对应的渠道
  3. 如无金额区间配置，使用商户默认代收方案
  4. 从默认方案中随机选择可用渠道
  5. 如未配置默认方案或无可用的渠道，返回错误

异步通知说明

通知机制
  • 支付完成后，系统会向商户提供的 notifyUrl 发送异步通知
  • 通知方式为 POST 请求，Content-Type 为 application/json
  • 商户需要在收到通知后返回 JSON 格式的响应：{"code": 0, "message": "success"}
  • 如果商户未正确响应，系统会重试通知（最多重试 5 次）
  • 重试间隔为：1分钟、5分钟、10分钟、30分钟、1小时