商户接入接口文档 版本 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¤cy=VND&mchNo=99992017122510000542&mchOrderNo=6666201711151723480245¬ifyUrl=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 | 银行处理中，需代付查询确认处理结果 === 表格结束 ===