发起付款接口(必用接口)


接口URL:
/api/v1/charges
传参方式:Post表单
请求参数:
# 参数名 含义 类型 必填 说明
1 uid 商户uid string 必填 您的商户唯一标识,注册后在设置里获得。
2 money 订单金额 string 必填 单位:元。精确小数点后2位。例:1021.16
3 channel 支付通道编码 string 必填 指定支付通道编码。具体编码值请在商户后台查看。
5 outTradeNo 商户订单号 string 必填 您的唯一订单ID,必须全局唯一。
6 notifyUrl 通知回调网址 string 必填 用户支付成功后,我们会将支付成功消息以POST请求发送给这个网址。不要urlencode。例:http://www.aaa.com/paysucc_notify
7 returnUrl 跳转网址 string 必填 用户支付成功后,我们会让用户浏览器自动跳转到这个网址。由您自定义。不要urlencode。例:http://www.aaa.com/paysucc_return
8 goodsName 商品名称 string 选填 您的商品名称,可以用来统计商品销售情况。
9 outUserId 付款用户id string 选填 我们会显示在您后台的订单列表中,方便您看到是哪个用户的付款,方便后台对账。强烈建议填写。可以填用户名,也可以填您数据库中的用户uid。例:xxx, xxx@aaa.com
10 outBody 订单附加信息 string 选填 商户给该笔订单的附加信息,我们会在付款成功回调的时候原样返回。可以用来实现灵活的业务控制
11 channelAccount 指定下单收款账号 string 选填 指定下单收款账号,方便用户自由控制轮询逻辑
12 payMode 支付模式 string 选填 支付模式。支持传多个以英文逗号,分隔 系统将随机选择1个模式。具体值请联系技术
13 timestamp 系统时间戳 string 必填 当前系统时间戳(单位毫秒
14 sign 签名 string 必填 签名参数。把使用到的所有参数(sign本身和路径path参数除外)连同参数token一起,按参数名字母升序排序。然后按key1=value1&key2=value2形式拼接在一起。最后md5-32位加密取字符串大写得到sign参数字符串。注意不要urlencode

注意:token在安全上非常重要,一定不要显示在任何网页代码、网址参数中。只可以放在服务端。计算sign时,先在服务端计算好,把计算出来的sign传出来。严禁在客户端计算sign,严禁在客户端存储token。

SIGN参数签名的步骤如下:

第一步,设所有发送或者接收到的数据为集合M,将集合M内非空参数值的参数按照参数名ASCII码从小到大排序(字典序),使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串stringA。

特别注意以下重要规则:

  • 参数token参与计算签名时要一起按字典排序而不是直接加在最后面;

  • 参数名ASCII码从小到大排序(字典升序);
  • 网址类型的参数注意不要urlencode编码;
  • 参数名区分大小写;
  • 接口URL路径上的path参数不要参与签名;

第二步,对stringA进行MD5 32位大写计算,得到sign值。

参与签名计算参数示例:

channel=alipay_wxhb&money=100.00¬ifyUrl=http://paytest.xxx.com/api/payproject/notify/101/1320&outTradeNo=100309111638apay101d1af&returnUrl=http://paytest.xxx.com/api/payproject/callback/101/1320×tamp=1583723798594&token=20450cab4d0e499fb54eb9c03aab57b4&uid=443451373061661864
			
响应参数:
# 参数名 含义 类型 说明
1 code 返回码 int(32) 0表示接口调用正常。非0表示异常
2 msg 提示信息 string 对应返回码code的提示信息。
3 timestamp 时间戳 int(64) 服务器时间戳,可用来校时。
4 version 接口版本 string 用途暂时保留
5 data 数据对象 object
请求成功时返回示例:
{
  "code": 0,
  "msg": "调用成功。",
  "timestamp": "1555040027820",
  "version": "1.0",
  "data": {
	// 通道类型
    "channelType": "alipay",
	// 通道名称
    "channel": "alipay_hb",
	// 订单金额。单位:元。精确小数点后2位。例:1030.00
    "money": "0.01",
	// 用户实际需要支付的金额。单位:元。精确小数点后2位。例:1021.16
    "realMoney": "0.01",
	// 平台返回的订单号
    "tradeNo": "323232553241366528",
	// 商户自己的唯一订单号
    "outTradeNo": "APP323232553119731712",
	// 订单状态:1待支付,2支付成功,3已关闭
    "status": 2,
	// 支付地址。商户需要展示该地址给付款用户
    "payUrl": "https://www.xxxx.com/payment.html?p=DgLlHVQqblKNh242vXDGU/14wY72CQlB6Kjq7+kcTaWTrRBr/7AwjoPawz9fqO1v6yw&t=alipay",
    // 付款二维码图片地址。
	"qrcodeUrl": "https://www.xxxx.com/upload/qrcode/d58ecb9bf1734967a7e124f6605d59cfac.jpg",
	// 付款二维码图片内容。
    "qrcodeContent": "https://www.xxxx.com//pay/v1/go_pay?p=DgLlHVQqblKNh75643vXDGU/14wY72CQlB6Kjq7+kcTaWTrRBr/7AwjoPawz9fqO1v6yw&t=alipay",
    // 是否支付成功
	"paySucc": true,
    // 是否回调成功
	"notifySucc": true,
    // 订单有效截止时间yyyy-MM-dd HH:mm:ss,超出无法支付。默认5分钟
	"validTime": "2019-04-11 23:00:46",
    // 订单有效截止时间戳(毫秒),超出无法支付。默认5分钟
	"validTimeMills": "1554994846000"
  }
}
请求失败时返回示例:
{
  "code": 1012,
  "msg": "通道不存在或者不可用。",
  "data": null,
  "timestamp": "1554210357457",
  "version": "1.0"
}

付款成功回调通知


用户付款成功后,我们会向您在发起付款接口传入的notify_url网址发送通知。您的服务器只要返回内容:SUCCESS(注意是大写),就表示回调已收到。如果返回内容不是SUCCESS,我们会在10分钟内尝试回调3次。

即使在3次回调仍然失败的情况下,您还可以通过查询订单接口来获取支付状态后进行相应补单业务。

传参方式:Post表单
参数内容:
# 参数名 含义 类型 是否必填 说明
1 channel 支付通道编码 string 必填 商户下单时的支付通道编码
2 tradeNo 平台订单号 string 必填 订单支付金额
3 outTradeNo 商户自己的订单号 string 必填 商户下单时的私有唯一订单号
4 money 订单金额 string 必填 单位元。商户下单时的金额
5 realMoney 实际订单金额 string 必填 实际收到金额(单位元)。注意,请使用该字段给您的用户进行充值。
6 uid 对应商户uid string 必填
7 outUserId 商户下单时传的自己用户id string
8 outBody 商户下单时传的附加信息 string
9 sign 签名 string 必填 签名算法同上。注意有些参数可能没有,比如outBody。所以请获取所有POST参数进行签名(除了sign字段本身)

付款成功自动跳转


用户付款成功后,我们会先通过调用您下单时填入的notifyUrl接口,通知您服务器付款成功,然后引导用户跳转到returnUrl网址。