关于开放平台

飞瀚开放平台面向广大开发者,提供线上数字营销、企业福利等一站式解决方案。商户及开发者可查阅平台 API 文档,了解当前已开放的各类业务接口,灵活选用在线直充、卡密发放、实物购买等服务并自主完成接口对接。平台具备完善的商品与活动支撑能力,可全面满足商户综合权益运营需求,助力企业实现福利发放、活动营销等多场景应用。

我司作为虚拟商品充值供应商,简称 CP;调用我方接口开展业务的合作商户,统一称为业务合作方(SP)。

平台服务概览

🚀

申请接入

当您需要飞翰开放平台提供对接服务时,即可提交申请,我们十分欢迎您,并安排专人为您对接!

📖

开发指南

您可在此详细了解对接业务的各种规范,帮您快速开发。

🛠️

帮助与支持

您可以在此查看常见问题。

📋

API 文档

了解飞翰开放平台目前提供的所有可对接的业务接口以及对接方案详情。

对接流程

1

创建项目

会员实名认证后登陆 api.ofpay.com 创建项目,通过我司商务审核之后生成一个A开头的编号(如A08566)。

2

IP白名单

向我司对接商务提供SP服务器的出口IP地址(可多个IP)和秘钥(keystr)进行绑定。

3

商品价格设定

通知我司商务商品设定协议价格。

4

资金权限开通

通知我司商务开通账户资金权限和商品资金权限。

5

账户充值

向我司账户上打款后,方可正式下单。

6

对账方式

SP可以登陆接口后台查看交易记录进行对账,也可以使用对账接口进行自动对账。

关于接口的说明

数据传输格式:该接口使用HTTP协议,请求数据传输格式如下:

【接口URL】?【参数名称1】=【参数值1】&【参数名称2】=【参数值2】……

生产环境

地址 https://api2.ofpay.com
userid(项目编号) 项目编号,通过我司商务审核生成的A开头编号,如 A08566
userpws(项目密码) 将通过注册短信下发,请妥善保管
keystr(项目密钥) 联系我司商务获取

联调环境

地址 http://apitest.ofpay.com
userid A08566
userpws md5(of111111) 小写
秘钥(keystr) OFCARD

⚠️ 该数据只能测试环境使用,正式环境禁止使用测试账号。

开发指南

HTTP请求方式:POST, GET

签名算法(MD5)

MD5签名计算方法
包体 = 参数1 + 参数2 + ... + KeyStr
md5_str = md5(包体).toUpperCase()  // 32位大写
KeyStr(秘钥):必须由客户提供给欧飞商务进行绑定,否则签名验证失败。KeyStr不在接口间进行传输。

全局返回值

参数名 类型 说明
retcode string 操作返回代码,1成功,其他数字具体错误在err_msg返回
err_msg string 错误描述,如请求得到正确返回,此处将为空

订单状态说明

状态码 说明
0 充值中
1 充值成功
9 充值失败(可退款)
-1 查不到订单(需人工核实)

基础接口

用户余额查询

v6.0

此接口可以查询SP用户的信用点余额,可以提醒SP商户补充信用点

POST/GET {URL}/newqueryuserinfo.do
模拟请求
/newqueryuserinfo.do?userid=A08566&userpws=4c625b7861a92c7971cd2029c2fd3c4a&version=6.0

输入参数

名称 是否必须 类型 备注
userid string SP项目编码,如A08566
userpws string 项目密码的md5值(32位小写)
version string 固定值6.0

返回参数

名称 类型 备注
retcode string 1成功
totalBalance string 账户余额
oufeiBalance string 欧飞账户资金余额
feihanBalance string 飞翰资金账户余额

返回示例

<?xml version="1.0" encoding="GB2312"?>
<userinfo>
  <err_msg/>
  <retcode>1</retcode>
  <userId>A08566</userId>
  <totalBalance>100120801.5</totalBalance>
  <oufeiBalance>100120301.5</oufeiBalance>
  <feihanBalance>500</feihanBalance>
</userinfo>

商品详情查询

v6.0

根据商品编号查询商品信息

POST/GET {URL}/querycardinfo.do
模拟请求
/querycardinfo.do?userid=A08566&userpws=4c625b7861a92c7971cd2029c2fd3c4a&cardid=140101&version=6.0

输入参数

名称 是否必须 类型 备注
userid string SP项目编码
userpws string 项目密码md5值(32位小写)
cardid string 商品编号,由我司商务提供
version string 固定值6.0

返回参数

名称 类型 备注
err_msg string 错误信息
retcode string 返回码,1成功
cardid string 商品编号
pervalue string 面值
inprice string 价格
cardname string 商品名称
innum string 库存数量

返回示例

<?xml version="1.0" encoding="gb2312"?>
<cardinfo>
  <err_msg></err_msg>
  <retcode>1</retcode>
  <ret_cardinfos>
    <card>
      <cardid>220612</cardid>
      <pervalue>1</pervalue>
      <inprice>1</inprice>
      <cardname>Q币1元直充</cardname>
      <innum>30</innum>
    </card>
  </ret_cardinfos>
</cardinfo>

订单充值状态查询

v6.0

此接口用于下单之后查询充值状态(无需签名)

POST/GET {URL}/api/query.do
模拟请求
/api/query.do?userid=A08566&spbillid=sp20260427001

输入参数

名称 是否必须 类型 备注
userid string SP项目编码
spbillid string SP商户订单号

返回参数

名称 类型 备注
err_msg string 错误信息
errorCode string 返回码,1成功
errorMsg string 错误描述
mac string mac签名
result string 充值状态,0充值中、1成功、9失败

返回示例

<?xml version="1.0" encoding="GB2312"?>
<userinfo>
  <err_msg/>
  <errorCode>1</errorCode>
  <errorMsg></errorMsg>
  <mac>mac签名</mac>
  <result>1</result>
</userinfo>

返回状态说明

  • 0 - 充值中
  • 1 - 成功
  • 9 - 失败

订单详情查询

v6.0

根据外部订单号查询订单详情,支持XML和JSON格式返回(需签名)

POST/GET {URL}/queryOrderInfo.do
签名算法
包体 = userid + userpws + sporder_id
md5_str = md5(包体 + KeyStr).toUpperCase()
模拟请求
/queryOrderInfo.do?userid=A08566&userpws=4c625b7861a92c7971cd2029c2fd3c4a&sporder_id=sp20260427001&md5_str=3A31B081DB896F3DBA4EA7EC0AD4AB11&version=6.0

输入参数

名称 是否必须 类型 备注
userid string SP项目编码
userpws string 项目密码md5值
sporder_id string 商家下单时传入的订单号
md5_str string 签名串
version string 固定值6.0
format string xml或json,默认xml

返回参数

名称 类型 备注
err_msg string 错误信息
retcode string 返回码,1成功
orderid string 欧飞订单号
cardid string 商品编码
cardnum string 商品数量
ordercash string 订单额
cardname string 商品名称
sporder_id string 外部订单号
game_userid string 充值账号(直充类)
game_state string 充值状态,1充值成功、0充值中、9充值失败
oper_date string 订单完成时间(直充类)
pay_state string 支付状态
esupOrderNo string 欧飞订单号(卡密类)
cardno string 卡号(卡密类)
cardpws string 卡密(卡密类)
expiretime string 有效期(卡密类)

返回示例

直充类XML返回
<?xml version="1.0" encoding="GB2312"?>
<orderinfo>
    <err_msg></err_msg>
    <retcode>1</retcode>  返回码
    <orderid>S2205244579789</orderid> 欧飞订单号
    <cardid>142706</cardid> 商品编码
    <cardnum>1</cardnum> 商品数量
    <ordercash>10</ordercash> 订单额
    <cardname>重庆移动手机快充10元</cardname> 商品名称
    <sporder_id>581448186439143424</sporder_id> 外部订单号
    <game_userid>131111111111</game_userid> 充值账号
    <game_state>0</game_state> 充值状态,1充值成功、0充值中、9充值失败
    <oper_date>2020-09-30 15:03:19</oper_date> 订单完成时间
    <pay_state>1</pay_state> 支付状态
</orderinfo>
卡密类XML返回
<orderinfo>
    <err_msg/>
    <retcode>1</retcode>
    <orderid>S1505171935460</orderid>
    <cardid>210302</cardid>
    <cardnum>1</cardnum>
    <ordercash>14.7</ordercash>
    <cardname>网易一卡通15元卡密</cardname>
    <sporder_id>367873857</sporder_id>
    <esupOrderNo>15051723993221</esupOrderNo>
    <game_state>1</game_state> --1充值成功、0充值中、9充值失败
    <pay_state>1</pay_state>
    <cards>
        <card>
            <cardno>131111111111</cardno>
            <cardpws>499751945</cardpws>
            <expiretime>2016-04-30</expiretime>
        </card>
    </cards>
</orderinfo>
直充类JSON返回
{
    "cardnum": "1",  数量
    "game_state": 0,  充值状态,1充值成功、0充值中、9充值失败
    "orderid": "S2205244579789",  欧飞订单
    "cardname": "重庆移动手机快充10元",  商品名称
    "cardid": "142706",  商品编号
    "billState": 1,  支付状态
    "sporder_id": "581448186439143424",  外部订单号
    "ordercash": "10",  订单额
    "oper_date": "2020-09-30 15:03:19",  订单完成时间
    "retcode": "1",  状态码
    "game_userid": "18375734568"  充值账号
}
卡密类JSON返回
{
    "cardnum": "1",  数量
    "cards": [
        {
            "expiretime": "4001-01-31",  有效期
            "cardpws": "https://s.suhan.cn/b5IZVr?s=3856112",  卡密
            "cardno": "1n3m2022020123856112"  卡号
        }
    ],
    "game_state": 1,  充值状态,1充值成功、0充值中、9充值失败
    "orderid": "S2203314560750",  欧飞订单
    "cardname": "肯德基代金券50元卡密",  商品名称
    "cardid": "15010024",  商品编号
    "billState": 1,  支付状态
    "sporder_id": "Sp20220331161707z",  外部订单号
    "ordercash": "50",  订单额
    "retcode": "1"  状态码
}

对账接口

订单列表查询

v6.0

⚠️ 此接口只查询3天内的订单

POST/GET {URL}/querybill.do
签名算法
包体 = userid + userpws + cardid + starttime + endtime
md5_str = md5(包体 + KeyStr).toUpperCase()

输入参数

名称 是否必须 类型 备注
userid string SP项目编码
userpws string 项目密码md5值
cardid string 商品编码,不填为全部
orderstat int 订单状态,默认5
classtype int 类目编号,默认0所有
starttime string 开始时间(yyyyMMdd)
endtime string 结束时间(yyyyMMdd)
md5_str string 签名串
version string 固定值6.0

返回格式

CP流水号|SP订单号|商品编号|商品数量|充值账号|订单金额|订单时间|订单状态
订单总数:xxx|订单总额:xxx

账务明细查询

v6.0

⚠️ 不可跨月查询(需签名)

POST/GET {URL}/financeQuery.do
签名算法
包体 = userid + userpws + starttime + endtime + pagenum + pagesize
md5_str = md5(包体 + KeyStr).toUpperCase()
模拟请求
/financeQuery.do?md5_str=3A31B081DB896F3DBA4EA7EC0AD4AB11&pagesize=200&endtime=20260426&userpws=4c625b7861a92c7971cd2029c2fd3c4a&starttime=20260426&pagenum=1&userid=A08566&version=6.0&paymenttype=

输入参数

名称 是否必须 类型 备注
userid string SP项目编码
userpws string 项目密码md5值
starttime string 开始时间,格式yyyy-MM-dd HH:mm:ss
endtime string 结束时间,格式yyyy-MM-dd HH:mm:ss
pagenum string 当前页
pagesize string 页条数
paymenttype string 收支类型 0:收入 1:支出
md5_str string 签名串
version string 固定值6.0

返回参数

名称 是否必须 类型 备注
occurTime string 时间
dlcDetailId string 流水号
paymentType string 收支类型
fundsType string 业务类型
inComeCost string 收入金额
expenditureCost string 支出金额
leftBalance string 账户余额
billId string 业务单号
company string 公司

返回示例

<?xml version="1.0" encoding="GBK" ?>
<financeInfo>
    <err_msg></err_msg>
    <retcode>1</retcode>
    <finances>
        <totalCount>68</totalCount>
        <pageNum>1</pageNum>
        <pageSize>1</pageSize>
        <finance>
            <occurTime>2025-12-04 19:20:03</occurTime>
            <detailId>KPD251204191265017</detailId>
            <inOutType>订单支出</inOutType>
            <fundsType>正常消费</fundsType>
            <inComeCost></inComeCost>
            <expenditureCost>90</expenditureCost>
            <leftBalance>996481356.172</leftBalance>
            <billId>S2512045470752</billId>
            <company>欧飞</company>
        </finance>
    </finances>
</financeInfo>

直充接口

归属地查询

v6.0

⚠️ 接口不支持json格式请求(无需签名)

POST/GET {URL}/queryMobileInfo.do
模拟请求
/queryMobileInfo.do?userid=A08566&phoneno=131111111111

输入参数

名称 是否必须 类型 备注
userid string SP项目编码
phoneno string 7或11位手机号码

返回参数

名称 是否必须 类型 备注
province string 省份
city string 城市
errMsg string 错误信息
oriOperator string 原运营商名称
retCode string 返回码
phoneNo string 手机号
operator string 运营商名称

返回示例

{"city":"广州","operator":"移动","phoneNo":"1581585","province":"广东","retCode":"1"}

直充下单

v6.0

直充卡密类通用接口,支持话费、流量,游戏等多种直充和卡密(需签名)

POST/GET {URL}/newOnlineOrder.do
签名算法
包体 = userId + userPws + cardId + buyNum + spOrderId + orderTime + customerNo
md5Str = md5(包体 + KeyStr).toUpperCase()
模拟请求(直充)
/newOnlineOrder.do?buyNum=1&retUrl=url&md5Str=0C887C60EFAEA4E01C34255F639B9CB1&spOrderId=202604271354U2287508&userId=A08566&version=6.0&orderTime=20260427135427&cardId=50168&userPws=4c625b7861a92c7971cd2029c2fd3c4a&customerNo=ocZAp5IcIYfALBRJYfz2qZYhUpVc
模拟请求(话费)
/newOnlineOrder.do?buyNum=100&retUrl=url&md5Str=0C887C60EFAEA4E01C34255F639B9CB1&spOrderId=202604271354U2287508&userId=A08566&version=6.0&orderTime=20260427135427&cardId=140101&userPws=4c625b7861a92c7971cd2029c2fd3c4a&customerNo=ocZAp5IcIYfALBRJYfz2qZYhUpVc
提示:请求参数包含拓展字段 extendParams(JSON格式),可根据需要添加

输入参数

名称 是否必须 类型 备注
userId string SP项目编码
userPws string 项目密码md5值(32位小写)
cardId string 商品编码,话费固定值140101
buyNum string 购买数量
spOrderId string Sp商家的订单号,唯一
orderTime string 订单时间(yyyyMMddHHmmss)
customerNo string 充值账号
md5Str string 签名
retUrl string 充值回调地址
version string 固定值6.0
extendParams string 拓展字段(JSON格式)

返回参数

名称 是否必须 类型 备注
errMsg string 错误描述
retCode string 返回码,结果参考交易结果码备注
orderId string 订单号
cardId string 商品编号
cardName string 商品名称
buyNum string 数量(话费填写面值)
orderCash string 订单金额
spOrderId string 下游订单号
customerNo string 充值账号
orderState string 充值状态
cardNo string 卡号
cardPws string 卡密
expireTime string 有效期

返回示例

直充类XML返回
<?xml version="1.0" encoding="GB2312" ?>
<orderInfo>
    <errMsg></errMsg>  // 错误描述
    <retCode>1</retCode>  // 返回码,结果参考交易结果码备注
    <orderId>S1212121212</orderId>  // 订单号
    <cardId>140101</cardId>  // 商品编号
    <cardName>江苏移动100元直充</cardName>  // 商品名称
    <buyNum>1</buyNum>  // 数量
    <orderCash>100</orderCash>  // 订单金额
    <spOrderId>312321312321321</spOrderId>  // 下游订单号
    <customerNo>13813888888</customerNo>  // 充值账号
    <orderState>0</orderState>  // 如果成功将为1,撤销(充值失败)为9,充值中为0,只能当状态为9时,商户才可以退款给用户。
</orderInfo>
卡密类XML返回
<?xml version="1.0" encoding="GBK"?>
<orderInfo>
    <errMsg></errMsg>
    <retCode>1</retCode>
    <orderId>S2202214544905</orderId>
    <cardId>64349807</cardId>
    <cardName>全国中石油加油卡卡密200元</cardName>
    <buyNum>1</buyNum>
    <orderCash>200</orderCash>
    <spOrderId>Sp20220221162833s</spOrderId>
    <customerNo>15715155515</customerNo>
    <orderState>1</orderState>
    <cards>
        <card>
            <cardNo>1n3m202202013841113</cardNo>  -- 卡号
            <cardPws>1n3m202202013841113</cardPws>  -- 密码(字符串、短链)
            <expireTime>2025-01-31 00:00:00</expireTime>  -- 有效期
        </card>
    </cards>
</orderInfo>

下单回调说明

  • retUrl 不为空时,系统将在有结果时发送成功信息
  • 回调参数:ret_code(1成功/9撤销)、sporder_idordersuccesstimeerr_msg
  • 提交方式:POST
  • 成功返回:Y

直充订单回调

v6.0

订单充值结果回调通知

GET 回调地址?ordersuccesstime=xxx&ret_code=xxx&sporder_id=xxx&err_msg=xxx
模拟请求
回调地址?ordersuccesstime=2026-04-27 13:33:33&ret_code=1&sporder_id=sp202604270001&err_msg=

请求参数

名称 是否必须 类型 备注
ordersuccesstime string 充值成功时间
ret_code string 充值结果 1成功9失败
sporder_id string 外部订单号
err_msg string 失败原因
响应要求:成功返回 Y

实物接口

物流查询

v6.0

查询实物订单物流信息(需签名)

POST/GET {URL}/queryExpressTrack
模拟请求
/queryExpressTrack?userId=A08566&userPws=4c625b7861a92c7971cd2029c2fd3c4a&spOrderId=20251229000001655258&md5Str=3A31B081DB896F3DBA4EA7EC0AD4AB11&version=6.0

输入参数

名称 是否必须 类型 备注
userId string SP项目编码
userPws string 项目密码md5值(32位小写)
spOrderId string 商家传给欧飞的唯一单号
expressNo string 物流单号
expressCompanyNo string 物流公司编号
md5Str string 签名串
version string 固定值6.0

返回参数

名称 是否必须 类型 备注
errMsg string 错误描述
retCode string 返回码,结果参考交易结果码备注
expressNo string 物流单号
expressName string 物流公司名称
expressState string 物流状态
time string 时间
context string 内容

返回示例

<?xml version="1.0" encoding="GBK"?>
<physicalInfo>
    <errMsg></errMsg>
    <retCode>1</retCode>
    <expressTrackInfos>
        <expressTrackInfo>
            <expressNo>TEST19734944054</expressNo>
            <expressName>**物流</expressName>
            <expressState>揽收</expressState>
            <time>2023-04-04 15:50:40</time>
            <context>您的快件因【寄件人超时未准备好货物】操作再取,下次揽收时间2023-04-08 23:00-2023-04-09 00:00</context>
        </expressTrackInfo>
        <expressTrackInfo>
            <expressNo>TEST19734944054</expressNo>
            <expressName>**物流</expressName>
            <expressState>签收</expressState>
            <time>2023-04-04 15:24:40</time>
            <context>揽收任务已分配给工作人员。</context>
        </expressTrackInfo>
    </expressTrackInfos>
</physicalInfo>

实物下单

v6.0

实物下单接口,与直充下单共用接口,需要额外传 receiveInfo 参数

POST/GET {URL}/newOnlineOrder.do
模拟请求
/newOnlineOrder.do?buyNum=1&orderTime=20260427150005&retUrl=回调地址&cardId=114256&md5Str=BF6A34619615FF139536F5DDAE28AB06&receiveInfo=收件人信息(JSON,URLEncodeGBK编码)&userPws=b91adb92903d776a8846ad1b9525dc37&spOrderId=T260427140007676&userId=A08566&version=6.0

请求参数

名称 是否必须 类型 备注
userId string SP项目编码
userPws string 项目密码md5值(32位小写)
cardId string 商品编码,话费固定值140101
buyNum string 购买数量
spOrderId string Sp商家的订单号,唯一
orderTime string 订单时间(yyyyMMddHHmmss)
customerNo string 充值账号
md5Str string 签名
retUrl string 充值回调地址
version string 固定值6.0
receiveInfo string 收件人信息(JSON,URLEncodeGBK编码)

receiveInfo格式

{
  "receiverName": "收件人姓名",
  "receiverMobile": "收件人手机号",
  "address": "详细地址(必须包含省市)"
}

返回参数

名称 是否必须 类型 备注
errMsg string 错误描述
retCode string 返回码,结果参考交易结果码备注
orderId string 订单号
cardId string 商品编号
cardName string 商品名称
buyNum string 数量
orderCash string 订单金额
spOrderId string 下游订单号
customerNo string 充值账号
orderState string 充值状态
cardNo string 卡号
cardPws string 卡密
expireTime string 有效期

返回示例

<?xml version="1.0" encoding="GB2312" ?>
<orderInfo>
    <errMsg></errMsg>  错误描述
    <retCode>1</retCode>  返回码
    <orderId>S1212121212</orderId>  订单号
    <cardId>114256</cardId>  商品编号
    <cardName>心相印云感柔肤卷纸110克*30卷</cardName>  商品名称
    <buyNum>1</buyNum>  数量
    <orderCash>65.5</orderCash>  订单金额
    <spOrderId>T260427140007676</spOrderId>  下游订单号
    <customerNo>13111111111</customerNo>  充值账号
    <orderState>0</orderState>  充值状态,1成功、9失败、0充值中
</orderInfo>

实物下单回调说明

  • 下单回调:系统请求 ret_code(1成功/9失败)、sporder_idordersuccesstimeerr_msg
  • 发货回调:orderType=PHYSICALexpressNoexpressCompanyTyperet_code=2表示发货

实物订单回调

v6.0

实物订单发货回调通知

POST 回调地址
模拟请求
提交方式:POST
/回调地址?orderType=PHYSICAL&expressOrderList=%255B%257B%2522expressNo%2522%253A%25229886818655373%2522%252C%2522expressCompanyType%2522%253A%2522%25D3%25CA%25D5%25FE%25BF%25EC%25B5%25DD%25B0%25FC%25B9%25DC%2522%257D%255D&err_msg=&ordersuccesstime=20220426094600&sporder_id=PHYSICAL20220425141047&ret_code=2

请求参数

名称 是否必须 类型 备注
expressOrderList JSONArray 物流信息列表
ret_code string 充值结果 1成功9失败2已发货
sporder_id string 外部订单号
err_msg string 失败原因
orderType string 固定值:PHYSICAL
ordersuccesstime string 订单成功时间,格式yyyyMMddHHmmss

expressOrderList格式

名称 是否必须 类型 备注
expressNo string 物流单号
expressCompanyType string 物流公司
注意:SP得到请求信息后,请自行处理系统订单状态。如SP系统问题没收到返回结果,或者在长时间内没有收到充值成功信息,可调用查询接口查询订单充值状态

错误码列表

Code Msg
1 成功
1001 商户名验证错误
1002 商户IP验证错误
1003 MD5串验证错误
1004 此商品暂不可用
1005 购买的商品数量超出系统要求
1006 充值金额超出系统限制
1007 账户金额不足
1008 缺少必需参数
1010 查询结果为空
12 库存不足
319 充值的手机号不正确
321 暂时不支持此类手机号的充值
331 订单生成失败
4001 支付异常
2015 对账接口维护
9998 参数格式错误
9999 未知错误(不能作失败处理,需要人工核实)

常见问题

项目编号及密码怎么获取?

答:会员实名认证后登陆api.ofpay.com 创建项目通过我司商务审核之后生成一个A开头的编号,同时绑定的会员手机会收到一条项目密码的短信,接口调用时使用。userid 为A开头编号,userpws 为 项目密码md5值。

秘钥(keystr)有什么作用?

答:秘钥是保障双方数据安全传输的基础,必须由客户提供给欧飞商务进行绑定,否则签名验证失败。KeyStr不在接口间进行传输。

订单状态未知怎么办?

答:订单状态未知原因有很多,一般可能是商品库存不足、充值通道不稳定等多种情况,不可当失败处理;可以稍后再次查询,或者咨询专属商务或运营,我们会及时为您解答。

在开发过程中如遇任何问题,欢迎您随时通过页面右侧的 在线咨询 与我们联系。