[关闭]
@ulodev 2019-04-24T07:56:30.000000Z 字数 8803 阅读 3036

优络服务接口文档-代付

接口 支付

1. 引言

1.1. 阅读对象

本文阅读对象：商户系统（在线购物平台、人工收银系统、自动化智能收银系统及其他）集成微信、支付宝、QQ钱包支付涉及的技术架构师，研发工程师，测试工程师，系统运维工程师。

1.2. 服务账户

商户在优络服务平台(申请扫码支付、公众号支付)按照相应提示，申请相应服务模式。工作人员审核资料 无误后开通相应的服务模式，如：微信支付、支付宝支付、百度钱包、QQ 钱包支付等。申请审核通过后，商 户在申请资料填写的邮箱中收取到由优络服务平台发送的邮件，此邮件包含开发时需要使用的支付账户信息。

1.2.1. 账户参数说明

参数 API 参数名 详细说明
商户号 mch_id 商户申请优络技术服务后，由服务平台分配的商户收款账号。
API 密钥 key 交易过程生成签名的密钥，不会在网络中传播。商户妥善保管该 Key， 切勿在网络中传输，不能在其他客户端中存储，保证 key 不会被泄漏。

1.2.2. 测试服务账户

参数 示例 详细说明
商户号 26104515 商户申请优络服务后，由服务平台分配的商户 收款账号。
API 密钥 d014da1ab33d8f3ddfaf7e5a81724f1a 交易过程生成签名的密钥，不会在网络中传 播。
金额 100 单位为分,1 元

1.3. 电子账户

商户提出申请，优络科技为商户开通电子账户功能，支付款项结算至电子账户中，商户根据接口进行款项代付。在首次开通电子商户时，电子账户号和商户号相同。

2. 接口规则

2.1. 协议规则

调用API必须遵循以下规则

传输方式 为保证交易安全性，采用 HTTPS 传输
提交方式 采用 POST 方法提交
数据格式 提交和返回数据都为 XML 格式，根节点名为 xml
字符编码 统一采用 UTF-8 字符编码
签名算法 MD5，后续会兼容 SHA1、SHA256、HMAC 等。
签名要求 请求和接收数据均需要校验签名，详细方法请参考 安全规范 -签名算法
证书要求 调用申请退款、撤销订单接口需要商户证书
判断逻辑 先判断协议字段返回，再判断业务返回，最后判断交易状态

2.2. 参数规定

交易金额

交易金额默认为人民币交易，接口中参数支付金额单位为【分】，参数值不能带小数。对账单中的交易金 额单位为【元】

产品类型

普通代付，不限出款时间，使用“结算余额”，正常 5 分钟内到账，偶尔半小时也属于正常时间范围；
任意付，不限出款时间，优先使用“结算余额”，“结算余额”不够情况下使用“可垫资余额”；
垫资付，不限出款时间，使用“可垫资余额”，正常 5 分钟内到账，偶尔半小时也属于正常时间范围；

货币类型

货币类型的取值列表：CNY：人民币

时间标准

时间标准北京时间，时区为东八区；如果商户的系统时间为非标准北京时间。参数值必须根据商户系统所在时 区先换算成标准北京时间， 例如商户所在地为0时区的伦敦，当地时间为 2014 年 11 月 11 日 0 时 0分0秒，换算成北京时间为 2014 年 11 月 11 日 8 时 0 分 0 秒。

时间戳

标准北京时间，时区为东八区，自 1970 年 1 月 1 日 0 点 0 分 0 秒以来的秒数。注意：部分系统取到的值为毫 秒级，需要转换成秒(10 位数字)。

商户订单号

商户支付的订单号由商户自定义生成，要求商户订单号保持唯一性（建议根据当前系统时间加随机序列来生成订单 号）。重新发起一笔支付要使用原订单号，避免重复支付；已支付过及已调用关单、撤销（请见后文的 API 列表）的订单号不能重新发起支付。

2.3. 安全规范

1、签名算法

签名生成的通用步骤如下：第一步，设所有发送及者接收到的数据为集合 M，将集合 M 内非空参数值的参数按照参数名 ASCII 码从 小到大排序（字典序），使用  URL  键值对的格式（即  key1=value1&key2=value2…）拼接成字符串  stringA。 特别注意以下重要规则：
◆ 参数名 ASCII 码从小到大排序（字典序）；
◆ 如果参数的值为空不参与签名；也就是说参数是空的不需要参与签名；
◆ 参数名区分大小写；
◆ 验证调用返回或主动通知签名时，传送的  sign  参数不参与签名，将生成的签名与该sign值作校验。
◆  支付接口可能增加字段，验证签名时必须支持增加的扩展字段

2、生成随机数算法

支付 API 接口协议中包含字段 nonce_str，主要保证签名不可预测。我们推荐生成随机数算法如下：调用 随机数函数生成，将得到的值转换为字符串。

举例： 假设传送的参数如下：

  1.     appid： wxd930ea5d5a258f4f 
  2.     mch_id：  10000100
  3.     device_info： 1000 
  4.     body：  test

第一步：对参数按照 key=value 的格式，并按照参数名 ASCII 字典序排序如下：

  1. stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100&nonce_str=ibuaiVcKdpRxkhJA";

最终得到最终发送的数据：

  1. <xml>
  2.     <appid>wxd930ea5d5a258f4f</appid>
  3.     <mch_id>10000100</mch_id>
  4.     <device_info>1000<device_info>
  5.     <body>test</body>
  6.     <nonce_str>ibuaiVcKdpRxkhJA</nonce_str>
  7.     <sign>9A0A8659F005D6984697E2CA0A9CF3B7</sign>
  8. <xml>

采用标准XML协议，所有参数只存在一级节点中，不采用多级节点嵌套。

协议级错误返回：

  1. <xml>
  2.     <return_code>
  3.         <![CDATA[FAIL]]>
  4.     </return_code>
  5.     <return_msg>
  6.         <![CDATA[404 NotFound]]>
  7.     </return_msg>
  8. </xml>

正确返回数据：

  1. <xml>
  2.     <mch_id><![CDATA[15121009]]></mch_id>
  3.     <openid><![CDATA[ozaUDwqSo51HvC0lw9CrL20KXlsQ]]></openid>
  4.     <out_trade_no><![CDATA[20150303398]]></out_trade_no>
  5.     <result_code><![CDATA[SUCCESS]]></result_code>
  6.     <return_code><![CDATA[SUCCESS]]></return_code>
  7.     <third_trans_id><![CDATA[1004970044201510081126012906]]></third_trans_id>
  8.     <time_end><![CDATA[20151008112037]]></time_end>
  9.     <total_fee><![CDATA[1]]></total_fee>
  10.     <transaction_id><![CDATA[1512100920150925000000010]]></transaction_id>
  11. </xml>

业务级错误返回：

  1. <xml>
  2.     <err_code><![CDATA[AUTHCODEEXPIRE]]></err_code>
  3.     <err_code_des><![CDATA[请扫描微信支付被扫条码/二维码]]></err_code_des>
  4.     <result_code><![CDATA[FAIL]]></result_code>
  5.     <return_code><![CDATA[SUCCESS]]></return_code>
  6. </xml>

3. API 列表

3.1. 单笔代付接口

3.1.1. 应用场景

系统每日 10 点进行账户清结算，开通电子账户的商户，款项默认转至此账户中，商户可调用代付接口进 行代付。实际资金将在每日  11  点左右进行入账，也就是说，11 点之后就可以进行余额提现，且是秒到。
每笔代付会自动从余额中扣除手续费，具体手续费咨询商务；如手续费是  1  元/笔，则转账  10  块钱，实际会扣除余额账户11元。

3.1.2. 接口地址

https://api.ulopay.com/pay/agentpay/single

3.1.3. 输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
随机字符串 nonce_str String(32) 是 随机字符串，不长于 32 位
产品类型 product_type String(32) 是 0 - 普通代付，1 - 任意付，2 - 垫资付。详见2.2. 参数规定
收款银行所在城市 bank_city String(32) 是 收款银行所在城市
商户订单号 out_trade_no String(32) 是 商户系统内部的订单号,32 个字符内、可包含字母,其他 说明见商户订单号
代付金额 total_fee Int 是 订单总金额，单位为分，只能为整数 单笔最大不超过 5 万元 单笔最小不低于 1 元
代付备注 body String(32) 是 代付简要描述
入账账户类型 pay_type String(2) 是 0：对私，1：对公，
入账账户户名 pay_name String(32) 是 收款银行账户姓名
入账账户账号 pay_card_no String(32) 是 收款银行账户账号
账户联行号 bank_union_no String(32) 否 对公账户必须有联行号，对私账户不需要 收款银行的联行号，可在网上查询： http://www.lianhanghao.com
操作员编号 op_user_id String(32) 否 操作员帐号
签名 sign String(32) 是 签名，详见签名生成算法

3.1.4. 返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看 result_code 来判断
返回信息 return_msg String(128) 否 返回信息，如非空，为错误原因签名失败 参数格式校验错误
当 return_code 为 SUCCESS 的时候，还会包括以下字段：
商户号 mch_id String(32) 是 调用接口提交的商户号
随机字符串 nonce_str String(32) 是 微信返回的随机字符串
签名 sign String(32) 是 微信返回的签名，详见签名生成算法
业务结果 result_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
当 return_code 和result_code 都为 SUCCESS 的时，还会包括以下字段：
交易状态 trade_state String(32) 是 NOTPAY—正在调拨资金,请耐心等待
PROCESSING—处理中,请耐心等待划账
SUCCESS—出款成功,请检查款项是否到账
REVOKED—撤销代付请求,款项被退回
PAYERROR—代付系统错误,款项被退回
交易状态描述 trade_state_desc String(64) 是 交易状态简要描述，提示代付的下一步步骤
平台代付单号 transaction_id String(32) 是 代付平台系统生成的唯一单号，可用于代付查询

3.1.5. 错误码

注意：如果当前交易返回的支付状态是明确的错误原因造成的支付失败（支付确认失败），请重新下单支 付；如果当前交易返回的支付状态是不明错误（支付结果未知），请调用查询订单接口确认状态。
名称 描述 原因 解决方案
NOAUTH 商户无此接口权限 商户未开通此接口权限 请商户前往申请此接口权限
BALANCE_NOT_ENOUGH 余额不足 转出账户余额不足 转出账户余额不足
CASHACCT_NOT_EXIST 未开通电子账户服 务 未开通电子账户服务 未开通电子账户服务
CASHTRANS_PROCSFEE_I NVALID 金额错误 单笔转出金额不足以支 付手续费 单笔转出金额不足以支付手续费
UNIONNO_INVALID 银行联行号不正确 银行联行号不正确 银行联行号不正确
SYSTEMERROR 系统错误 系统超时 系统异常，请用相同参数重新调用
APPID_NOT_EXIST APPID 不存在 参数中缺少 APPID 请检查 APPID 是否正确
MCHID_NOT_EXIST MCHID 不存在 参数中缺少 MCHID 请检查 MCHID 是否正确
LACK_PARAMS 缺少参数 缺少必要的请求参数 请检查参数是否齐全
OUT_TRADE_NO_USED 商户订单号重复 同一笔交易不能多次提 交 请核实商户订单号是否重复提交
SIGNERROR 签名错误 参数签名结果不正确 请检查签名参数和方法是否都符合签名算 法要求
XML_FORMAT_ERROR XML 格式错误 XML 格式错误 请检查 XML 参数格式是否正确
REQUIRE_POST_METHOD 请使用 post 方法 未使用 post 传递参数 请检查请求参数是否通过 post 方法提交
POST_DATA_EMPTY post 数据为空 post 数据不能为空 请检查 post 数据是否为空
NOT_UTF8 编码格式错误 未使用指定编码格式 请使用 NOT_UTF8 编码格式

3.2. 代付查询接口

3.2.1. 应用场景

商户可以通过该接口主动查询代付订单状态，确认当前代付状态，完成下一步的业务逻辑。

3.2.2. 接口地址

https://api.ulopay.com/pay/agentpay/query

3.2.3. 输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
随机字符串 nonce_str String(32) 是 随机字符串，不长于 32 位
商户订单号 out_trade_no String(32) 二
选
一		 商户系统内部的订单号,32 个字符内、可包含字母,其他 说明见商户订单号
平台代付单号 transaction_id String(32) 优络服务平台生成的内部单号
操作员编号 op_user_id String(32) 否 操作员帐号
签名 sign String(32) 是 签名，详见签名生成算法

3.2.4. 返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看 result_code 来判断
返回信息 return_msg String(128) 否 返回信息，如非空，为错误原因 签名失败 参数格式校验错误
当 return_code 为 SUCCESS 的时候，还会包括以下字段：
商户号 mch_id String(32) 是 调用接口提交的商户号
随机字符串 nonce_str String(32) 是 微信返回的随机字符串
签名 sign String(32) 是 微信返回的签名，详见签名生成算法
业务结果 result_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
当 return_code 和 result_code 都为 SUCCESS 的时，还会包括以下字段：
交易状态 trade_state String(32) 是 NOTPAY—正在调拨资金,请耐心等待
PROCESSING—处理中,请耐心等待划账
SUCCESS—出款成功,请检查款项是否到账
REVOKED—撤销代付请求,款项被退回
PAYERROR—代付系统错误,款项被退回
CLOSE—代付系统异常，订单已关闭
交易状态描述 trade_state_desc String(64) 是 交易状态简要描述，提示代付的下一步步骤
平台代付单号 transaction_id String(32) 是 代付平台系统生成的唯一单号，可用于代付查询
商户订单号 out_trade_no String(32) 是 商户系统内部的订单号,32 个字符内、可包含字母,其 他说明见商户订单号
代付金额 total_fee Int 是 订单总金额，单位为分，只能为整数
单笔最大不超过 10 万元
单笔最小不低于 1 元
代付备注 body String(32) 是 代付简要描述
入账账户类型 pay_type String(2) 是 0：对私，1：对公
入账账户户名 pay_name String(32) 是 收款银行账户姓名
入账账户账号 pay_card_no String(32) 是 收款银行账户账号
账户联行号 bank_union_no String(32) 否 对公账户必须有联行号，对私账户不需要 收款银行的联行号，可在网上查询

3.2.5. 错误码

名称 描述 原因 解决方案
NOAUTH 商户无此接口权限 商户未开通此接口权限 请商户前往申请此接口权限
CASHTRANS_NOE_EXISTS 单号错误 此代付订单号不存在 此代付订单号不存在
CASHACCT_NOT_EXIST 未开通电子账户服 务 未开通电子账户服务 未开通电子账户服务
SYSTEMERROR 系统错误 系统超时 系统异常，请用相同参数重新调用
APPID_NOT_EXIST APPID 不存在 参数中缺少 APPID 请检查 APPID 是否正确
MCHID_NOT_EXIST MCHID 不存在 参数中缺少 MCHID 请检查 MCHID 是否正确
LACK_PARAMS 缺少参数 缺少必要的请求参数 请检查参数是否齐全
OUT_TRADE_NO_USED 商户订单号重复 同一笔交易不能多次提 交 请核实商户订单号是否重复提交
SIGNERROR 签名错误 参数签名结果不正确 请检查签名参数和方法是否都符合签名算 法要求
XML_FORMAT_ERROR XML 格式错误 XML 格式错误 请检查 XML 参数格式是否正确
REQUIRE_POST_METHOD 请使用 post 方法 未使用 post 传递参数 请检查请求参数是否通过 post 方法提交
POST_DATA_EMPTY post 数据为空 post 数据不能为空 请检查 post 数据是否为空
NOT_UTF8 编码格式错误 未使用指定编码格式 请使用 NOT_UTF8 编码格式

3.3. 查询余额接口

3.3.1. 应用场景

商户可以通过该接口主动查当前系统余额，判断是否有可转金额，完成下一步的业务逻辑。

3.3.2. 接口地址

https://api.ulopay.com/pay/agentpay/account

3.3.3. 输入参数

字段名 变量名 类型 必填 描述
商户号 mch_id String(32) 是 商户号
随机字符串 nonce_str String(32) 是 随机字符串，不长于 32 位
操作员编号 op_user_id String(32) 否 操作员帐号
签名 sign String(32) 是 签名，详见签名生成算法

3.3.4. 返回结果

字段名 变量名 类型 必填 描述
返回状态码 return_code String(16) 是 SUCCESS/FAIL此字段是通信标识，非交易标识，交易是否成功需要查看result_code 来判断
返回信息 return_msg String(128) 否 返回信息，如非空，为错误原因 签名失败 参数格式校验错误
当 return_code 为 SUCCESS 的时候，还会包括以下字段：
商户号 mch_id String(32) 是 调用接口提交的商户号
随机字符串 nonce_str String(32) 是 微信返回的随机字符串
签名 sign String(32) 是 微信返回的签名，详见签名生成算法
业务结果 result_code String(16) 是 SUCCESS/FAIL
错误代码 err_code String(32) 否 详细参见错误列表
错误代码描述 err_code_des String(128) 否 错误返回的信息描述
当 return_code 和 result_code 都为 SUCCESS 的时，还会包括以下字段：
当前可用余额 current_amount Number(20) 是 当前可用余额，单位为分
当前冻结余额 frozen_amount Number(20) 是 当前冻结余额，单位为分
可结算余额 can_settle_balance Number(20) 是 当前可结算余额，单位为分
待清算余额 un_settle_amount Number(20) 是 0点后当天交易金额会转入待清算余额，到次日11点左右转入可结算余额

3.3.5. 错误码

名称 描述 原因 解决方案
NOAUTH 商户无此接口权限 商户未开通此接口权限 请商户前往申请此接口权限
CASHACCT_NOT_EXIST 未开通电子账户服 务 未开通电子账户服务 未开通电子账户服务
SYSTEMERROR 系统错误 系统超时 系统异常，请用相同参数重新调用
MCHID_NOT_EXIST MCHID 不存在 参数中缺少 MCHID 请检查 MCHID 是否正确
LACK_PARAMS 缺少参数 缺少必要的请求参数 请检查参数是否齐全
OUT_TRADE_NO_USED 商户订单号重复 同一笔交易不能多次提 交 请核实商户订单号是否重复提交
SIGNERROR 签名错误 参数签名结果不正确 请检查签名参数和方法是否都符合签名算 法要求
XML_FORMAT_ERROR XML 格式错误 XML 格式错误 请检查 XML 参数格式是否正确
REQUIRE_POST_METHOD 请使用 post 方法 未使用 post 传递参数 请检查请求参数是否通过 post 方法提交
POST_DATA_EMPTY post 数据为空 post 数据不能为空 请检查 post 数据是否为空
NOT_UTF8 编码格式错误 未使用指定编码格式 请使用 NOT_UTF8 编码格式
添加新批注
在作者公开此批注前，只有你和作者可见。
回复批注