支付平台API对接文档

本文档提供了支付平台所有接口的详细说明，包括请求参数、返回参数、示例代码等。请仔细阅读每个接口的使用说明。

重要提示：
  • 所有接口请求均使用 POST 方法
  • 请求参数支持 JSON 和 form-data 两种格式
  • 所有接口都需要进行签名验证
  • 签名计算时 ext 字段不参与签名

签名算法

为了保证接口调用的安全性，所有接口都需要进行签名验证。

签名规则

  1. 参数签名不包含 ext 字段
  2. 将所有参数按参数名排序
  3. 使用 key=value 和 & 连接每个参数，参数为空值不参与签名
  4. 再拼接 key={secret}
  5. 将拼接好的字符串进行 MD5 运算，得到 32位 小写字符串
注意：
不要将 secret 作为参数传入接口

签名示例

拼接字符串: amount=100&app_id=123456¬ify_url=http://my_notify_url&out_trade_no=202001016447&product_id=16&time=1500001234&key=abcdefg 对应的MD5签名为: f0d2df13c0fd006ec4bd4122b9222e7d

支付(代收)

用于创建支付订单，返回支付链接供用户完成支付。

POST /api/order

请求参数

参数 描述 类型 长度 是否必填 示例
app_id 开发者ID String 32 是 2001101011
product_id 产品渠道ID int 10 是 123
out_trade_no 客户端订单号 String 64 是 123456789
notify_url 异步通知url String 500 是 https://abc.def.gh/notify
amount 订单金额(单位:元) String - 是 100.00
time 当前请求秒级时间戳 int - 是 1500001234
desc 订单描述,原样返回 String 200 否 abc
ext 扩展字段 不参与签名！ JSON Object 1000 否 {"bankName":"bankName"}
sign 接口签名,详见签名生成 String 32 是 5cdf1c679b4a2ec216bc339d6edb1f45

JSON格式请求示例

curl --location --request POST 'http://xxxxx/api/pay' \ --header 'Content-Type: application/json' \ --data-raw '{ "product_id": "1", "app_id": "aaa", "out_trade_no": "123456", "notify_url": "http://wwww.xx.com", "amount": "10.00", "desc": "", "time": 1640995200, "sign": "aaaaaa", "ext": { "clientIp": "123.123.123.123" } }'

Form格式请求示例

curl --location --request POST 'http://xxxxx/api/pay' \ --form 'product_id="1"' \ --form 'app_id="aaa"' \ --form 'out_trade_no="123456"' \ --form 'notify_url="http://wwww.xx.com"' \ --form 'amount="10.00"' \ --form 'desc=""' \ --form 'time="1640995200"' \ --form 'sign="aaaaaa"' \ --form 'ext["clientIp"]="123.123.123.123"'

返回参数

参数 描述 类型 示例
code 状态码 int 200
message 状态描述 String 成功
data 返回数据 Object -

data结构说明

参数 描述 类型 示例
type 返回数据类型 String url
url 支付地址 String https://abc.def.gh/pay

返回示例

{ "code": 200, "message": "OK", "data": { "type": "url", "url": "https://abc.def.gh/pay" } }

支付回调

支付完成后，系统会向您提供的notify_url发送支付结果通知。

通知方式：
  • 请求方式: POST
  • 数据格式: form-data
  • 成功返回: 返回小写 success 表示成功

通知参数

参数 描述 类型 示例
trade_no 平台订单编号 String 2001101011
product_id 产品渠道ID int 123
app_id 开发者ID String 2001101011
out_trade_no 客户端订单号 String 123456789
trade_status 交易状态:1成功,-1处理中,2失败 int 1
amount 订单金额(单位:元) String 100.00
real_amount 订单实际金额(单位:元) String 100.00
complete_time 完成时间 时间字符串 2000-12-16 10:20:37
desc 订单描述,原样返回 String abc
time 当前请求秒级时间戳 int 1500001234
sign 接口签名 String 5cdf1c679b4a2ec216bc339d6edb1f45

支付查询

主动查询订单支付状态。

POST /api/order/status

请求参数

参数 描述 类型 是否必填 示例
app_id 开发者ID String 是 2001101011
out_trade_no 客户端订单号 String 是 123456789
time 当前请求秒级时间戳 int 是 1500001234
sign 接口签名 String 是 5cdf1c679b4a2ec216bc339d6edb1f45

返回示例

{ "code": 200, "message": "OK", "data": { "trade_no": 1234567890123456, "product_id": 1, "app_id": "abcdenfg", "out_trade_no": "abc1234567890", "trade_status": 1, "amount": "10.00", "real_amount": "10.00", "desc": "abc", "complete_time": "2022-01-01 11:30:01" } }

账户查询

查询账户余额信息。

POST /api/account

请求参数

参数 描述 类型 是否必填 示例
app_id 开发者ID String 是 2001101011
time 当前请求秒级时间戳 int 是 1500001234
sign 接口签名 String 是 5cdf1c679b4a2ec216bc339d6edb1f45

返回data结构

参数 描述 类型 示例
account 可提现资金账户 String 123.45
frozen_account 冻结中资金账户 String 123.45
total_account 总资金账户=可提现+冻结中 String 123.45

返回示例

{ "code": 200, "message": "OK", "data": { "account": "123.45", "frozen_account": "123.45", "total_account": "123.45" } }

代付(提现)

创建提现订单，将资金转账到指定账户。

POST /api/payment

请求参数

参数 描述 类型 是否必填 示例
app_id 开发者ID String 是 2001101011
product_id 产品渠道ID，可在商户后台代付产品查看 int 是 123
out_trade_no 客户端订单号 String 是 123456789
notify_url 异步通知url String 否 https://abc.def.gh/notify
amount 订单金额(单位:元) String 是 100.00
time 当前请求秒级时间戳 int 是 1500001234
desc 订单描述,原样返回 String 否 abc
ext 扩展字段 不参与签名！
JSON Object 不是字符串		 JSON Object 是 见下方说明
sign 接口签名 String 是 5cdf1c679b4a2ec216bc339d6edb1f45
ext 参数说明：
  • 银行卡默认参数: {"bankName":"银行名称","accountName":"账户名称","accountNumber":"卡号"}
  • 支付宝默认参数: {"bankName":"随便填","accountName":"姓名","accountNumber":"支付宝号"}
  • 海外代付: 具体字段看后台代付产品 ext

可选字段: accountName(账户名称), accountNumber(卡号), bankName(银行名称), subbranch(支行名称), province(省), city(市)

JSON格式请求示例

curl --location --request POST 'http://xxxxx/api/payment' \ --header 'Content-Type: application/json' \ --data-raw '{ "product_id": "1", "app_id": "aaa", "out_trade_no": "123456", "notify_url": "http://wwww.xx.com", "amount": "10.00", "desc": "", "time": 1640995200, "sign": "aaaaaa", "ext": { "city": "city1", "province": "province1", "accountNumber": "accountNumber1", "accountName": "accountName1", "subbranch": "subbranch1", "bankName": "bankName1" } }'

Form格式请求示例

curl --location --request POST 'http://xxxxx/api/payment' \ --form 'product_id="1"' \ --form 'app_id="aaa"' \ --form 'out_trade_no="123456"' \ --form 'notify_url="http://wwww.xx.com"' \ --form 'amount="10.00"' \ --form 'desc=""' \ --form 'time="1640995200"' \ --form 'sign="aaaaaa"' \ --form 'ext["city"]="city1"' \ --form 'ext["province"]="province1"' \ --form 'ext["accountNumber"]="accountNumber1"' \ --form 'ext["accountName"]="accountName1"' \ --form 'ext["subbranch"]="subbranch1"' \ --form 'ext["bankName"]="bankName1"'

返回示例

{ "code": 200, "message": "OK", "data": { "trade_no": 1234567890123456, "product_id": 1, "app_id": "abcdenfg", "out_trade_no": "abc1234567890", "trade_status": -1, "amount": "10.00", "real_amount": 0, "desc": "", "complete_time": "" } }

代付回调

代付处理完成后，系统会向您提供的notify_url发送处理结果通知。

通知方式：
  • 请求方式: POST
  • 数据格式: form-data
  • 成功返回: 返回小写 success 表示成功

通知参数

参数 描述 类型 示例
trade_no 平台订单编号 String 2001101011
product_id 产品渠道ID int 123
app_id 开发者ID String 2001101011
out_trade_no 客户端订单号 String 123456789
trade_status 交易状态:1成功,-1处理中,2失败 int 1
amount 订单金额(单位:元) String 100.00
real_amount 订单实际金额(单位:元) String 100.00
complete_time 完成时间 时间字符串 2000-12-16 10:20:37
message 订单失败时候返回信息 String 默认:-
desc 订单描述,原样返回 String abc
time 当前请求秒级时间戳 int 1500001234
sign 接口签名 String 5cdf1c679b4a2ec216bc339d6edb1f45

代付查询

主动查询代付订单状态。

POST /api/payment/status

请求参数

参数 描述 类型 是否必填 示例
app_id 开发者ID String 是 2001101011
out_trade_no 客户端订单号 String 是 123456789
time 当前请求秒级时间戳 int 是 1500001234
sign 接口签名 String 是 5cdf1c679b4a2ec216bc339d6edb1f45

成功返回示例

{ "code": 200, "message": "OK", "data": { "trade_no": 1234567890123456, "product_id": 1, "app_id": "abcdenfg", "out_trade_no": "abc1234567890", "trade_status": 1, "amount": "10.00", "real_amount": "10.00", "desc": "abc", "complete_time": "2022-01-01 11:30:01" } }

错误返回示例

{ "code": 10400, "message": "订单不存在" }
↑