交易API文档

2024-09-07 20:48:36 bone

签名方法

获取所有post 请求内容，不包括字节类型参数，如文件、字节流，剔除 sign 字段，剔除值为空的参数；
按照第一个字符的键值 ASCII 码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值 ASCII 码递增排序，以此类推；
将排序后的参数与其对应值，组合成 参数=参数值 的格式，并且把这些参数用 & 字符连接起来，此时生成的字符串为待签名字符串。
>>>加签原理<<<见开发指引

必填参数说明

M = 必填

O = 非必填

C= 条件必填

公共请求参数

所有请求都必须添加公共参数。

变量名	必填	限制	类型	说明
req_id	O	-	String	请求流水号，2023-08-06新增字段，可为空，不入库，用于定位联调时的参数问题，
org_id	O	-	String	代理商机构号，填写机构号后请使用代理商秘钥进行加签与验签
mchid	M	-	String	商户号
appid	O	-	String	应用APPID
method	M	-	String	接口名称
charset	M	-	String	编码格式，请求使用的编码格式，如utf-8,gbk,gb2312等
sign_type	M	-	String	签名方法，目前仅支持RSA2
timestamp	M	-	String	请求时间，请传入当前请求时间的时间戳，10位时间戳格式，如：1688885536，时间戳时区为北京时间，误差上下不允许超过60s
version	M	-	String	版本号，调用的接口版本，固定为：1.0
biz_content	M	-	String	业务参数集合，json格式，最大长度不限，除公共参数外所有业务参数都必须放在这个参数中传递
sign	M	-	String	商户请求参数的签名串

请求地址

参数获取路径：请登录商户后台-系统设置-开发设置获取，地址后缀请添加/

请求地址拼接method

如使用交易下单接口：

如请求地址为：https://www.baidu.com

拼接后为：https://www.baidu.com/pay.order/create

1、统一交易下单接口

1.1接口说明

支持支付宝拉码支付、公众号支付、服务窗支付、银联JS支付、微信小程序支付。

注意：由于微信与支付宝不对间联机构开放H5支付功能权限，如果您使用的是间联渠道将无法使用微信H5与支付宝H5，如需使用H5请调用其他支付方式例如：【微信小程序H5支付=wechatLiteH5】

支付宝H5调用方式：

可使用扫码获取支付链接后，直接使用浏览器打开该链接即可自动调起支付宝H5支付

如果是APP内或者部分浏览器无法打开的情况下，可使用js调起支付宝客户端后进行支付

方法一：alipays://platformapi/startapp?appId=20000067&url=支付url例：alipays://platformapi/startapp?appId=20000067&url=https://www.baidu.com

方法二：alipays://platformapi/startapp?saId=10000007&clientVersion=3.7.0.0718&qrcode=支付url

例：alipays://platformapi/startapp?saId=10000007&clientVersion=3.7.0.0718&qrcode=https://www.baidu.com

银联云闪付H5调用方式：

可使用扫码获取支付链接后，使用js调起云闪付客户端后进行支付

upwallet://html/' +payurl.replace('https://','').replace( 'http://’,'')

其中payurl为获取的支付链接

1.2请求方式

POST

1.3接口名称

method = pay.order/create

1.4业务参数

公共请求参数内的biz_content业务参数集合，json格式

变量名	必填	限制	类型	说明
channel_code	O	-	String	支付渠道代码，支付渠道代码，请查看后台商户进件管理内，填写后将只轮训该渠道下进件的子商户号
trade_type	M	-	String	支付方式编码，请查看支付方式
pay_channel_id	O	-	String	通道ID，可在商户后台→通道列表内查看，留空则为商户池轮询模式
out_trade_no	M	-	String	商户订单号，由商家自定义，15-64个字符，仅支持字母、数字、下划线且需保证全局不重复（我司系统内唯一）
total_amount	M	-	String	订单金额，单位为元，精确到小数点后两位，取值范围：[0.01,100000000] 。
subject	M	-	String	订单标题，注意：不可使用特殊字符，如 /，=，& 等，禁止使用与商品无关的内容也只能是商品名称相关的内容，禁止有任何诱导规避投诉的内容
attach	O	-	String	附加参数，原样返回
sub_appid	C	-	String	微信公众号/小程序APPID，原生支付必传
user_id	C	-	String	用户标识，微信openid 支付宝userid 银联云闪付upUserId，微信公众号/小程序，支付宝生活号/小程序/js，云闪付JS，原生支付必传项
notify_url	M	-	String	支付结果异步通知地址，外网可访问地址
return_url	O	-	String	支付完成跳转地址,仅支持非原生支付，快捷支付，网银等支持同步跳转的支付类型
client_ip	M	-	String	支付用户的真实ip地址,目前仅支持传入ipv4地址，不支持识别ipv6，请不要传入商户服务器的ip地址，系统将会风控鉴权
channe_expend	C	-	String	渠道拓展参数，请查看下面具体参数
time_expire	O	-	String	订单失效时间格式10位时间戳，如不传默认为30分钟后自动失效
fund_process_type	C	-	int	分账标识，0=订单不分账，1=订单分账，不传默认为不分账，如果是订单分账则，分账串必传，该字段与后台设定默认分账渠道关联，如后台有默认分账规则，则以本次请求接口为准将会忽略系统默认分账规则，如为不分账，系统将会自动调用系统内设定的默认分账
divide_detail	C	-	String	分账详情，JSON字符串，具体参考下方说明
auth_code	C	-	String	扫码设备读出的条形码或者二维码信息，反扫必传

channe_expend 参数表

变量名	必填	限制	类型	说明
is_raw	O	-	String	是否原生支付，1=原生支付，0=非原生支付，默认非原生支付，支付类型为wechatPub ,wechatLite,alipayLite ,alipayPub 可选项，其他无效
wechat_h5_type	O	-	String	微信H5支付方式，1=原生支付，2=小程序H5，3=微信客服H5支付，不填写默认跟随我司系统默认支付方式，支付类型为wechatWap 可选项，其他无效
bank_card_no	O	-	String	支付银行卡号，使用汇付斗拱渠道支付类型为：银联H5（unionOnline）时必传
pay_scene	O	-	String	场景类型（目前仅汇付斗拱渠道有效），01=A通道，02=B通道，03=非盈利行业费，04=缴费行业费率，05=保险行汪费率，06=行业（蓝海绿洲）活动场景费率，07=校园餐饮费率，08=K12中小幼费率，09=非在线教培行业费率

divide_detail[]参数表 JSON字符串(数组)

变量名	必填	限制	类型	说明
account	M	-	String	分账用户id，分账用户渠道分账账号，须提前报备
amount	M	-	String	分账金额单位元，保留两位小数，不能超过渠道限额分账总比例
fee_flag	O	-	String	手续费承担方是否手续费承担方，N-否，Y-是，手续费承担方有且只能有一个
description	O	-	String	分账说明

1.5返回参数

变量名	必填	限制	类型	说明
code	M	无	string	返回状态码1 - 成功，非1 - 失败
msg	C	无	string	返回错误信息
data	M	无	string	业务返回参数，请查看下方具体参数

data参数表

变量名	必填	限制	类型	说明
mchid	M	无	string	商户号
out_trade_no	M	无	string	商户订单号
trade_no	M	无	string	平台订单号
total_amount	M	无	string	订单金额
float_amount	M	无	string	实际支付金额
payurl	C	无	string	订单支付URL
payInfo	C	无	string	JS支付信息串
trade_type	M	无	string	支付方式

2、支付结果

2.1、支付结果通知

由于诸多因素都会影响到支付结果的通知，推送可能存在延迟，并且不能保证100%推送成功。故强烈建议主接交易查询接口，并且需要做好系统重复通知的幂处理方案，以免造成重复入账。

POST Content-Type: text; charset=utf-8

通知参数

所有通知参数除空值与签名串外均需要加入验签字段，通知参数后期可能会根据情况增加，在验证签名时请注意

接收到通知结果并处理成功后需返回“success”或者全部大写

回调验签注意请使用平台公钥进行验签，通知的所有参数除去空值与sign值外均需要加入验签字段，禁止固定写死验签字段，验签方法可参考支付宝官方的demo进行，

验签失败一般有以下几个原因

1.把商户公钥当平台公钥填写到系统了，检查是否填错回调验签是需要配置平台公钥的

2.拼接字符串有问题，查看下是否是所有通知参数除空值与签名串外均需要加入验签字段，

3.一般按照加签规则进行反推即可

参数名	变量名	必填	限制	类型	说明
商户号	mchid	M	无	string	交易商户号
签名方法	sign_type	M	10	string	一般为RSA2
商户订单号	out_trade_no	M	32	string	商户提交的订单号
机构订单号	trade_no	M	10	string	机构订单号
通道订单号	channel_order_sn	M	无	string	微信、支付宝、等通道的订单号
订单金额	total_amount	M	32	string
通道ID	pay_channel_id	M	64	string
支付渠道代码	channel_code	M	无	string
支付类型	trade_type	M	无	string
订单分账标识	fund_process_type	M	无	string
订单标题	subject	M	无	string
附加字段	attach	M	无	string
通知时间	notify_time	M	无	string
订单状态	order_status	M	无	string	PROCESSING=订单待支付，SUCCESS=订单支付成功，TIME_OUT=订单已过期，FAIL=订单支付失败，CLOSE=订单关闭,CALL_FAIL=支付成功未返回
签名	sign	M	无	string

2.2、交易结果查询

此接口查询有频率限制，10秒内同一笔订单号限制查询一次，如超出限制系统将会对访问IP对该接口的调用做封禁10分钟处理，当天多次超出以封禁次数*10做封禁时间处理

2.2.1请求方式

POST

2.2.2接口名称

method = pay.order/query

2.2.3业务参数

公共请求参数内的biz_content业务参数集合，json格式

变量名	必填	限制	类型	说明
out_trade_no	C	-	String	商户订单号，与平台订单号二选一
trade_no	C	-	String	平台订单号，与商户订单号二选一

2.2.4返回参数

变量名	必填	限制	类型	说明
code	M	无	string	返回状态码1 - 成功，非1 - 失败
msg	C	无	string	返回错误信息
data	M	无	string	业务返回参数，与支付结果通知参数一致

3、退款

3.1订单退款

3.1.1接口说明

系统支持对已支付订单进行多笔不同金额的退款，需保证商户退款订单号不重复，退款金额不允许超过订单金额，异步通知地址为预留字段，后期将会增加退款成功后同步通知到商户服务器

3.1.2请求方式

POST

3.1.3接口名称

method = pay.order/refund

3.1.4业务参数

公共请求参数内的biz_content业务参数集合，json格式

变量名	必填	限制	类型	说明
refund_amount	M	-	String	退款金额
refund_reason	M	-	String	退款说明
out_refund_no	M	-	String	商户退款请求流水号，不可重复
out_trade_no	C	-	String	商户订单号，与trade_no平台订单号二选一
trade_no	C	-	String	平台订单号，与out_trade_no商户订单号二选一
notify_url	C	-	String	异步通知地址

3.1.5返回参数

变量名	必填	限制	类型	说明
code	M	无	string	返回状态码1 - 退款请求成功，非1 - 失败
msg	C	无	string	返回错误信息
data	M	无	string	业务返回参数，请查看下方具体参数

data参数表

变量名	必填	限制	类型	说明
mchid	M	无	string	商户号
trade_no	M	无	string	商户订单号
refund_amount	M	无	string	本次退款金额
refund_reason	M	无	string	退款说明
out_refund_no	M	无	string	退款流水号
refund_no	M	无	string	退款订单号
ins_refund_sn	C	无	string	机构退款流水号

3.2退款查询

3.2.1接口说明

3.2.2请求方式

POST

3.2.3接口名称

method = pay.order/refundQuery

3.2.4业务参数

公共请求参数内的biz_content业务参数集合，json格式

变量名	必填	限制	类型	说明
out_trade_no	C	-	String	商户订单号，与trade_no平台订单号二选一
trade_no	C	-	String	平台订单号，与out_trade_no商户订单号二选一
out_refund_no	M	-	String	商户退款请求流水号

3.2.5返回参数

data参数表

变量名	必填	限制	类型	说明
mchid	M	无	string	商户号
out_refund_no	M	无	string	商户退款订单号
refund_no	M	无	string	平台退款订单号
ins_refund_sn	M	无	string	机构退款订单号
channel_refund_sn	M	无	string	通道退款订单号
refund_amount	M	无	string	退款金额
refund_reason	M	无	string	退款说明
refund_status	M	无	string	退款状态
out_trade_no	M	无	string	商户订单号
trade_no	M	无	string	平台订单号

4、支付类型

支付方式	字段	字段说明
支付宝	alipayPc	支付宝电脑
	alipayApp	支付宝APP
	alipayQr	支付宝当面付
	alipayWap	支付宝H5
	alipayLite	支付宝小程序
	alipayPub	支付宝生活号
	alipayScan	支付宝反扫
微信	wechatQr	微信扫码
	wechatPub	微信公众号支付
	wechatLite	微信小程序支付
	wechatScan	微信反扫
	wechatWap	微信H5支付
	wechatLiteH5	微信小程序H5支付
银联	unionApp	银联云闪付APP
	unionQr	银联云闪付扫码
	unionWap	银联云闪付H5支付
	unionScan	银联云闪付反扫
	unionOnline	银联H5支付
快捷	quickPay	快捷支付
网银	obB2c	个人网银支付
网银	obB2b	企业网银支付
数字人民币	dcpay	数字货币支付
QQ	qqQr	QQ扫码支付
QQ	qqWap	QQH5支付

4、错误码（code错误码解决方法）

code码	错误说明	解决方法
0	通用请求错误	请查看msg错误说明，根据提示解决
1	请求成功	接口请求成功
1001	请求接口地址异常	接口参数method异常，请检查该参数是否异常
1002	当前请求方法不存在	接口参数method不存在，请检查该参数是否异常
1003	当前请求方法限制IP	当前客户端IP不在设置的IP白名单内，请检查客户端IP或设置IP白名单

交易API文档

签名方法

必填参数说明

公共请求参数

请求地址

1、统一交易下单接口

1.1接口说明

1.2请求方式

1.3接口名称

1.4业务参数

1.5返回参数

2、支付结果

2.1、支付结果通知

2.2、交易结果查询

2.2.1请求方式

2.2.2接口名称

2.2.3业务参数

2.2.4返回参数

3、退款

3.1订单退款

3.1.1接口说明

3.1.2请求方式

3.1.3接口名称

3.1.4业务参数

3.1.5返回参数

3.2退款查询

3.2.1接口说明

3.2.2请求方式

3.2.3接口名称

3.2.4业务参数

3.2.5返回参数

4、支付类型

4、错误码（code错误码解决方法）

关于我们

公司项目

新闻资讯

公司形象