doc

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

@@ -0,0 +1,360 @@
+商户接入接口文档 
+版本 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 | 银行处理中，需代付查询确认处理结果
+=== 表格结束 ===