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签名说明 |