富友代收接口文档 - fuiou · 2020. 6. 16. · 富友代收付平台企业直连接入规范...

富友代收付平台企业直连接入规范

1

富友代收接口文档

V1.9

上海富友支付服务股份有限公司

2019 年 5 月


2

修订历史

版本号时间修订人修订原因

V1.3 2016-04-21 郜红欣去掉冗余，增加退票

通知接口

V1.4 2017-11-01 葛静静添加交易状态类别

V1.5 2018-01-22 葛静静修改业务处理周期

V1.6 2018-06-20 沈选锋户名不能保护特殊英

文字符

V1.7 2018-08-28 葛静静新增 srcModuleCd

V1.8 2018-09-29 郜红欣多模式文档合并

V1.9 2019-05-31 郜红欣增加双活域名切换


3

目录

1 概述 ........................................................................................................................................... 5

1.1 背景 ......................................................................................................................................... 5

1.2 编写目的 ................................................................................................................................. 5

1.3 范围 ......................................................................................................................................... 5

1.4 定义和缩略语 ......................................................................................................................... 5

2 富友代收付平台介绍 ................................................................................................................ 6

2.1 基本业务种类 ......................................................................................................................... 6

2.2 系统功能 ................................................................................................................................. 6

2.3 运行时间及业务处理周期...................................................................................................... 6

3 协议说明 ................................................................................................................................... 6

3.1 交互模式 ................................................................................................................................. 6

3.2 协议格式 ................................................................................................................................. 7

3.2.1 请求报文 ......................................................................................................................... 7

3.2.2 响应报文 ......................................................................................................................... 8

3.2.3 接口地址 ......................................................................................................................... 8

4 交易 ........................................................................................................................................... 8

4.1 代收（单笔） ......................................................................................................................... 8

4.1.1 请求参数 ......................................................................................................................... 8

4.1.2 响应参数 ......................................................................................................................... 9

4.2 签约 ......................................................................................................................................... 9

4.2.1 接口定义 ....................................................................................................................... 10

4.2.2 接口地址 ....................................................................................................................... 10

4.2.3 请求参数 ....................................................................................................................... 10

4.3 签约结果通知（异步）........................................................................................................ 11

4.4 签约查询接口 ....................................................................................................................... 12

4.4.1 接口地址 ....................................................................................................................... 12

4.4.2 示例 ............................................................................................................................... 12

4.4.3 请求报文 ....................................................................................................................... 12

4.4.4 响应报文 ....................................................................................................................... 13

4.4.5 生成签名 ....................................................................................................................... 15

5 交易查询接口 .......................................................................................................................... 16

5.1 交易查询（条件可组合）.................................................................................................... 16

5.1.1 请求参数 ....................................................................................................................... 16

5.1.2 响应参数 ....................................................................................................................... 17

5.2 账户余额查询 ....................................................................................................................... 18

5.2.1 协议格式 ....................................................................................................................... 18

5.2.2 接口地址 ....................................................................................................................... 19


4

5.2.3 请求报文 ....................................................................................................................... 19

5.2.4 响应报文 ....................................................................................................................... 19

6 附录 ......................................................................................................................................... 21

6.1 证件类型代码表 ................................................................................................................... 21

6.2 交易状态码说明 ................................................................................................................... 21

6.3 签约查询应答码附录 ........................................................................................................... 22

7 双活域名切换 .......................................................................................................................... 22


5

1 概述

1.1 背景

根据目前富友代收付平台实际业务运作情况，结合富友代收付系统业务处理规范，在遵

循人行小额支付系统报文规范的基础上，特制定本规范。

1.2 编写目的

本规范的主要目的是建立与企业业务系统对接的基础，指导前置系统的开发与实施。为

后续系统总体设计、概要设计和设备选型、招标、采购，以及系统集成提供的标准性文档。

1.3 范围

本规范使用于富友代收付平台以及相关企业前置机系统。

1.4 定义和缩略语

名称说明

代收付平台富友代收付平台

代收业务指富友按照与委托单位及缴款单位（个人）的协议，将委托单位提供

的清单或缴款单位（个人）提供的缴款凭证上送至富友的代收渠道，由银

行或金融机构代理委托单位收取款项的业务，主要包括代收水费、电费、

煤气费、交通罚款，代扣电话费，代收学费、代收订报费、代收住房公积

金、代收房租，代收工商管理费、代收技术监督费、代收外管局罚没款及

其他代收行政罚没款等。

付款业务根据商户交易指令，将资金代发至商户指定的银行账户。

商户指有合法资质，或使用本平台向个人用户发起代收款或付款款操作的

用户，可自行注册，或由代理商注册，后台审批通过后才能使用本平台功

能。

商户号富友代收付平台为每个接入的商户分配一个唯一的编号。

请求流水每商户每天唯一的不超过 10-30 位数字序号，用于保存和定位商户交易。


6

2 富友代收付平台介绍

2.1 基本业务种类

富友代收付平台处要处理下列业务：

代收业务

付款业务

注：本文档只介绍代收业务相关接口。

2.2 系统功能

系统功能主要包括报文发送、接收，业务处理。

2.3 运行时间及业务处理周期

24 小时接收业务数据。

代收交易不设交易场次。

3 协议说明

3.1 交互模式

对外接口分为两种，一种是接收外部请求的接口，我们统称为外部接入接口。一种是主

动通知外部系统的接口，我们统称为外部通知接口。

外部接入接口的主要目的是让外部合作伙伴主动使用我们的服务，外部通知接口的主要

目的是为外部合作伙伴提供数据同步服务。通知接口会通知商户多次, 在接收到重复通知

时,如果上一次的通知已经处理成功, 在重复通知中也应该返回给富有接受通知成功.

商户富友

http(s)请求（商户号，请求类型，请求参数XML，校验值）

响应（xml）


7

图 2-1 外部接入接口

富友商户

http(s)请求（商户号，请求类型，请求参数XML，校验值）

响应（xml）

图 2-2 外部通知接口

3.2 协议格式

同步 http 请求响应对。

请求数据采用 POST 表单提交。

并发请求不得多于 10 个。

商户必须保证流水号当天唯一。

响应数据采用 XML。

请求和响应数据使用 UTF-8 字符集编码。

需要签证校验值。

可空：是表示可以没有值，否则表示必须要有值。

红色字体部分，为提交参数

3.2.1 请求报文

*注意: 付款、代收、查询必须且只传递以下参数

节点名称中文名称类型可空含义

merid 商户号否生产由富友分配

reqtype 请求类型否代付：payforreq 代收：sincomeforreq

xml 请求参数否使用 XML 表示，见各功能点的请求报文定义

mac 校验值否商户号|富友分配给商户的密钥|请求类型|业

务参数 XML，用竖线拼接后用 MD5 散列后的

32 进制文本

Md5(merid+”|”+pwd+”|”+reqtype+”|”+xml)

示例：实际传输时请采用 post 方式

https://.../req.do?merid=...&reqtype=...&xml=...&mac=...


8

3.2.2 响应报文

见下文功能部分

3.2.3 接口地址

测试环境交易：https://fht-test.fuioupay.com/fuMer/req.do

生产环境交易 1：https://fht-api.fuioupay.com/req.do

生产环境交易 2：https://fht-api-xs.fuioupay.com/req.do

4 交易

4.1 代收（单笔）

参数名取值说明

reqtype sincomeforreq 实时返回扣款结果

1. 代收处理结果

实时返回扣款结果，返回应答码为 000000 表示扣款成功。

应答码为 200001、200002、999999 表示交易超时，需要商户进行后续查询确认交

易最终状态。

其他返回应答码为失败。

2.代收前置条件：签约绑卡，具体做什么签约，请咨询业务对接人员并索要相应的签约对接

文档。

4.1.1 请求参数

字段中文名称类型可空含义

ver 版本号 c(4) 否 1.0

merdt 请求日期 c(8) 否 yyyyMMdd

orderno 请求流水 c(10,30) 否字母，数字或字母数字组合，当天必须唯一

bankno 总行代码 c(4) 否参见总行代码表

accntno 账号 c(10,28) 否用户账号

accntnm 账户名称 c(30) 否用户账户名称; 户名不能包含特殊英文字符: (. , ? ! /

\ *等)

amt 金额 n(1,12) 否单位：分(单笔最少 5 元)

entseq 企业流水号 c(1,32) 是填写后，系统体现在交易查询中

memo 备注 c(1,64) 是填写后，系统体现在交易查询中

mobile 手机号 c(11) 否短信通知时使用

https://fht-test.fuioupay.com/fuMer/req.do

https://fht-api.fuioupay.com/req.do

https://fht-api-xs.fuioupay.com/req.do

https://fht-test.fuiou.com/fuMer/download/bank.txt


9

certtp 证件类型 c(1) 否证件类型发送交易到银行时用来做校验

certno 证件号 c(20) 否发送交易到银行时用来做校验

addDesc 是否返回交易状态

类别

c(1) 是值为 1，其他值或不填则认为不需要返回交易状态

（transStatusDesc）类别且响应参数无状态类别节点

示例：

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<incomeforreq>

<ver>1.0</ver>

<merdt>20110417</merdt>

<orderno>20110417000001</orderno>

<bankno>0104</bankno>

<accntno>1111111111111111111</accntno>

<accntnm>张三</accntnm>

<amt>100000</amt>

<mobile>13776771234</mobile>

<certtp>0</certtp>

<certno>412209198301220323</certno>

<addDesc>1</addDesc>

</incomeforreq>

4.1.2 响应参数


ret 响应码 c(6) 否见响应代码表

memo 响应描述 c(1,1024) 否

transStatusDesc 交易状态类别 C(60) 是见交易状态类别说明

示例：


<incomeforrsp>

<ret>000000</ret>

<memo>成功</memo>

<transStatusDesc>success</transStatusDesc>

</incomeforrsp>

4.2 签约

本系统对外 api 均使用 HTTP 短连接通讯，通过 POST 请求，商户可调用该接口，进户名、

证件号、手机号验证操作。

注意：

签约手机必须是银行预留手机号；

加密所需的原始字符串通过’|’进行拼接；

https://fht-test.fuiou.com/fuMer/download/rspCode_20160811.xlsx


10

加密使用 sha1 算法进行加密。

4.2.1 接口定义

商户组织如下参数信息(请求参数信息)，通过 form 表单的 post 方式提交到富友,(编码格

式采用 UTF-8),进而进行户名、证件号、手机要前台验证操作。

4.2.2 接口地址

测试地址: https://fht-test.fuioupay.com/fuMer/api_contractAPP.do

生产地址 1: https://fht-api.fuioupay.com/api_contractAPP.do

生产地址 2: https://fht-api-xs.fuioupay.com/api_contractAPP.do

4.2.3 请求参数

字段名称类型是否必填备注

srcChnl 签约来源 char(3) 是 5 要素接口页面默认值为:APP

busiCd 业务类型 char(4) 是默认值为:AC01

bankCd 行别 char(4) 是按住 ctrl_+点击行别代码可直接下载

userNm 户名 char(20) 是姓名，长度介于 1 到 20 位之间字符串，支

持中文

mobileNo 手机号 char(11) 是银行预留手机号码，最大 11 位

credtTp 证件类型 char(4) 是 0:身份证

credtNo 证件号码 char(30) 是证件号码最大长度为 30 位

acntTp 账户类型 char(4) 是 01：借记卡

acntNo 银行卡号 char(30)

是

银行卡号最大长度不能超过 30 位

mchntCd

商户号

char(15)

是

由富友统一分配

按住 ctrl_+点击测试商户，即可查看

isCallback 回拨号码 char(1) 是默认值:0

reserved1

保留字段 1

char(60)

否

保留字段，长度介于 1 到 60 位之间字符串，

支持中文

pageFrontUrl 前台地址 char(200) 否签约完成后,会重定向到该地址

不填则默认为原来商户的地址

isRspExpireDt

是否返回

签约授权

期限

char(1) 否非必填; 0/不填:不返回 1: 返回签约期限;

signature

签名

char(32)

是

sha1 加密产品的字符串具体生成签名方

法:

按住 ctrl_+点击下方，即可查看

https://fht-test.fuioupay.com/fuMer/api_contractAPP.do

https://fht-api.fuioupay.com/api_contractAPP.do

https://fht-api-xs.fuioupay.com/api_contractAPP.do

https://fht-test.fuiou.com/fuMer/download/bank.txt

https://fht-test.fuiou.com/fuMer/faq.html


11

生成 signature 步骤以及使用算法:

第一步：获取原始加密字符串

（1）将参数 add 到 list 集合中

将 srcChnl, busiCd, bankCd, userNm, mobileNo, credtTp, credtNo, acntTp, acntNo,

mchntCd, isCallback, reserved1 放到集合中

示例代码 : List<String> genSign=new ArrayList(); genSign.add("APP");

genSign.add("AC01"); ...//此处省略

(2) 对集合进行排序

示例代码: Collections.sort(genSign);

(3)使用“|”拼接产生加密原数据。

StringBuffer sb=new StringBuffer();

for(String gen:genSign )

{ sb.append(gen); sb.append("|"); }

String bigstr =sb.toString().substring(0,sb.toString().length()-1);

第二步:使用 sha1 算法加密第一步生成的原始字符串，生成一个 16 进行字符串

示例代码: String firstSign=DigestUtils.shaHex(bigstr); 第三步：将第二步生成

的 16 进行字符串，加上秘钥之后，使用 sha1 算法加密生成 signature。将第二步

得到的 16 进制字符串和商户秘钥(key)用“|”拼接，并再次使用 SHA1 算法对拼接形

成的字符串加密，形成最终的 signature 。示例代码 : String

signature=DigestUtils.shaHex(firstSign +"|"+key);

4.3 签约结果通知（异步）

富友以 HTTP 的 POST 方式回调对接系统接口（回调地址由商户提供，富友授权该回

调地址），商户端接收通知成功之后，需要向富友返回 1，富友通知成功，不再通知，否则

会 1 分钟通知一次。通知总共会通知 5 次。

字段名称类型是否必填备注

mchnt_cd 商户号 char(15) 是富友分配给商户的商户号

contract_no 协议号 char(30) 是最大 30 位

acnt_no 银行卡号 char(30) 是银行卡号最大长度不能超过30

位

contract_st

签约状态

char (2)

是

1 已生效（注：签约成功） 0 未

生效（注：签约失败）

contract_pay_code 交易状态码 char (4) 是 0000 （操作成功）

contract_pay_error 交易说明 char(30) 是 Success（交易成功）

contract_sign_dt 生效日期 char(8) 否格式: yyyyMMdd, eg: 20181212

contract_expire_dt 失效日期 char(8) 否格式: yyyyMMdd, eg: 20211212

signature 签名 char 是商户端对接收报文,按照下面

的说明，进行 sha1 加密验证。


12

后台通知校验 signature 生成方法

第一步:组装 signature 加密原始字符串（mercht_pfx：商户秘钥）

String signSource=mchnt_cd +"|"+ contract_no+"|"+acnt_no+"|"+签约请求日期(yyyyMMdd 格

式) +"|"+ contract_st+"|"+ mercht_pfx;

第二步:使用 sha1 算法进行加密

String signature=DigestUtils.shaHex(signSource);

Note:

1. contract_sign_dt/ contract_expire_dt 在异步通知中不参与签名; 注意和签名中的签约请求

日期区分开.

4.4 签约查询接口

本系统对外 api 均使用 HTTP 短连接通讯，通过 POST 请求，编码格式统一采用 UTF-8 格

式，商户可调用该接口，可查询签约记录

注：本接口查询限制每 3 分钟查询一次。

4.4.1 接口地址

测试：https://fht-test.fuioupay.com/fuMer/api_queryContracts.do

生产 1：https://fht-api.fuioupay.com/api_queryContracts.do

生产 2：https://fht-api-xs.fuioupay.com/api_queryContracts.do

4.4.2 示例

模拟 get 请求: https://fht-test.fuioupay.com/fuMer/api_queryContracts.do?xml= . . .

注意:上面仅为简单测试使用 get 请求，实际测试时，请使用 post 请求

4.4.3 请求报文

节点名称中文名称类型可空备注

ver 版本号 char(3) 否默认 1.0

mchntCd 商户号 char(15) 否生产由富友提供，测试 faq 页面提供

contractNo 协议号 char(30) 是签约协议号

startdt 开始日期 char(8) 是 yyyyMMdd

enddt 结束日期 char(8) 是 yyyyMMdd

userNm 户名 char(30) 是持卡人姓名，长度介于 1 到 30 位之

间，支持中文

https://fht-test.fuioupay.com/fuMer/api_queryContracts.do

https://fht-api.fuioupay.com/api_queryContracts.do

https://fht-api-xs.fuioupay.com/api_queryContracts.do

https://fht-test.fuioupay.com/fuMer/api_queryContracts.do


13

mobileNo 手机号 char(11) 手机号、身

份证号、卡

号至少填

写一个

银行预留手机号码，最大 11位

credtNo 身份证号 char(30) 证件号码最大长度为 30位

acntNo 银行卡号 char(30) 银行卡号最大长度不能超过 30位

isRspExpireDt 是否返回

授权日期

char(1) 是值为：1，若填 1，则响应时返回签

约日期和签约失效日期，若不传该

节点或者填其他值，则不返回日期。

signature 签名 char(30) 否 sha1 加密产品的字符串

具体生成签名方法:

查看加密细节

请求报文示例


<custmrBusi>

<ver>1.0</ver>

<mchntCd>0002900F0345178</mchntCd>

<contractNo></contractNo>

<startdt>20170301</startdt>

<enddt>20170308</enddt>

<userNm></userNm>

<mobileNo></mobileNo>

<credtNo>340827198806185218</credtNo>

<acntNo></acntNo>

<isRspExpireDt >1</isRspExpireDt >

<signature>a2b7e8388d233b21fc3f1e75ec127b409e3515e7</signature>

</custmrBusi>

4.4.4 响应报文

名称含义类型是否必填备注

busiCd 业务类型 char(4) 是默认为 AC01

userNm 户名 char(30) 是姓名，长度介于 1到 30位之间字符串，

支持中文

mobileNo 手机号 char(11) 是银行预留手机号码，最大 11位

credtNo 身份证号码 c(30) 是证件号码最大长度为 30位

acntNo 银行卡号 c(30) 是用户银行卡号

mchntCd 商户号 c(15) 是由富友统一提供

查看富友测试信息

contractNo 协议号 c(30) 是富友生成的唯一签约标识

contractSt 是否生效 c(1) 是 1:签约已生效 0:签约未生效

https://fht-test.fuiou.com/fuMer/faq.html


14

2:待验证

contractSignDt 签约日期 c(8) 否日期格式为：yyyyMMdd

contractExpireDt 签约失效日期 c(8) 否日期格式为：yyyyMMdd

acntIsVerify1 户名验证 c(1) 是 1:通过 0:不通过

acntIsVerify2 卡密验证 c(1) 是 1:通过 0:不通过

acntIsVerify3 证件号验证 c(1) 是 1:通过 0:不通过

acntIsVerify4 手机号验证 c(1) 是 1:通过 0:不通过

respCd 响应码 c(6) 是见响应代码表

respCd 响应码 c(6) 是见响应代码表

响应报文示例

操作成功 response xml = <?xml version="1.0" encoding="UTF-8"?>

<custmrBusi>

<busiCd>AC01</busiCd>

<userNm>钱海龙</userNm>

<mobileNo>18810540453</mobileNo>

<credtNo>130229198806130015</credtNo>

<acntNo>6212261202028614338</acntNo>

<mchntCd>0002900F0345178</mchntCd>

<contractNo>000036338623</contractNo>

<contractSt>1</contractSt>

<contractSignDt>20180523</contractSignDt>

<contractExpireDt>20210523</contractExpireDt>

<acntIsVerify1>1</acntIsVerify1>




<respCd>0000</respCd>

<respDesc>6212261202028614338 卡号户名验证成功,卡号密码验证失败,户名证件号验

证成功,手机号码验证失败,签约已生效</respDesc>

</custmrBusi>

操作失败 <?xml version="1.0" encoding="UTF-8"?><custmrBusi>

<respCd>响应码</respCd>

<respDesc>响应描述</respDesc>

</custmrBusi>


15

4.4.5 生成签名

说明:生成 signature 步骤(sha1算法):

第一步:获取原始加密字符串

将请求参数放到集合中（）

示例代码:

List<String> genSign=new ArrayList();

genSign.add("1.0");

genSign.add("0002900F0345178");

genSign.add("20160401");

genSign.add("20160425");

...//此处省略

对集合进行排序示例代码:

Collections.sort(genSign);

(3)使用“|”拼接产生加密原数据。

StringBuffer sb=new StringBuffer();

for(String gen:genSign ){

sb.append(gen); sb.append("|");

}

String bigstr =sb.toString().substring(0,sb.toString().length()-1);

第二步:使用 sha1 算法加密第一步生成的原始字符串，生成一个 16 进行字符串

示例代码:

String firstSign=DigestUtils.shaHex(bigstr);

第三步：将第二步生成的 16 进行字符串，加上秘钥之后，使用 sha1 算法加密生成

signature。

将第二步得到的 16 进制字符串和商户秘钥(key)用“|”拼接，并再次使用 SHA1 算法

对拼接形成的字符串加密，形成最终的 signature。

示例代码:

String signature=DigestUtils.shaHex(firstSign +"|"+key


16

5 交易查询接口

测试环境查询：https://fht-test.fuioupay.com/fuMer/qry.do

生产环境查询 1：https://fht-api.fuioupay.com/qry.do

生产环境查询 2：https://fht-api-xs.fuioupay.com/qry.do

5.1 交易查询（条件可组合）

*注意:查询必须且只传递以下参数


merid 商户号否生产由富友分配

xml 请求参数否使用 XML表示，见各功能点的请求报文定义

mac 校验值否商户号|富友分配给商户的密钥|业务参数

XML，用竖线拼接后用 MD5散列后的

32进制文本

Md5(merid+”|”+key +”|”+xml)

示例：实际传输时请采用 post方式

https://.../req.do?merid =...&xml=...&mac=...

查询说明：

1.单笔不限制查询频次，批量限制 3min 一次。

2.关于批量查询，可以不填请求流水，查询时间段的所有交易。也可以一次查询多个流

水，流水之间用”,”英文逗号分隔，最多 50 个。

5.1.1 请求参数


ver 版本号 c(4) 否 1.1

busicd 业务代码 c(4) 否 AC01 、AP01 或 TP01

orderno 原请求流水 c(10,

30)

是商户通过接口请求代收付交易时的流水号

startdt 开始日期 c(8) 否 yyyyMMdd

enddt 结束日期 c(8) 否 yyyyMMdd 开始和结束时间间隔不能超过 15 天

transst 交易状态 c(1) 是见交易状态码说明

srcModuleCd 交易来源 c(3) 是平台交易值位：WMP

接口交易值为：HMP

ftp 交易值为：FMP

示例：

https://fht-test.fuioupay.com/fuMer/qry.do

https://fht-api.fuioupay.com/qry.do

https://fht-api-xs.fuioupay.com/qry.do


17


<qrytransreq>

<ver>1.1</ver>

<busicd>AP01</busicd>


<startdt>20110407</startdt>

<enddt>20110417</enddt>

<transst>1</transst>

</qrytransreq>

5.1.2 响应参数


ret 响应码 c(6) 否见响应代码表

memo 响应描述 c(1,1024) 否

trans 响应列表组合元素是

trans：


merdt 原请求日期 c(8) 否 yyyyMMdd

orderno 原请求流水 c(10,30) 否数字串，当天必须唯一

accntno 账号 c(10,28) 否用户账号

accntnm 账户名称 c(30) 否用户账户名称

amt 交易金额 n(1,12) 否单位：分

entseq 企业流水号 c(1,32) 是填写后，系统体现在交易查询和外部通知中

memo 备注 c(1,64) 是填写后，系统体现在交易查询和外部通知中

state 交易状态 c(2) 否见交易状态码说明

result 交易结果 c(1,8) 是

reason 结果原因 c(1,1024) 是

tpst 是否退票 c(1) 是 1.是 0.否（仅 AP01 有）

rspcd 银行响应码 c(6) 否参见提供返回码(交易发送中、未发送该节点值为空)

transStatu

sDesc

交易状态类

别

c(1,60) 否见交易状态类别说明

示例：


<qrytransrsp>

<ret>000000</ret>

<memo>成功</memo>

<trans>



<accntno>1111111111111111111</accntno>


<amt>100000</amt>

https://fht-test.fuiou.com/fuMer/download/rspCode_20160811.xlsx


18

<entseq> </entseq>

<memo> </memo>

<state>1</state>

<result>渠道资金到账已复核,交易已发送</result>

<reason>交易成功</reason>

<tpst>0</tpst>

<rspcd>000000</rspcd>


</trans>

<trans>



<accntno>1111111111111111111</accntno>


<amt>100000</amt>

<entseq>PY-HF1-JK-201606010004</entseq>

<memo>auto_loan</memo>

<state>1</state>

<result>渠道资金到账已复核,交易已发送</result>

<reason>交易成功</reason>

<tpst>0</tpst>

<rspcd>000000</rspcd>


</trans>

</qrytransrsp>

5.2 账户余额查询

本系统对外 api 均使用 HTTP(s)短连接通讯，报文格式采用 xml，提交方式为 POST(编码

格式采用 UTF-8)。商户可调用该接口，查询虚拟账户余额情况。

注：本接口查询限制每 3 分钟查询一次。

5.2.1 协议格式

同步 https 请求响应。

请求数据采用 POST 表单提交。

响应数据采用 XML。

请求和响应数据使用 UTF-8 字符集编码。

通过 MD5 算法进行验签校验。

可空：是:表示必须要有值，否:则表示可以没有值

接口返回金额单位为分。


19

5.2.2 接口地址

测试地址: https://fht-test.fuioupay.com/fuMer/t0zj_qryAcnt.do

生产地址 1: https://fht-api.fuioupay.com/t0zj_qryAcnt.do

生产地址 2: https://fht-api-xs.fuioupay.com/t0zj_qryAcnt.do

5.2.3 请求报文


ver 版本号 char(3) 否 1.0

merid 商户号 char(15) 否由富友分配

mac 校验值 char(1024) 否版本号+商户号+商户秘钥

md5Source =ver+”|”+merid+”|”+mchntKey

生成校验值:（mchntKey:商户秘钥）

DigestUtils.md5Hex(md5Source.getBytes(“utf-

8”))

请求报文示例

实际传输时请采用 post 方式

https://fht-test.fuioupay.com/fuMer/t0zj_qryAcnt.do?xml=..

查询请求示例报文:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<qryacnt>

<ver>1.0</ver>

<merid>0002900F0345178</merid>

<mac>579b96ad3e2a0d661dfcc87e2b98eb90</mac>

</qryacnt>

5.2.4 响应报文


ret 响应码 c(6) 否响应码(富友提供)

memo 响应描述 c(1,1024) 否响应描述(富友提供)

ctamt 账面余额 c(1,12) 否单位:分

caamt 可用余额 c(1,12) 否单位:分

cuamt 未转结余额 c(1,12) 否单位:分

cfamt 冻结余额 c(1,12) 否单位:分

mac 校验值 c(1024) 否商户号|响应码|响应描述|账面余额|可用余额|未转

余额|冻结余额|商户秘钥(由富友提供)

https://fht-test.fuioupay.com/fuMer/t0zj_qryAcnt.do

https://fht-api.fuioupay.com/t0zj_qryAcnt.do

https://fht-api-xs.fuioupay.com/t0zj_qryAcnt.do

https://fht-test.fuioupay.com/fuMer/t0zj_qryAcnt.do?xml


20

伪代码如下：

md5Source = merid+”

|”+ret+”|”+memo+”|”+ctamt+”|”+caamt+”|”+cuamt+”

|”+cfamt+"|"+mchntKey;

校验:（mchntKey:商户秘钥，mac：富友返回校验值）

DigestUtils.md5Hex(md5Source.getBytes(“utf-8”));

响应报文示例

查询成功返回示例报文: <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<qryacnt>

<ret>000000</ret>

<memo>操作成功</memo>

<ctamt>68593179434</ctamt>

<caamt>68497163683</caamt>

<cuamt>94652629</cuamt>

<cfamt>1363122</cfamt>

<mac>c0dbdcbdc45f2ab635935623f7fb59bc</mac>

</qryacnt>

查询失败返回示例报文: <qryacnt>

<ret>111167</ret>

<memo>查询请求过于频繁，请稍后再试</memo>

<mac>88be3279a69fcf80202f6e223c32fe18</mac>

</qryacnt>


21

6 附录

6.1 证件类型代码表

城市代码城市名称

0 身份证

1 护照

2 军官证

3 士兵证

5 户口本

7 其他

6.2 交易状态码说明

业务代码状态码说明

AC01

0 交易未发送

1 交易已发送且成功

2 交易已发送且失败

3 交易发送中

7 交易已发送且超时


22

6.3 签约查询应答码附录

以下是签约查询返回应对码及对应的原因描述。

应答码原因描述

0000 受理成功

300001 报文格式错，包括但不限于：

手机号码格式错

商户号格式错

商户不存在

证件类型不存在

证件号格式错

账户类型不存在

账户格式错

行别代码不存在

300002 报文验签错

300003 低风险商户无需导入

300004 签约来源未定义

300005 商户不存在

300013 手机号已绑定多张银行卡

300014 当日总验证次数超限

300015 已存在更高级别的签约方式

您已进行过 IVR 签约,不能在进行 APP 签约

您已进行过 POS 签约,不能在进行 APP 签约

您已进行过 POS 签约,不能在进行 IVR 签约

300016 签约已生效,不能重复签约

300017 卡密已经生效，不允许 APP 签约

7 双活域名切换

7.1 域名故障监测切换（生产地址 1 和生产地址 2 之间的切换）

建议域名故障监测切换方案 1：

单独开启网络检测线程，每分钟监测一次，如果监测出当前生产地址链接超时

(ConnectTimeout)，则每 10 秒检测一次，超过 N 次(建议 5-10 次)后切换另一生产地址。

建议域名故障监测切换方案 2：

实时交易检测，记录连续链接超时(ConnectTimeout)次数，超过 N 次(建议 5-10 次)后

切换另一生产地址。

切换方案 1 可参考 java 实现类(仅供参考)

SingleFuiouDomainDemo.java（对接富友单业务域名）


23

MultiFuiouDomainDemo.java(对接富友多业务域名)

其中域名心跳检测地址为：域名+"/heartbeat"

如域名为：https://fht.fuioupay.com,心跳检测地址：https://fht.fuioupay.com/heartbeat

富友代收接口文档 - fuiou · 2020. 6. 16. · 富友代收付平台企业直连接入规范...

Documents