微信小店
取消
中文
中文
EN
取消
  • 微信小店

    • # 资金结算

    本文档面向自研商家和 ISV 服务商，覆盖资金结算模块从余额查询、流水对账、提现到结算账户管理的完整接入流程。

    # 开发前准备

    # 接入流程

    # 账户余额与流水查询

    本节覆盖 3 种数据对象，目标是建立完整的资金数据同步与对账体系。

    数据对象 说明 接口
    账户快照 可提现余额 available_amount
    待结算余额 pending_amount

    总账——此刻账户有多少钱    		 [API] 获取账户余额 / getbalance
    资金流水 每笔资金变动记录
    flow_id / amount / funds_type / flow_type
    - flow_type：收支方向（1=收入 / 2=支出）
    - funds_type：业务类型（订单支付/提现/服务费等）

    收付明细——每笔钱的进出明细    		 [API] 获取资金流水列表 / getfundsflowlist
    [API] 获取资金流水详情 / getfundsflowdetail
    订单流水 每个订单的完整费用拆解
    实收 / 服务费 / 佣金 / 运费险 / 补贴

    业务侧明细——这笔交易应该收/付多少    		 [API] 查询订单流水列表 / listorderflow
    [API] 获取订单详情 / getorder（跨模块）
    %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%% flowchart LR %% === 账户快照 === A["[API] 获取账户余额<br/>getbalance"] -->|"展示可提现/待结算"| R[商家管理后台] %% === 资金流水明细 === B["[API] 获取资金流水列表<br/>getfundsflowlist"] -->|"循环遍历"| C["[API] 获取资金流水详情<br/>getfundsflowdetail"] %% === 订单流水（对账校验）=== D["[API] 查询订单流水列表<br/>listorderflow"] E["[API] 获取订单详情<br/>getorder"] %% --- 跨层连线 --- C -->|"funds_type 为订单相关"| E D -.->|"总量交叉比对"| C %% --- 非接口节点样式 --- style R fill:#ffffff,stroke:#0ab8a6,color:#666666

    关键调用规则：

    1. [API] 获取资金流水列表 / getfundsflowlist 返回的是 flow_id 列表（不含金额），需逐一调 [API] 获取资金流水详情 / getfundsflowdetail 获取详情
    2. [API] 获取资金流水详情 / getfundsflowdetail 返回的 funds_type 决定该笔流水应该用哪种方式对账（见下文「对账策略」）
    3. [API] 查询订单流水列表 / listorderflow 与 [API] 获取资金流水详情 / getfundsflowdetail 是两个独立的数据源，用于交叉验证

    注意事项：

    • 当日流水延迟：当日流水次日 16 点后 出账。16 点前查询 end_time 最大值为前一天 0 点
    • 先用后付订单：此类订单需用户确认收货并自动付款后才产生资金流水，存在额外时间差
    • 一笔订单多条流水：同一笔订单可能产生多条不同 funds_type 的记录（如支付 1 条 + 佣金扣除 1 条 + 服务费 1 条），不要假设一一对应
    • 对账必须过滤已结算订单：资金流水反映的是实际已入账金额，[API] 查询订单流水列表 / listorderflow 查询时需按 order_settle_state 过滤已结算状态（值=60），否则未结算订单的金额（可能仍有退款/售后变动）会导致对账差异

    # 对账策略

    对账的本质是用 订单流水（业务侧） 的数据来验证 资金流水（资金侧） 的数据是否一致。资金流水是"收付明细"，订单流水是"业务明细"。

    flow_type 是判断一笔流水收入或支出方向的最直接字段，[API] 获取资金流水详情 / getfundsflowdetail 返回：

    flow_type 值 含义
    1 收入（资金流入账户）
    2 支出（资金从账户流出）

    funds_type（资金流水类型）是同一接口返回的另一个字段，标识每一笔资金变动的业务原因——这笔钱为什么进、为什么出。一笔订单完成后，平台会自动生成多条不同 funds_type 的流水记录（支付收入、技术服务费扣除、达人佣金扣除等）。

    实际使用建议：先用 flow_type 区分收支方向，再用 funds_type 确认业务类型，两者结合可以快速定位每笔流水的性质。

    # 按 funds_type 分类的对账方式

    不同类型的资金变动，按 收入（flow_type=1）/ 支出（flow_type=2） 分为两类，每种类型都有对应的校验方式：

    收入类（flow_type=1，钱进来了——验证"应该收的是否全到了"）

    funds_type 描述 校验方式 校验动作
    1 订单支付 订单流水交叉验证 订单流水 mch_received_amount 求和 = 资金流水金额
    5 提现退票 与提现(4)配对核销 同一 withdraw_id 下，退票金额 = 原提现金额；未退票的查 getwithdrawdetail 状态是否 SUCCESS
    15 回补极速退款垫资 与垫资(14)配对核销 同一订单下，回补金额 = 原垫资金额，差额即为实际垫资成本
    17 预付运费退回 订单流水交叉验证 订单流水运费相关字段求和 = 资金流水金额
    19 平台优惠补贴 订单流水交叉验证 订单流水平台补贴相关字段求和 = 资金流水金额
    21 国补发放 订单流水交叉验证 订单流水国补相关字段求和 = 资金流水金额
    23 注销提现退票 与注销提现(22)配对核销 同一笔注销操作下，退票金额与注销提现金额一致
    25 平台赔付 订单流水交叉验证 订单流水平台赔付相关字段求和 = 资金流水金额

    支出类（flow_type=2，钱出去了——验证"应该扣的是否扣对了"）

    funds_type 描述 校验方式 校验动作
    3 订单退款 订单流水交叉验证 订单流水退款相关字段求和 = 资金流水金额
    4 提现 与退票(5)配对核销 同一 withdraw_id 下，funds_type=4 的支出 + funds_type=5 的收入应能配对；未退票的检查状态是否 SUCCESS
    10 达人佣金 订单流水交叉验证 订单流水达人佣金相关字段求和 = 资金流水金额
    11 技术服务费 订单流水交叉验证 订单流水 platform_commission_amount 求和 = 资金流水金额
    12 带货机构服务费 订单流水交叉验证 订单流水带货机构服务费相关字段求和 = 资金流水金额
    14 极速退款垫资 与回补(15)配对核销 标记为垫资金额，等待 funds_type=15 回补时核销
    16 运费险 订单流水交叉验证 订单流水运费险相关字段求和 = 资金流水金额
    20 补交运费 订单流水交叉验证 订单流水运费相关字段求和 = 资金流水金额
    22 注销提现 与退票(23)配对核销 与商家注销流程的状态联动，确认金额一致性

    配对核销类（4↔5、14↔15、22↔23）同一业务产生一收一支两条流水，按关联字段配对验证收支一致即可。

    注意：平台正在将资金流水逐步迁移至新版本。迁移期间，funds_type=3（订单退款）、funds_type=10（达人佣金）、funds_type=12（带货机构服务费）这 3 种类型可能同时出现 flow_type=1（收入）和 flow_type=2（支出）两条方向相反的流水，属于正常现象，对账时需将两个方向分别处理。

    # 策略一：日常批量对账

    适合每日定时任务，快速判断订单类资金是否平衡。覆盖所有"订单流水交叉验证"类 funds_type：

    1. 调 [API] 获取资金流水列表 / getfundsflowlist 拉取 T 日全量流水，循环调 [API] 获取资金流水详情 / getfundsflowdetail 获取明细。
    2. 按 funds_type + flow_type 分组汇总 amount（flow_type=1 为收入，flow_type=2 为支出）。
    3. 调 [API] 查询订单流水列表 / listorderflow，过滤 order_settle_state=60（结算完成）的订单，按费用字段分组汇总。资金流水反映实际入账/出账，必须与已结算订单对齐，未结算订单可能仍有退款/售后变动。
    4. 执行校验：
      • 订单收入：订单流水 sum(mch_received_amount) = 资金流水 sum(amount where funds_type=1 and flow_type=1)
      • 退款：订单流水 sum(refund_amount) = 资金流水 sum(amount where funds_type=3 and flow_type=2)
      • 技术服务费：订单流水 sum(platform_commission_amount) = 资金流水 sum(amount where funds_type=11 and flow_type=2)

    各项总和一致则对账通过；不一致则标记为异常，进入策略二逐单排查。配对核销类（4↔5、14↔15、22↔23）同一业务产生一收一支两条流水，按 withdraw_id / order_id 等关联字段配对验证收支一致即可。

    # 策略二：异常逐单排查

    当策略一发现差异时，定位到具体订单：

    1. 从异常的 [API] 获取资金流水详情 / getfundsflowdetail 结果中，取 related_info_list 中 related_type=1 的 order_id。
    2. 用该 order_id 调用 [API] 获取订单详情 / getorder，获取订单精确金额。
    3. 将订单侧的支付金额/退款金额/各项扣费，与对应资金流水的 amount 逐项比对。

    # 订单流水枚举

    以下枚举用于 [API] 查询订单流水列表 / listorderflow 接口的查询参数过滤，其中 order_settle_state 是对账的关键过滤条件：

    枚举 字段 枚举值 描述
    订单结算状态 order_settle_state 0 无，查询全部
    1 待结算
    2 无需结算
    60 结算完成 ← 对账时使用此值
    100 部分结算
    订单状态 order_state 0 全部
    20 待发货
    30 待收货
    100 订单完成
    订单支付方式 order_pay_method 0 全部
    1 普通支付
    2 先用后付

    # 商户提现

    查询可提现余额后，通过提现接口发起提现，管理员扫码确认后资金到账。

    %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%% flowchart LR A["[API] 获取账户余额<br/>getbalance"] --> B{有可提现余额?} B -->|是| C["[API] 商户提现<br/>submitwithdraw"] C --> D["[API] 获取二维码<br/>ecgetqrcode"] D --> E[管理员扫码确认] E --> F["[事件] 提现二维码回调<br/>qrcode_status"] F --> G["[事件] 提现回调<br/>channels_ec_withdraw_notify"] G --> H{提现结果} H -->|成功| I[资金到账] H -->|失败| J[查看失败原因] style B fill:#ffffff,stroke:#0ab8a6,color:#666666 style E fill:#ffffff,stroke:#0ab8a6,color:#666666 style H fill:#ffffff,stroke:#0ab8a6,color:#666666 style I fill:#ffffff,stroke:#0ab8a6,color:#666666 style J fill:#ffffff,stroke:#0ab8a6,color:#666666

    # 结算账户管理（按需）

    需要修改结算账户时，调用银行卡辅助接口获取银行信息后修改。有两条查询路径：通过卡号直查，或通过搜索银行+省份/城市/支行逐级定位。

    # 查询银行信息

    %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%% flowchart LR A{查询方式} -->|已知卡号| B["[API] 根据卡号查银行信息<br/>ecgetbankbynum"] A -->|搜索银行| C["[API] 搜索银行列表<br/>ecgetbanklist"] C --> D["[API] 查询大陆银行省份列表<br/>ecgetprovince"] D --> E["[API] 查询城市列表<br/>ecgetcity"] E --> F["[API] 查询支行列表<br/>ecgetsubbranch"] B --> G[获得银行信息] F --> G style A fill:#ffffff,stroke:#0ab8a6,color:#666666 style G fill:#ffffff,stroke:#0ab8a6,color:#666666

    # 修改结算账户

    %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%% flowchart LR A["[API] 获取结算账户<br/>getbankacct"] --> B{需要修改?} B -->|是| C["[API] 修改结算账户<br/>setbankacct"] C --> D["[事件] 结算账户变更回调<br/>channels_ec_acct_notify"] style B fill:#ffffff,stroke:#0ab8a6,color:#666666

    # 状态流转

    # 提现状态枚举

    状态值 描述
    INIT 业务单已创建
    CREATE_SUCCESS 受理成功
    SUCCESS 提现成功
    FAIL 提现失败
    REFUND 提现退票
    CLOSE 关单

    # 前端对接说明

    资金结算模块为纯服务端接口，无前端组件对接需求。提现流程中的二维码展示需商家自行在管理后台实现。

    # 接口全览

    # 资金账户 API 接口

    中文名 / 英文名 请求方式 功能说明
    获取账户余额 / getbalance POST /channels/ec/funds/getbalance 查询可提现余额和待结算余额
    获取结算账户 / getbankacct POST /channels/ec/funds/getbankacct 查询当前结算银行账户信息
    获取资金流水详情 / getfundsflowdetail POST /channels/ec/funds/getfundsflowdetail 根据流水 ID 查询流水详细信息
    获取资金流水列表 / getfundsflowlist POST /channels/ec/funds/getfundsflowlist 按时间范围分页查询流水 ID 列表
    获取提现记录 / getwithdrawdetail POST /channels/ec/funds/getwithdrawdetail 查询单笔提现的详细信息和状态
    获取提现记录列表 / getwithdrawlist POST /channels/ec/funds/getwithdrawlist 按时间范围分页查询提现单号列表
    修改结算账户 / setbankacct POST /channels/ec/funds/setbankacct 修改结算银行账户信息
    商户提现 / submitwithdraw POST /channels/ec/funds/submitwithdraw 发起商户提现申请
    查询订单流水列表 / listorderflow POST /channels/ec/funds/listorderflow 按订单维度查询结算信息列表

    # 银行卡 API 接口

    中文名 / 英文名 请求方式 功能说明
    根据卡号查银行信息 / ecgetbankbynum POST /shop/funds/getbankbynum 根据银行卡号查询开户银行信息
    搜索银行列表 / ecgetbanklist POST /shop/funds/getbanklist 按关键字搜索支持的银行列表
    查询城市列表 / ecgetcity POST /shop/funds/getcity 查询指定省份下的所有城市
    查询大陆银行省份列表 / ecgetprovince POST /shop/funds/getprovince 查询大陆银行省份列表
    查询支行列表 / ecgetsubbranch POST /shop/funds/getsubbranch 查询指定银行在指定城市的支行

    # 资金二维码 API 接口

    中文名 / 英文名 请求方式 功能说明
    获取二维码 / ecgetqrcode POST /shop/funds/qrcode/get 获取提现确认二维码图片
    查询扫码状态 / eccheckqrcode POST /shop/funds/qrcode/check 查询提现二维码的扫码状态

    # 事件通知

    中文名 / 英文名 事件标识 功能说明
    结算账户变更回调 / channels_ec_acct_notify Event: channels_ec_acct_notify 结算账户修改后通知
    提现回调 / channels_ec_withdraw_notify Event: channels_ec_withdraw_notify 提现流程各阶段结果通知
    提现二维码回调 / qrcode_status Event: qrcode_status 提现二维码扫码状态变更通知

    # 常见问题 FAQ

    Q：提现有频率限制吗？ A：每天最多允许提现一次。提现需要管理员扫码确认，扫码确认后通过 [事件] 提现回调 / channels_ec_withdraw_notify 接收提现结果。

    Q：资金账户和银行卡接口的路径前缀为什么不同？ A：资金账户类接口路径前缀为 /channels/ec/funds/，银行卡辅助接口和资金二维码接口路径前缀为 /shop/funds/，这是历史原因导致的差异，两类接口均正常可用。

    文档变更日志（1条）
    2026 年 04 月 23 日
    新增 资金结算 开发指南