API开发文档简介
本文阅读对象:使用 聚合支付 商户自服务系统的技术架构师、研发工程师、系统运维工程师。通过本文档,商户可了解 聚合支付 接入的技术、接入的产品业务、接入的流程、接入规范等信息,以便于商户顺利完成接入工作。
接入网关
请登录商户中心,API管理 开发文档中 查看网关地址和API对接参数。
统一下单接口
提交方式:POST
地址: http://paytest.ccsttoo.com/apisubmit
请求类型:application/x-www-form-urlencoded
参数名称 类型长度 是否必填 参与签名参数说明
version varchar(5) 【版本号】默认1.0
customerid int(8) 【商户编号】商户后台获取
sdorderno varchar(20) 【商户订单号】必须确保唯一性
total_fee decimal(10,2) 【订单金额】单位元。保留两位小数,不足以0占位。且不能出现千位分隔符
paytype varchar(10) API接入不可为空 【支付编号】详见附录1,收银台接入时如果该参数为空、则由用户选择支付方式,否则为固定支付方式
bankcode varchar(10) 网银直连不可为空,其他支付方式可为空 【银行编号】详见附录2
access_type varchar(8) 【接入方式】API接入:API 收银台接入:CHECKOUT
notifyurl varchar(50) 【异步通知URL】不能带有任何参数,且必须是可正常访问的url
returnurl varchar(50) 【同步通知URL】不能带有任何参数,且必须是可正常访问的url
clientip varchar(30) 【clientip】终端ip,建议获取用户ip
remark remark 【订单备注】建议传递商品名称!
name name 【付款人姓名】支付宝实名制需要用到,微信可以随意传内容!若传入参数为张三,用李四的支付宝扫码付款则无法付款。
cert_no cert_no 【付款人身份证号码】支付宝实名制需要用到,微信可以随意传内容!
is_jump bool 【收银台自动跳转】收银台接入时,该字段如果为 true 请求成功直接跳转失败返回错误消息、为 false 则返回参数有由客户端自行判断跳转。为空时不传递、默认值为 true。表单请求可忽略
sign varchar(32) 【md5签名】参照下方md5签名说明
md5签名方法说明:
1、除参数说明中注明不需要参与签名字段外,所有参数按照字段名的ascii码从小到大排序后使用QueryString 的格式 (即 key1=value1&key2=value2…)再拼接上下发的key拼接而成,空值不传递,不参与签名组串。最后对于签名字符串进行MD5加密
2、签名原始串中,字段名和字段值都采用原始值,不进行URLEncode。
3、返回的应答或通知消息可能会由于升级增加参数,请验证应答签名时注意允许这种情况。
例:某渠道key=123qwe,某接口有4个参数都参与签名,ac=xxx,ab=xxx,c=xxx,b=xxx,按照ascii升序拼接后为: ab=xxx&ac=xxx&b=xxx&c=xxx再拼接key得到签名串: ab=xxx&ac=xxx&b=xxx&c=xxx&123qwe 最后对上述字符串进行MD5运算后得到签名sign
返回参数
返回参数建议做好 sign 验签。接入方式为收银台,并且is_jump为true 时。直接跳转没有以下参数返回
请求类型:application/x-www-form-urlencoded
参数名 是否必反 是否签名 参数说明
status 必反 成功返回 OK 该状态仅代表接口调用状态不代表成功状态,成功状态需同时判断 status 与 msg
msg 必反 成功返回 SUCCESS 失败返回错误说明
url 必反 API接入时可直接跳转,通常用于h5支付拉起或者内部浏览器直接拉起支付
img API接入必反 注意判断字符串长度大于100为base64格式二维码图片可直接作用于src属性、判断字符串长度小于100视为url需自行生成二维码
total_fee 必反 订单金额
orderid 必反 平台订单号
sdorderno 必反 商户订单号
customerid 必反 商户号
sign 必反 【md5签名】同接口请求签名
异步通知
通知方式:异步POST、同步GET
请求类型:application/x-www-form-urlencoded
收到通知回复:success 联调时请务必确保异步通知下该参数正常返回。对接务必做好重复通知处理、客户端业务处理成功以及重复通知(已经处理的订单)均需要返回success标识。
若未正常返回 success 标识,系统认定为通知失败,通知失败订单不会参与结算、列入异常订单,并且会在后续自动补发最多10次通知,最后一次通知依然失败会冻结订单。需联系客服解冻后方可再次通知!
参数名称 类型长度 参数说明
status varchar(1) 【订单状态】1:成功,其他失败
customerid varchar(8) 【商户编号】
sdpayno varchar(20) 【平台订单号】
sdorderno varchar(20) 【商户订单号】
total_fee decimal(10,2) 【订单金额】单位元
realmoney decimal(10,3) 【实付金额】单位元
paytype varchar(20) 【支付类型】
remark varchar(50) 【订单备注】
sign varchar(32) 【md5验证签名串】参照签名方法
md5签名方法说明:(按以下格式拼接即可不需要排序)
{value}要替换成接收到的值,{apikey}要替换成平台分配的接入密钥,可在商户后台获取
customerid={value}&status={value}&sdpayno={value}&sdorderno={value}&total_fee={value}&realmoney={value}&paytype={value}&{apikey}
使用md5签名上面拼接好的字符串即可生成小写的32位密文
订单查询接口
提交方式:POST
地址: http://paytest.ccsttoo.com/apiorderquery
请求类型:application/x-www-form-urlencoded
参数名称 类型长度 是否可空 参与签名 参数说明
customerid int(8) 【商户编号】商户后台获取
sdorderno varchar(20) 【商户订单号】要查询的商户订单号
reqtime varchar(14) 【当前时间戳】格式:yyyymmddhhmmss
sign varchar(32) 【md5签名】参照下方md5签名说明
md5签名方法说明:(不需要排序按以下格式拼接即可)
{value}要替换成接收到的值,{apikey}要替换成平台分配的接入密钥,可在商户后台获取

customerid={value}&sdorderno={value}&reqtime={value}&{apikey}

使用md5签名上面拼接好的字符串即可生成小写的32位密文
备注:该接口只能查询最近三天的订单记录

返回数据:
订单成功则返回(示例):{"status":1,"msg":"成功订单","sdorderno":"商户订单号","total_fee":"订单金额","sdpayno":"平台订单号"}
订单未付款或失败返回(示例):{"status":0,"msg":"失败订单"}
附录1
paytype参数值说明: 具体接入方式需联系客服审核开通后方可接入
支付方式名称 支付编号
支付宝 alipay
支付宝H5 alih5
微信H5 wxh5
微信公众号 wxgzh
微信扫码 weixin
银联支付 union
银联H5 unh5
在线网银 bank
附录2
当paytype为bank时,bankcode为以下银行取值:
银行名称 银行编号
中国工商银行 ICBC
中国农业银行 ABC
中国银行 BOCSH
建设银行 CCB
招商银行 CMB
浦发银行 SPDB
广发银行 GDB
交通银行 BOCOM
邮政储蓄银行 PSBC
中信银行 CNCB
民生银行 CMBC
光大银行 CEB
华夏银行 HXB
兴业银行 CIB
上海银行 BOS
上海农商 SRCB
平安银行 PAB
北京银行 BCCB
常见错误代码
错误返回说明:
返回参数 返回说明 排查方案
001 商户不存在 检查商户号是否填写错误
002 商户账号未审核 联系客服检查商户状态
003 商户账号已停用 联系客服检查商户状态
004 商户网站未绑 检查后台绑定的IP或域名是否正确
005 代理账户不允许直接接入 使用普通商户接入
100 商户通道关闭 联系客服开启对应通道或接入其他通道
101 商户通道不存在 联系客服开启对应通道或接入其他通道
102 平台通道关闭 联系客服开启对应通道或接入其他通道
103 平台通道不存在 联系客服开启对应通道或接入其他通道
104 商户API功能未开通 联系客服开启API接口模式或改为收银台模式
105 商户收银台功能未开通 联系客服开启收银台接口模式或改为API接口模式
106 支付方式不存在 检查支付编号是否填写错误
107 接入方式错误 检查支付编号是否填写错误
200 参数不完整 检查是否缺少必填参数
201 Sign验证失败 检查签名方式,以及商户秘钥是否正确
202 订单金额格式错误 参考统一下单接口参数说明
203 订单号长度超过限制(50) 参考统一下单接口参数说明
204 商品信息长度超过限制(30) 参考统一下单接口参数说明
205 订单号已存在 参考统一下单接口参数说明
206 非法接入 联系客服查询商户是否异常
208 非法空值 检查是否缺少必填参数
207 金额超过限定额 联系客服咨询限额
219 金额低于限定金额 联系客服咨询限额
220 金额超过限定金额 联系客服咨询限额
400 频率超限 单IP订单提交过快
501 空的银行编号 检查银行编号是否填写或填写是否正确
502 银行接口维护 联系客服咨询或接入其他接口
503 非法的银行编 检查银行编号是否填写或填写是否正确
504 平台接口不存在 联系客服咨询或接入其他接口
506 非法回调地址 检查回调地址是否填写正确
507 RSA签名异常 【md5签名】参照md5签名说明