vn_pay_demo/src/doc/Api-V1.8.13-converted.txt

商户接入接口文档 
版本 1.8.13
1. 引言 
本文档是接入本平台支付渠道的技术说明文档，供接入方技术人员使用。 
2. 方案概述 
3. 数据规则 
4. 请求地址 
支付测试号：
商户号：见商户后台
密钥：见商户后台 
地址：https://c.gmobvfxllc.com/gateway/api/trade  
接口默认请求以上地址，特殊情况请求地址会在章节里面备注，以章节请求地址为准。 
5. 数字签名 
签名生成的通用步骤如下： 
设所有发送或者接收到的数据为集合 M，将集合 M 内非空参数值的参数按照参数名 ASCII 码 从小到大排序（字典序），使用 URL 键值对的格式（即 key1=value1&key2=value2…）拼接成字符串paramStr
特别注意以下重要规则： 
1. ◆ 参数名 ASCII 码从小到大排序（字典序）； 
2. ◆ 如果参数的值为空不参与签名； 
3. ◆ 参数名区分大小写；
4. ◆ 本平台商户后台提供有加签验证工具； 
5. ◆ 验证调用返回或主动通知签名时，传送的 sign 参数不参与签名，将生成的签名与该 sign 值作校验。 
在paramStr最后拼接上paySecret得到 preSignStr 字符串，并对preSignStr进行 MD5 运算，再将得到的字符串所有字符转换为大写，得到 sign 值。 
  示例： 
假设传送的 json 串如下： 
{ 
"tradeType"="cs.pay.submit",
"version"="2.0", 
"channel"="usdt_pay", 
"mchNo"="99992017122510000542", 
"mchOrderNo"="6666201711151715030245", 
"body"="iphone",
"amount"="50", 
"currency"="VND", 
"remark"="test", 
"timeExpire"="20171115191503", 
"timePaid"="20171115171503", 
"extra"={"notifyUrl":"http://www.xxx.com","callbackUrl":"http://www.xxx.com"} 
}
第一步： 
对参数按照 key=value 的格式，并按照参数名 ASCII 字典序排序， 其中 key 是 extra时需要特殊处理。 
当key是 extra时，把 extra 去掉，把 extra 里面的属性拿出来跟外面的属性一起排序。 
示例中 json 数据的最终的拼装结果如下：
paramStr = "amount=50&body=iphone&callbackUrl=http://www.xxx.com&channel=wx_pub&currency=VND&mchNo=99992017122510000542&mchOrderNo=6666201711151723480245&notifyUrl=http://www.xxx.com&openId=TEST165453&remark=test&timeExpire=20171115192348&timePaid=20171115172348&tradeType=cs.pay.submit&version=1.0"
第二步：拼接 API 密钥： 
preSignStr = paramStr+"&paySecret=b071b69ece214b3d9257fb71640dd776 ";
sign = MD5(preSignStr).toUpperCase();
最终得到发送的数据： 
{ 
"tradeType"="cs.pay.submit",
"version"="2.0", 
"channel"="usdt_pay", 
"mchNo"="99992017122510000542", 
"mchOrderNo"="6666201711151715030245", 
"body"="iphone",
"amount"="50", 
"currency"="VND", 
"remark"="test", 
"timeExpire"="20171115191503", 
"timePaid"="20171115171503", 
"extra"={"notifyUrl":"http://www.xxx.com","callbackUrl":"http://www.xxx.com"}, 
"sign"="xxxxxxxxxxxxxxxx" 
}
6. 接口定义 
6.1  订单预支付接口 
请求参数 
返回参数
6.1.1  网银预支付 
请求扩展参数 
响应扩展参数 
6.2 支付/代付异步通知（本平台请求商户）
注意：异步通知是以JSON 格式（application/json）请求访问商户提供的接口地址. POST请求
请求参数 
返回结果 
返回 success (注意是小写) 表示通知接收成功，本平台将不再通知，返回其他结果会继续通知，一般通知 5次(回调通知可能多次下发，请确保收到回调通知正确处理)。 
通知策略为：0m，1m，2m，5m，15m
6.2.1 页面通知
同后台通知（以后台通知为准）
6.3 订单查询接口
请求参数 
返回结果 
返回结果与后台异步通知结果相同，请查阅后台异步通知请求参数。 
*支付查询返回的payResult与异步通知存在差异，具体值为：
	SUCCESS：支付成功；	 
WAITING_PAYMENT：等待支付；	
FAILED：支付失败；
其他状态请参阅payInfo
6.4 提现/代付接口
请求参数 
响应参数
6.4.1代付查询接口
注意：代付查询必须在代付提交30秒后再进行。
请求参数    
响应参数 
6.6钱包余额查询
请求参数
响应参数 
7. 附件 
7.1 支付渠道 
7.2银行编码
7.3代付状态说明 
7.4接入常见问题 
1. 组合签名的时候，注意extra里的内容要拿出来；提交的时候要装进去；
2. 空值不参与签名;注意值里的空格；
3. 交易请求是用的是form表单，回调返回的是json数据。

=== 表格内容 ===
传输方式 | 为保证交易安全性，采用 HTTPS 传输（测试环境采用 HTTP 传输）
提交方式 | 采用 POST 方法提交
数据格式 | 提交数据使用post，标准form请求；返回数据为 JSON 格式，如有采用其他格式会在章节里备注
字符编码 | 统一采用 UTF-8 字符编码
金额格式 | 单位为分，不能有小数点
签名算法 | MD5
签名要求 | 请求和接收数据均需要校验签名，详细方法请参考数据加密和签名
判断逻辑 | 先判断协议字段返回，再判断业务返回，最后判断交易状态
=== 表格结束 ===


=== 表格内容 ===
字段名 | 变量名 | 必填 | 类型 | 描述
交易类型 | tradeType | 是 | String(32) | 预支付：cs.pay.submit
版本号 | version | 是 | String(8) | 版本号，默认 2.0
支付渠道 | channel | 是 | String(24) | 支付使用的第三方支付产品渠道，见附件<支付渠道>
商户号 | mchNo | 是 | String(32) | 本平台下发的商户号
签名 | sign | 是 | String(32) | 签名，详见签名生成算法
商品描述 | body | 是 | String(128) | 商品或支付单简要描述
商户支付订单 号 | mchOrderNo | 是 | String(32) | 商户系统内部的支付订单号,32 个字符内、可包含字 母,数字，请确保在商户系统唯一
交易金额 | amount | 是 | String(16) | 单位：分，不能带有小数点；VND时要注意金额*100
货币类型 | currency | 否 | String(16) | 默认：VND
订单提交支付时间 | timePaid | 是 | String(14) | 提交支付时间，格式为 yyyyMMddHHmmss，如 2017 年 11
月 15 日 9 点 10 分 10 秒表示为 20171115091010
订单失效时间 | timeExpire | 否 | String(14) | 订单失效时间，格式同上
支付描述 | remark | 否 | String(128) | 支付备注
支付请求扩展参数 | extra | 是 | map | 特定渠道发起交易时需要的额外参数以及部分渠道支 付成功返回的额外参数，详见具体支付渠道章节
=== 表格结束 ===


=== 表格内容 ===
字段名 | 变量名 | 必填 | 类型 | 描述
通信状态码 | status | 是 | int | 0：成功、其他值：失败。 此字段是通信标识，非交易标识，预支付请求是否成功需要查看 resultCode 来判断
通信错误信息 | message | 否 | String(128) | 返回信息，如非空，为错误原因 
签名失败 
参数格式校验错误等；
针对虚拟卡业务，这里会以json格式返回虚拟卡信息
以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回
商户号 | mchNo | 是 | String(32) | 由本平台分配的商户号
操作结果 | resultCode | 是 | int | 操作结果状态，0：成功 其他值:失败
与具体业务内容无关，如查询成功
不等于查询的订单支付成功
错误代码 | errCode | 否 | String(32) | 业务错误代码
错误代码描述 | errMsg | 否 | String(128) | 错误返回的信息描述
签名 | sign | 是 | String(32) | 签名，详见签名生成算法
平台订单号 | cpOrderNo | 是 | String(32) | 本平台订单号
商户订单号 | mchOrderNo | 是 | String(32) | 商户系统内部的订单号,32 个字符内、可包含字母, 确 保在商户系统唯一
以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回
支付结果扩展参数 | 是 | 特定渠道发起交易时会返回额外的参数，详见具体支付渠道章节
=== 表格结束 ===


=== 表格内容 ===
字段名 | 变量名 | 必填 | 类型 | 描述
后台通知地址 | notifyUrl | 是 | String(200) | 支付完成后，后台异步结果通知 url
页面返回地址 | callbackUrl | 否 | String(200) | 交易完成后跳转的 URL，需给绝对路径，该地址只作为前端页面的一个 跳 转 ，需 使用 notifyUrl 通知结果作为支付最终结果。
买家用户标识 | memberId | 是 | String(100) | 生成的虚拟银行帐号的姓名
银行编码 | bankType | 是 | String(20) | usdt时固定 offline；其它请咨询客服
银行卡类型 | cardType | 是 | String(2) | 0:借记卡  1:贷记卡。 固定 0
商户展示名称 | merchantName | 是 | String(32)
订单有效时长 | orderPeriod | 是 | String(3) | 订单有效时长，以分钟为单位；0表示生成的帐号为一次性银行帐号，大于0为可多次使用的银行帐号
商品编号 | goodsId | 否 | String(80)
商品描述 | goodsDesc | 否 | String(500)
商品展示地址 | showUrl | 否 | String(200)
终端类型 | clientType | 否 | String(10) | 用户（买家）使用的终端类型：
 1 - PC端；2 - 移动端
部分渠道不支持移动端，详情请咨询本平台工作人员
=== 表格结束 ===


=== 表格内容 ===
字段名 | 字段名 | 变量名 | 必填 | 必填 | 类型 | 描述 | 描述
支付链接 | codeUrl | codeUrl | 是 | 是 | String(32) | 商户根据此链接跳转支付
=== 表格结束 ===


=== 表格内容 ===
字段名 | 变量名 | 必填 | 类型 | 描述
通信状态码 | status | 是 | int | 0：成功、其他值：失败。 此字段是通信标识，非交易标识，交易是否成功需要查看 resultCode 和  payResult
通信错误信息 | message | 否 | String(128) | 返回信息，如非空，为错误原因 
签名失败 
参数格式校验错误等 
成功时会传回订单的备注信息
以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回
商户号 | mchNo | 是 | String(32) | 由本平台分配的商户号
操作结果 | resultCode | 是 | int | 操作结果状态，0：成功 其他值:失败
与具体业务内容无关，如查询成功
不等于查询的订单支付成功
错误代码 | errCode | 否 | String(32) | 业务错误代码
错误代码描述 | errMsg | 否 | String(128) | 错误返回的信息描述
签名 | sign | 是 | String(32) | 签名，详见签名生成算法
商户订单号 | mchOrderNo | 是 | String(32) | 商户系统内部的订单号,32 个字符内、可包含字母, 确 保在商户系统唯一
平台订单号 | cpOrderNo | 是 | String(35) | 系统内部的订单号
以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回
支付状态 | payResult | 是 | String(1) | 支付/代付结果状态，
0：支付/代付成功；
-1：仅用于代付失败
其他值：未支付，请检查payInfo；
支付状态信息 | payInfo | 否 | String(128) | 支付状态描述，当支付成功时为空
订单金额 | amount | 是 | String(16) | 单位为分
交易时间 | traceTime | 是 | String(14) | 支付处理成功时间，格式同上
=== 表格结束 ===


=== 表格内容 ===
字段名 | 变量名 | 必填 | 类型 | 描述
交易类型 | tradeType | 是 | String(32) | 订单查询：cs.order.query
版本 | version | 否 | String(8) | 版本号，默认 2.0
商户号 | mchNo | 是 | String(32) | 由本平台分配的商户号
商户订单号 | mchOrderNo | 是 | String(32) | 商户订单号
签名 | sign | 是 | String(32) | 签名
=== 表格结束 ===


=== 表格内容 ===
字段名 | 变量名 | 必填 | 类型 | 描述
交易类型 | tradeType | 是 | String(32) | cs.df.submit
版本 | version | 否 | String(8) | 版本号，默认 2.0
商户号 | mchNo | 是 | String(32) | 由本平台分配的商户号
金额 | amount | 是 | String(32) | 代付金额 单位 分
交易订单号 | mchOrderNo | 是 | String(32) | 商户代付订单号
代付结果通知地址 | notifyUrl | 否 | String(32) | 选填  需要通知时不为空, 不能与支付的结果通知地址相同。
账户类型 | accountType | 是 | String(32) | 0-银行借记卡号/USDT  3-银行帐号
收款人姓名 | accName | 是 | String(32) | 使用usdt通道时，直接填　USDT
收款人账号 | bankNo | 是 | String(32) | 使用usdt通道时，直接填USDT地址
备注 | remark | 是 | String(255)
银行编号 | bankCode | 是 | String(32) | 见7.2银行编码；使用usdt通道时，直接填 USDT
代付方式 | payType | 是 | String(2) | 代付方式：1:垫资代付，0:余额代付；
默认为余额代付
钱包编号 | walletNo | 否 | String(32) | 发起代付对应的钱包的编号，不传则默认使用余额最多的钱包发起代付
签名 | sign | 是 | String(32) | 签名
=== 表格结束 ===


=== 表格内容 ===
字段名 | 变量名 | 必填 | 类型 | 描述
通信状态码 | status | 是 | int | 0：成功、其他值：失败。 此字段是通信标识，非交易标识，交易是否成功需要查看 resultCode 和 payResult结合来看
通信错误信息 | message | 否 | String(128) | 返回信息，如非空，为错误原因 
签名失败 
参数格式校验错误等
以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回
商户号 | mchNo | 是 | String(32) | 由本平台分配的商户号
操作结果 | resultCode | 是 | int | 操作结果状态，0：成功 其他值:失败
与具体业务内容无关，如查询成功
不等于查询的订单支付成功
错误代码 | errCode | 否 | String(32) | 业务错误代码
错误代码描述 | errMsg | 否 | String(128) | 错误返回的信息描述
签名 | sign | 是 | String(32) | 签名，详见签名生成算法
商户订单号 | mchOrderNo | 是 | String(32) | 商户提交的订单号
平台订单号 | cpOrderNo | 是 | String(32) | 平台代付订单号
以下字段在resultCode为 0 时才有返回 | 以下字段在resultCode为 0 时才有返回 | 以下字段在resultCode为 0 时才有返回 | 以下字段在resultCode为 0 时才有返回 | 以下字段在resultCode为 0 时才有返回
代付结果 | payResult | 是 | String(32) | 代付执行结果，请查阅代付状态说明
代付金额 | amount | 是 | String(32) | 代付金额
支付状态信息 | payInfo | 否 | String(128) | 支付状态描述，当支付成功时为空
代付方式 | payType | 是 | String(2) | 代付方式：1:垫资代付，0:余额代付；
可用余额 | avlBal | 是 | String(50) | 商户当前可代付金额
=== 表格结束 ===


=== 表格内容 ===
字段名 | 变量名 | 必填 | 类型 | 描述
交易类型 | tradeType | 是 | String(50) | cs.df.query
版本 | version | 是 | String(50) | 版本号，默认 2.0
平台订单号 | settNo | 否 | String(50) | 平台返回的订单号，两个订单不能同时为空
商户订单号 | mchSettNo | 否 | String(50) | 商户订单号，两个订单不能同时为空
商户号 | mchNo | 是 | String(50) | 由本平台分配的商户号
签名 | sign | 是 | String(50) | 签名
=== 表格结束 ===


=== 表格内容 ===
字段名 | 变量名 | 必填 | 类型 | 描述
通信状态码 | status | 是 | int | 0：成功、其他值：失败。 此字段是通信标识，非交易标识，交易是否成功需要查看 resultCode  和  p a yR e s u l t
通信错误信息 | message | 否 | String(128) | 返回信息，如非空，为错误原因 
签名失败 
参数格式校验错误等
以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回
商户号 | mchNo | 是 | String(32) | 由本平台分配的商户号
操作结果 | resultCode | 是 | int | 操作结果状态，0：成功 其他值:失败
与具体业务内容无关，如查询成功
不等于查询的订单支付成功
错误代码 | errCode | 否 | String(32) | 业务错误代码
错误代码描述 | errMsg | 否 | String(128) | 错误返回的信息描述
签名 | sign | 是 | String(32) | 签名，详见签名生成算法
平台订单号 | cpOrderNo | 是 | String(32) | 本平台订单号
商户订单号 | mchOrderNo | 是 | String(32) | 商户系统内部的订单号,32 个字符内、可包含字母, 确 保在商户系统唯一
以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回
代付状态 | payResult | 是 | String(1) | 代付结果状态，请查阅代付状态说明
代付状态信息 | payInfo | 否 | String(128) | 代付状态描述，当代付成功时为空
代付方式 | payType | 是 | String(2) | 代付方式：1:垫资代付，0:余额代付；
默认为余额代付
交易金额 | amount | 是 | String(32) | 代付金额
=== 表格结束 ===


=== 表格内容 ===
字段名 | 变量名 | 必填 | 类型 | 描述
交易类型 | tradeType | 是 | String(50) | cs.wallet.query
版本 | version | 是 | String(50) | 版本号，默认 2.0
商户号 | mchNo | 是 | String(50) | 由本平台分配的商户号
钱包编号 | walletNo | 否 | String(50) | 来源：可从商户后台查看钱包编号
例如：10044_xys
      钱包编号为：10044
签名 | sign | 是 | String(50) | 签名
=== 表格结束 ===


=== 表格内容 ===
字段名 | 变量名 | 必填 | 类型 | 描述
通信状态码 | status | 是 | int | 0：成功、其他值：失败。 此字段是通信标识，非业务标识，交易是否成功需要查看 resultCode 来判断
通信错误信息 | message | 否 | String(128) | 返回信息，如非空，为错误原因 
签名失败 
参数格式校验错误等
以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回 | 以下字段在 status 为 0 时才有返回
商户号 | mchNo | 是 | String(32) | 由本平台分配的商户号
操作结果 | resultCode | 是 | int | 操作结果状态，0：成功 其他值:失败
与具体业务内容无关，如查询成功
不等于查询的订单支付成功
错误代码 | errCode | 否 | String(32) | 业务错误代码
错误代码描述 | errMsg | 否 | String(128) | 错误返回的信息描述
签名 | sign | 是 | String(32) | 签名，详见签名生成算法
以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回 | 以下字段在 resultCode 为 0 时才有返回
钱包列表 | walletList | 是 | json | 返回json字符串，解析后为钱包列表参数如下：
walletNo 钱包编号
mchBal 已结算余额
mchFroBal 冻结余额  
advLimit 垫资额度  
unsettBal 待结算余额
=== 表格结束 ===


=== 表格内容 ===
union_pay | 网银支付
usdt_pay | Usdt Payment
=== 表格结束 ===


=== 表格内容 ===
暂无
=== 表格结束 ===


=== 表格内容 ===
银行缩写 | 银行名称
REMIT_INIT | 订单初始化，未提交至银行，请检查参数确认无误后重新提交
SUBMITTED | 已提交申请，结果不明，需代付查询确认订单状态
SUBMITSUCCESS | 提交成功，等待银行处理，需代付查询确认处理结果
WAIT_CONFIRM | 等待审核，等待银行处理，需代付查询确认处理结果
SUBMIT_FAIL | 提交失败，订单失效
CANCEL | 审核失败，订单失效
REMIT_SUCCESS | 银行处理成功，打款成功
REMIT_FAIL | 银行处理失败，打款失败
REMITTING | 银行处理中，需代付查询确认处理结果
=== 表格结束 ===