返回主页

代付下单接口文档

接口说明

请求URL：https://api.openpayhub.com/api/payout/create

请求方式：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 代付金额，必须为正数
商户订单号 orderId 是 String ORDER20240315001 商户生成的唯一订单号，长度6-32位
异步通知地址 notifyUrl 是 String https://www.xxx.com/notify 代付结果异步回调URL，必须是有效的HTTP/HTTPS地址
手机号 mobile 是 String 9876543210 收款人手机号，必须为10位数字
代付类型 type 是 String IMPS/UPI 代付方式：IMPS-银行转账，UPI-UPI转账
收款人姓名 name 是 String John Doe 收款人姓名
邮箱 email 是 String user@example.com 收款人邮箱地址
银行账号 account 条件必填 String 123456789012 收款人银行账号（type=IMPS时必填）
IFSC代码 ifsc 条件必填 String SBIN0001234 银行IFSC代码（type=IMPS时必填）
UPI地址 upi 条件必填 String user@upi 收款人UPI地址（type=UPI时必填）

代付类型说明

IMPS（银行转账）

使用银行转账方式进行代付，需要提供以下参数：

  • account - 收款人银行账号（必填）
  • ifsc - 银行IFSC代码（必填）
UPI（UPI转账）

使用UPI方式进行代付，需要提供以下参数：

  • upi - 收款人UPI地址（必填）

请求示例

IMPS 代付请求

curl --location 'https://api.openpayhub.com/api/payout/create' \
--header 'X-Api-Key: your_api_key' \
--header 'X-Api-Secret: your_api_secret' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 100.00,
    "orderId": "ORDER20240315001",
    "notifyUrl": "https://www.xxx.com/notify",
    "mobile": "9876543210",
    "type": "IMPS",
    "account": "123456789012",
    "ifsc": "SBIN0001234",
    "name": "John Doe",
    "email": "user@example.com"
}'

UPI 代付请求

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

返回参数

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

data数据格式

变量名 必填 类型 示例值 描述
status 是 String PENDING 订单状态：SUCCESS-成功，FAILED-失败，PENDING-处理中，EXPIRED-已过期
amount 是 float 100.00 代付金额
orderId 是 String ORDER20240315001 商户订单号
tmId 是 String DD1234567890 平台订单号

成功返回示例

{
    "code": 0,
    "message": "success",
    "data": {
        "status": "PENDING",
        "amount": 100.00,
        "orderId": "ORDER20240315001",
        "tmId": "DD1234567890"
    }
}

错误返回示例

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

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

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

// 订单号为空
{
    "code": 400,
    "message": "Empty orderId",
    "data": ""
}

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

// 通知地址为空
{
    "code": 400,
    "message": "Empty notifyUrl",
    "data": ""
}

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

// 手机号格式错误
{
    "code": 400,
    "message": "mobile invalid",
    "data": ""
}

// 代付类型未传
{
    "code": 400,
    "message": "type is mandatory",
    "data": ""
}

// 代付类型无效
{
    "code": 400,
    "message": "type is invalid",
    "data": ""
}

// IMPS 银行账号为空
{
    "code": 400,
    "message": "Empty account",
    "data": ""
}

// IMPS IFSC 代码为空
{
    "code": 400,
    "message": "Empty ifsc",
    "data": ""
}

// UPI 地址为空
{
    "code": 400,
    "message": "Empty upi",
    "data": ""
}

// 收款人姓名为空
{
    "code": 400,
    "message": "Empty name",
    "data": ""
}

// 邮箱为空
{
    "code": 400,
    "message": "Empty email",
    "data": ""
}

// 邮箱格式错误
{
    "code": 400,
    "message": "Email is invalid",
    "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": "Payout not open",
    "data": ""
}

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

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

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

// 余额不足
{
    "code": 400,
    "message": "Insufficient balance",
    "data": ""
}

// 扣款失败
{
    "code": 500,
    "message": "Money decr error",
    "data": ""
}

// 系统错误
{
    "code": 500,
    "message": "please try again later",
    "data": ""
}

错误码说明

错误码 说明
0 请求成功
400 请求参数错误（数据为空、格式错误、长度不符、余额不足等）
401 未授权（API Key 或 Secret 验证失败）
403 禁止访问（IP 不在白名单、代付未开通、代付已关闭等）
404 资源不存在（商户不存在）
500 服务器内部错误（扣款失败、系统异常等）

注意事项

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

业务流程说明

  1. 验证请求参数是否完整（amount、orderId、notifyUrl、mobile、type、name、email）
  2. 验证请求头中 X-Api-Key 和 X-Api-Secret
  3. 获取客户端真实 IP 地址
  4. 记录请求日志
  5. 验证金额格式（必须为正数）
  6. 验证订单号长度（6-32位）
  7. 验证通知地址格式（有效的 HTTP/HTTPS URL）
  8. 验证手机号格式（10位纯数字）
  9. 验证代付类型（IMPS 或 UPI）
  10. 根据代付类型验证必填参数（IMPS需要account和ifsc，UPI需要upi）
  11. 验证收款人姓名和邮箱
  12. 根据 X-Api-Key 查询商户密钥信息
  13. 验证 X-Api-Secret（MD5 加密后对比）
  14. 查询商户信息并验证 IP 白名单
  15. 验证商户代付功能是否开通
  16. 检查重复订单（60秒内不能重复提交同一订单号）
  17. 验证平台代付功能状态
  18. 验证金额是否在允许范围内
  19. 检查商户余额是否充足
  20. 扣除商户余额
  21. 创建代付订单记录
  22. 根据代付类型调用相应的代付渠道
  23. 返回订单信息

异步通知说明

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

使用建议

最佳实践
  • 建议在异步通知未能正常接收时，使用订单查询接口主动查询订单状态
  • 可以设置定时任务轮询未完成订单的状态
  • 查询频率建议控制在合理范围内，避免频繁调用
  • 收到 SUCCESS 状态后，建议将订单标记为已完成，避免重复处理
  • 对于 PENDING 状态的订单，可以间隔一段时间后再次查询
  • 确保商户账户有足够的余额进行代付操作
  • 代付前建议先查询余额，避免因余额不足导致订单失败