二、API接口
#.1.1 支付请求接口 描述:
method: POST
contenttype: application/x-www-form-urlencoded
示例URL: https://lucktopay.work/PayOrder/payOrderApi
请求参数
| 参数名 |
参数描述 |
数据类型 |
最大长度 |
出现要求 |
是否签名 |
备注 |
| partner |
渠道号(user_pid) |
String |
15 |
M |
是 |
需与上游沟通获取商户后台的pid |
| user_seller |
商户号(user_seller) |
String |
6 |
M |
是 |
需与上游沟通获取商户后台的user_seller |
| out_order_no |
外部订单号 |
String |
50 |
M |
是 |
由商户系统订单,唯一不重复 |
| subject |
商品名称 |
String |
30 |
M |
是 |
用户商品名称 |
| category |
商品分类 |
String |
30 |
M |
否 |
用户商品分类 |
| sku |
商品sku |
String |
30 |
M |
否 |
用户商品sku |
total_fee |
订单金额 |
String |
20 |
M |
是 |
单位美元,两位小数,没有固定上下限制 |
| notify_url |
异步回调地址 |
String |
100 |
M |
是 |
填商户需要接收异步通知的地址 |
| return_url |
同步回调地址 |
String |
100 |
O |
否 |
填商户需要接收通不通知的地址 |
| payment_code |
通道id |
String |
30 |
M |
是 |
通道id需与上游沟通获取 |
| bank_code |
编码 |
String |
30 |
O |
否 |
编码 |
| user_info |
客户信息,详见1.1 客户信息参数说明 |
Array |
|
O |
否 |
payment_code:144,145,146必填 |
| device_info |
客户下单设备的信息,详见1.2 客户设备信息参数说明 |
Array |
|
O |
否 |
payment_code:144,145,146必填 |
| domain |
商户提交域名 |
String |
50 |
M |
是 |
如pay.51thinks.com,需要对接前在后台提交审核 |
sign |
签名 |
String |
|
M |
否 |
用于请求校验 |
1.1 客户信息参数说明
| card_no |
信用卡号 |
String |
30 |
M |
否 |
13-19位数字 |
| expiry |
有效期 |
String |
20 |
M |
否 |
格式MMYY |
| cvc |
CVC码 |
String |
5 |
M |
否 |
3-4位数字 |
| holder |
持卡人姓名 |
String |
30 |
M |
否 |
|
| email |
买家邮箱 |
String |
50 |
M |
否 |
买家邮箱 |
| billing |
地址/账单信息详见 1.1.2 地址/账单信息参数 |
array |
|
M |
否 |
|
1.1.2 账单信息参数说明
| first_name |
账单人名 |
String |
30 |
M |
否 |
|
| last_name |
账单人姓 |
String |
30 |
M |
否 |
|
| phone |
账单电话号码 |
String |
30 |
M |
否 |
|
| address1 |
账单地址1 |
String |
255 |
M |
否 |
|
| city |
账单城市 |
String |
30 |
M |
否 |
|
| state |
账单州/省 |
String |
30 |
M |
否 |
|
| country |
账单国家代码 |
String |
10 |
M |
否 |
查看四.国家代码:两位字母代码 |
| postal_code |
账单地址邮编 |
String |
30 |
M |
否 |
|
1.2 设备信息参数说明
| client_ip |
客户端IP地址 |
String |
30 |
M |
否 |
|
| user_agent |
浏览器信息 |
String |
255 |
M |
否 |
|
签名规则:
签名方法未md5 小写
待签字符串:按照“参数=参数值”的模式用“&”字符拼接成字符串,最后直接拼接秘钥
顺序需和下面数组一致:
$parameter = array(
"notify_url" => 'http://www.test.com/notify_url.php',
"out_order_no" => '1233',
"partner" => '1234567899876111',
"subject" => '123',
"total_fee" => '1.00',
"user_seller" => '666666',
"payment_code" => '101',
"domain" => 'www.test.com',
);
待签字符串示例:
notify_url=http://www.test.com/notify_url.php&out_order_no=1233&partner=1234567899876111
&subject=123&total_fee=1.00&user_seller=666666&payment_code=243&domain=www.test.com
假设秘钥为=>YDNKNDK最终签名字符串:
notify_url=http://www.test.com/notify_url.php&out_order_no=1233&partner=1234567899876111
&return_url=http://www.test.com/return_url.php&subject=123&total_fee=1.00&user_seller=666666&payment_code=243&domain=www.test.comYDNKNDK
返参说明:
| 参数名 |
参数描述 |
数据类型 |
最大长度 |
出现要求 |
是否签名 |
备注 |
| code |
提交状态 |
String |
10 |
M |
否 |
1请求成功 ,0请求失败 |
| out_order_no |
外部订单号 |
String |
50 |
O |
是 |
由商户系统订单,唯一不重复 |
| submit_status |
提交状态 |
String |
10 |
M |
否 |
SUCCESS 提交成功 0001提交失败 |
| msg |
状态描述 |
String |
20 |
O |
否 |
失败原因 |
| total_fee |
订单金额 |
String |
20 |
O |
是 |
单位元(submit_status等于SUCCESS才返回) |
| payUrl |
订单金额 |
String |
20 |
O |
否 |
支付地址(submit_status等于SUCCESS才返回) |
| sign |
签名 |
String |
|
O |
否 |
用于返回校验(submit_status等于SUCCESS才返回) |
签名规则:
签名方法未md5 小写
待签字符串: out_order_no total_fee user_pid 得到字符串,最后直接拼接秘钥
待签字符串示例:
M202015326521100.001234567899876111
假设秘钥为=>YDNKNDK最终签名字符串:
M202015326521100.001234567899876111YDNKNDK
#.1.2 支付回调接口 描述:异步回调为准
method: POST
contenttype: application/x-www-form-urlencoded
URL: http://www.test.html(商户上送地址)
注意: 回调会多次,返回小写success,停止回调
返参说明:
| 参数名 |
参数描述 |
数据类型 |
最大长度 |
出现要求 |
是否签名 |
备注 |
| out_order_no |
外部订单号 |
String |
50 |
M |
是 |
由商户系统订单,唯一不重复 |
| total_fee |
订单金额 |
String |
20 |
M |
是 |
单位元 |
| trade_no |
平台订单号 |
String |
30 |
M |
是 |
如:M202018659952 |
| trade_status |
订单状态 |
String |
20 |
M |
是 |
TRADE_SUCCESS成功 目前仅通知成功订单 |
| sign |
签名 |
String |
|
M |
否 |
用于返回校验 |
签名规则:
签名方法未md5 小写
待签字符串安以下参数的顺序直接拼接值:out_order_no、total_fee、trade_status、partner(商户后台pid)、key(支付秘钥)
待签字符串示例:
order16125940151.00M202018659952TRADE_SUCCESS1234567899876111YDNKNDK
#.1.3 支付查询接口 描述:请求和返回的请求方法和数据类型一致
method: POST
contenttype: application/json
示例URL: https://lucktopay.work/Api/orderQuery
请求参数说明:
| 参数名 |
参数描述 |
数据类型 |
最大长度 |
出现要求 |
是否签名 |
备注 |
| partner |
渠道号 |
String |
15 |
M |
是 |
需与上游沟通获取商户后台的pid |
| user_seller |
商户号 |
String |
6 |
M |
是 |
需与上游沟通获取商户后台的user_seller |
| out_order_no |
外部订单号 |
String |
50 |
M |
是 |
由商户系统订单,唯一不重复 |
| sign |
签名 |
String |
|
M |
否 |
用于请求校验 |
签名规则:
签名方法未md5 小写
待签字符串: 所有参与签名的参数按照Key的ASNI升序顺序,以Key=Value方式组成字符串,字符串之间以&符号连接 得到字符串,最后直接拼接秘钥
待签字符串示例:
out_order_no=20200203254654&partner=585608675758449&user_seller=256365
假设秘钥为=>YDNKNDK最终签名字符串:
out_order_no=20200203254654&partner=585608675758449&user_seller=256365YDNKNDK
返参说明:
| 参数名 |
参数描述 |
数据类型 |
最大长度 |
出现要求 |
是否签名 |
备注 |
| user_seller |
商户号 |
String |
6 |
M |
是 |
需与上游沟通获取商户后台的user_seller |
| out_order_no |
外部订单号 |
String |
50 |
M |
是 |
由商户系统订单,唯一不重复 |
| code |
查询状态 |
String |
10 |
M |
是 |
0000 查询成功 0001 查询失败(此时就返回code和msg) |
| status |
订单状态 |
String |
20 |
M |
是 |
订单状态 0000 支付成功 0001 未支付 |
| msg |
状态描述 |
String |
20 |
M |
是 |
失败原因 |
| order_no |
平台订单号 |
String |
30 |
O |
是 |
如:M202018659952(code等于0000且订单存在的时候存在) |
| money |
订单金额 |
String |
20 |
O |
是 |
单位元(code等于0000且订单存在的时候存在) |
| sign |
签名 |
String |
|
M |
否 |
用于返回校验 |
签名规则:
签名方法未md5 小写
待签字符串: 所有参与签名的参数按照Key的ASNI升序顺序,以Key=Value方式组成字符串,字符串之间以&符号连接 得到字符串,最后直接拼接秘钥
待签字符串示例:
code=0000&money=100.00&msg=未支付&order_no=M202015326521&out_order_no=O202015326521&status=0001&user_seller=284210
假设秘钥为=>YDNKNDK最终签名字符串:
code=0000&money=100.00&msg=未支付&order_no=M202015326521&out_order_no=O202015326521&status=0001&user_seller=284210YDNKNDK
#.1.3 代付请求接口 描述:请求和返回的请求方法和数据类型一致
method: POST
contenttype: application/json
示例URL: https://lucktopay.work/Api/cash
请求参数
| 参数名 |
参数描述 |
数据类型 |
最大长度 |
出现要求 |
是否签名 |
备注 |
| partner |
商户pid |
String |
15 |
M |
是 |
需与上游沟通获取商户后台的pid |
| user_seller |
商户号 |
String |
6 |
M |
是 |
需与上游沟通获取商户后台的user_seller |
| order_no |
外部订单号 |
String |
50 |
M |
是 |
由商户系统订单,唯一不重复 |
| sign_type |
签名类型 |
String |
10 |
M |
是 |
固定值:RSA-S |
| api_version |
版本 |
String |
5 |
M |
是 |
固定值:1.1 |
| money |
订单金额 |
String |
20 |
M |
是 |
单位元 不支持小数 |
| name |
收款账号名 |
String |
30 |
M |
是 |
如:张三 |
| bank_code |
收款账号银行编码/钱包编码/银行名称 |
String |
20 |
M |
是 |
通道101,108,看第四点银行编码
110,112 ,119 上送银行名称
113,114 欧元,英镑上送swiftBic(Swift or BIC)
通道115看菲律宾115银行编码 通道126看泰国126银行编码 尼日利亚 129 通道137看泰国137银行编码 通道140看菲律宾140银行编码 其他通道上送001) |
| bank_no |
收款账号号码/PIX账号/ 巴西cpf/cnpj |
String |
20 |
M |
是 |
如:6211100256622/ |
| notify_url |
异步回调地址 |
String |
100 |
O |
是 |
填商户需要接收异步通知的地址 |
| pay_type |
收款方交易类型(IMPS、NEFT、RTGS、UPI、PAYTM)
巴西通道111,128 130:PIX代付,需要填写,分为CPF, CNPJ, PHONE, EMAIL。(130 还支持EVP)需要让收款人自己选择这其中之一
通道119:1为银行卡2为upi |
String |
20 |
O |
是 |
通道102 ,111 119 128 130需要上送 |
| ifsc |
收款方账号IFSC。交易类型为IMPS、NEFT、RTGS时,此为必传项
巴西代付必须填写收款人税号,相当于身份ID,11位或14位 |
String |
100 |
O |
是 |
通道102,103,110 ,111,112 119 128 130 需要上送 |
| email |
受益人邮箱 |
String |
50 |
O |
是 |
通道102, 119 需要上送 |
| mobile |
受益人手机 |
String |
50 |
O |
是 |
通道102 ,119 需要上送 |
| routing_number |
美元上送美国银行账户路由/澳大利亚上送短码:例如:063-097 |
String |
50 |
O |
是 |
通道113,114 美元,澳大利亚需要上送 |
| address |
受益人地址 |
String |
50 |
O |
是 |
通道113,114,119 需要上送 |
| fast_name |
受益人姓名 |
String |
50 |
O |
是 |
通道113,114 需要上送 |
| last_name |
受益人姓名 |
String |
50 |
O |
是 |
通道113,114 需要上送 |
| country |
国家代码 (Alpha 2 https://www.iban.com/country-codes) |
String |
50 |
O |
是 |
通道113,114 需要上送 |
| sign |
签名 |
String |
|
M |
否 |
用于请求校验 |
签名规则:
签名算法使用MD5withRSA算法,我方和渠道伙伴需交换RSA数字证书公钥用于验证签名.
签名时,使用RSA数字证书私钥对签名参数串进行签名,RSA密用2048位及以上的,
将签名值使用BASE64转码后填充到报文的数字签名域(sing)。
验证签名时,使用对方颁发的RSA数字证书公钥进行验签
根据HTTP协议要求,传递参数的值中如果存在特殊字符(如:&、@等),
那么该值需要做URL Encoding,这样请求接收方才能接收到正确的参数值。
这种情况下,待签名数据应该是原生值而不是encoding之后的值。
例如:调用某接口需要对请求参数email进行数字签名,那么待签名数据应该是
email=test@msn.com,而不是email=test%40msn.com。
对参与签名的非空参数。每一个值从a到z的顺序排序,若遇到相同首字母,则看第二个字母,以此类推.
待签字符串示例:
address=shanghai.xiaoqu&api_version=1.1&bank_code=ICBC&bank_no=622021406001623055&email=65ee2@sina&ifsc=952666ss&mobile=905261452
&money=1000&name=sangao&order_no=test1234567&partner=305670808723445&sign_type=RSA-S&user_seller=284210
返回参数说明:
| 参数名 |
参数描述 |
数据类型 |
最大长度 |
出现要求 |
是否签名 |
备注 |
| user_seller |
商户号 |
String |
6 |
M |
是 |
需与上游沟通获取商户后台的user_seller |
| order_no |
外部订单号 |
String |
50 |
M |
是 |
由商户系统订单,唯一不重复 |
| money |
订单金额 |
String |
20 |
M |
是 |
单位元 |
| status |
提交状态 |
String |
10 |
M |
是 |
0000成功,0001失败 注意:该状态 仅表示提交成功,订单状态查询获取 |
| msg |
状态描述 |
String |
20 |
M |
是 |
如:余额不足 |
| sign |
签名 |
String |
|
M |
否 |
用于返回校验 |
待签字符串示例:
money=1000&msg=Paid successful&order_no=20200203254654&status=0000&user_seller=256365
#.1.4 代付回调接口 描述:代付订单回调
method: POST
contenttype: application/x-www-form-urlencoded
URL: http://www.test.html(商户上送地址)
注意: 回调会多次,返回小写success,停止回调
返参说明:
| 参数名 |
参数描述 |
数据类型 |
最大长度 |
出现要求 |
是否签名 |
备注 |
| out_order_no |
外部订单号 |
String |
50 |
M |
是 |
由商户系统订单,唯一不重复 |
| total_fee |
订单金额 |
String |
20 |
M |
是 |
单位元 |
| trade_no |
平台订单号 |
String |
30 |
M |
是 |
如:M202018659952 |
| trade_status |
订单状态 |
String |
20 |
M |
是 |
TRADE_SUCCESS成功 TRADE_FAIL 失败 |
| sign |
签名 |
String |
|
M |
否 |
用于返回校验 |
签名规则:
签名方法未md5 小写
待签字符串安以下参数的顺序直接拼接值:out_order_no、total_fee、trade_status、partner(商户后台pid)、key(支付秘钥)
待签字符串示例:
order16125940151.00M202018659952TRADE_SUCCESS1234567899876111YDNKNDK
#.1.5 代付查询接口 描述:请求和返回的请求方法和数据类型一致
method: POST
contenttype: application/json
示例URL: https://lucktopay.work/Api/cashQuery
请求参数说明:
| 参数名 |
参数描述 |
数据类型 |
最大长度 |
出现要求 |
是否签名 |
备注 |
| partner |
渠道号 |
String |
15 |
M |
是 |
需与上游沟通获取商户后台的pid |
| user_seller |
商户号 |
String |
6 |
M |
是 |
需与上游沟通获取商户后台的user_seller |
| order_no |
外部订单号 |
String |
50 |
M |
是 |
由商户系统订单,唯一不重复 |
| sign_type |
签名类型 |
String |
10 |
M |
是 |
固定值:RSA-S |
| api_version |
版本 |
String |
5 |
M |
是 |
固定值:1.1 |
| sign |
签名 |
String |
|
M |
否 |
用于请求校验 |
待签字符串示例:
api_version=1.1&order_no=20200203254654&partner=585608675758449&sign_type=RSA-S&user_seller=256365
返回参数说明:
| 参数名 |
参数描述 |
数据类型 |
最大长度 |
出现要求 |
是否签名 |
备注 |
| user_seller |
商户号 |
String |
6 |
M |
是 |
需与上游沟通获取商户后台的user_seller |
| order_no |
外部订单号 |
String |
50 |
M |
是 |
由商户系统订单,唯一不重复 |
| money |
订单金额 |
String |
20 |
M |
是 |
单位元 |
| status |
提交状态 |
String |
10 |
M |
是 |
0000订单成功,0001请求失败(请求本身,不是订单失败)
0002 订单处理中 0003 订单不存在 0004 订单失败
0005 未知错误(不是订单失败,具体联系运营处理) |
| msg |
状态描述 |
String |
20 |
M |
是 |
如:余额不足 |
| sign |
签名 |
String |
|
M |
否 |
用于返回校验 |
待签字符串示例:
money=1000&msg=successful&order_no=20200203254654&status=0000&user_seller=256365
#.1.6 余额查询接口 描述:请求和返回的请求方法和数据类型一致
method: POST
contenttype: application/json
示例URL: https://lucktopay.work/Api/moneyQuery
请求参数说明:
| 参数名 |
参数描述 |
数据类型 |
最大长度 |
出现要求 |
是否签名 |
备注 |
| partner |
渠道号 |
String |
15 |
M |
是 |
需与上游沟通获取商户后台的pid |
| user_seller |
商户号 |
String |
6 |
M |
是 |
需与上游沟通获取商户后台的user_seller |
| sign_type |
签名类型 |
String |
10 |
M |
是 |
固定值:RSA-S |
| api_version |
版本 |
String |
5 |
M |
是 |
固定值:1.1 |
| sign |
签名 |
String |
|
M |
否 |
用于请求校验 |
待签字符串示例:
api_version=1.1&partner=585608675758449&sign_type=RSA-S&user_seller=256365
返回参数说明:
| 参数名 |
参数描述 |
数据类型 |
最大长度 |
出现要求 |
是否签名 |
备注 |
| user_seller |
商户号 |
String |
6 |
M |
是 |
需与上游沟通获取商户后台的user_seller |
| total |
总额 |
String |
20 |
M |
是 |
单位元 |
| use_money |
可用余额 |
String |
20 |
M |
是 |
单位元 |
| status |
查询状态 |
String |
10 |
M |
是 |
0001 请求错误,具体原因看msg
0002查询成功
0003 查询错误 |
| msg |
状态描述 |
String |
20 |
M |
是 |
如:签名错误 |
| sign |
签名 |
String |
|
M |
否 |
用于返回校验 |
待签字符串示例:
msg=查询成功&status=0002&total=34108.86&use_money=34108.86&user_seller=284210
三、常见错误
#.支付请求错误
1. 下单请求参数为空,检查请你去方法是否为post,表单请求。
2. 用户不存在。检查user_seller和partner是否正确,两个是否值填反了。
3. 域名验证失败。检查发起支付的域名是否后台提交并审核通过。域名后台可以提交多个。
域名校验规则:先捕获发起支付的域名,捕获失败。校验参数domain提交的域名(任意后台审核过的域名即可)
4. 签名失败。Rsa公钥需要后台提交(建议用支付宝开放平台开发助手生成秘钥对,选择:RSA2 ,PKCS8(JAVA适用))。
核对参与签名的待签字符串是否正确,rsa加密算法是否为 MD5withRSA
5. 异步通知调试后台可以点击补发通知,测试回调。
#.代付请求错误
1. 下单请求参数为空,检查请你去方法是否为post/json.
2. 代付IP是否提交.