Skip to main content

支付API对接

支付API对接

统一支付接口，用户应该通过该接口来进行下单，该接口会返回对应的支付链接。

发起支付​

接口说明​

请求URL：请在后台API信息中查看

请求方式：POST

body 指该参数需在请求JSON传参

请求参数​

参数名类型必填描述
body appKeystringyes后台API信息中的appKey
body amountstringyes订单金额
body channelCodestringyes通道编码，详见通道文档
body payModestringyes支付方式，详见通道文档
body orderIdstringyes订单ID
body timestamplong stringyes毫秒级时间戳，有效期为一分钟
body nonceStrstringyes随机字符串，UUID即可
body signTypestringyes签名类型，固定为MD5
body callbackUrlstringyes回调URL
body signstringyes利用MD5签名，不可重复使用
body attachstringno附加信息，会在回调中回传
body payInfojsonstringno支付信息，在某些通道会用到，JSON字符串
签名方法

MD5(appKey+orderId+timestamp+nonceStr+appSecret)，appSecret为后台API信息中的appSecret

参数示例​

{
    "appKey": "ThisIsYourAppKey",
    "amount": "100",
    "channelCode": "THIS_IS_CHANNEL_CODE",
    "payMode": "WX_H5",
    "orderId": "10002022010348281234",
    "timestamp": 1647344736869,
    "nonceStr": "57D1JD8SRH",
    "signType": "MD5",
    "callbackUrl": "http://www.callback-url.com/callback",
    "sign": "3efbb814bf930afd6af301873a7b1ace"
}
注意

上述参数示例中，AppKey为 ThisIsYourAppKey ，AppSecret为 ThisIsYourAppSecret ，签名文本为 ThisIsYourAppKey10002022010348281234164734473686957D1JD8SRHThisIsYourAppSecret

返回示例​

{
    "msg": "操作成功",
    "code": 0, // 状态码为0则为成功，其他皆为异常
    "data": {
        "androidPayUrl": "安卓异步查单的URL，用于获取真实的支付链接，直接用Get请求",
        "iosPayUrl": "IOS异步查单的URL，用于获取真实的支付链接，直接用Get请求",
        "expireTime": "2022-03-16T00:00:00"
    },
    "timestamp": 1647344736869 // 失败时会返回该字段，该字段为服务器当前时间戳
}
注意

下单接口并不会直接返回真实的支付链接，只是给一个异步查询真实链接的URL，应当通过URL获取真实链接

异步查询真实支付链接​

请在支付页面间隔1秒轮询该接口查询真实的支付链接然后进行跳转

接口说明​

请求URL：下单结果中返回的androidPayUrl/iosPayUrl，不再需要任何多余的传参

请求方式：GET

响应参数​

参数名类型描述
body codeint业务状态码，0为正常返回，其他皆为下单失败
body msgstring系统提示信息，返回非0时可参考
body datastring真实的支付URL，code=0且当该字段为空或没有该字段时，代表订单还未下单完成

示例响应​

{
  code: 0,
  msg: '成功',
  data: 'weixin://pay/xxxxxxxx'
}

回调​

回调URL：下单时所传callbackUrl

回调方式：POST

回调时的RequestBody
{
    "attach": "下单时传的attach",
    "orderId": "下单时传的orderId",
    "timestamp": "回调时的毫秒时间戳",
    "sign": "MD5(orderId+timestamp+appSecret)"
}

最佳实践​

被回调时应当校验签名，且保证timestamp和当前时间相差不超过一分钟，如果无法完成校验请返回HttpStatusCode>=300的响应，系统会重新回调

常见问题​

  • Q: 下单提示 签名不可重复使用

  • A: 请保证nonceStr是随机字符串，且每次下单都进行了签名

  • Q: 下单提示 签名过期

  • A: 请检查timestamp和返回的timestamp的时间差，不能超过一分钟

  • Q: 提示通道不支持该金额、通道不支持该支付模式

  • A: 请查阅相关通道文档，并修改对应的amount、payMode