查询代付列表

契约 v1.0.0

本页目录

listDisbursements

GET/v1/disbursements

所需权限disbursements:read

disbursements:read 默认不在开发者可授予范围内，需要所有者或管理员创建的 Key。

说明

代付接口需要平台为当前环境开通代付能力，没开通返回 403 capability_disabled。资金规则、收款信息规则与结果处理见代付接入。

按状态、币种、商户代付单号和批次查询当前商户、当前环境的代付。按创建时间倒序、同一时间再按 id 倒序稳定排序，使用游标分页； created_gte 含、created_lt 不含。受理时被拒的请求没有代付记录。

请求头

请求头	必填	格式	说明
Authorization	是	Bearer <API_KEY>	服务端密钥，只能在商户服务端使用；商户与环境由密钥推导。缺失、无效、撤销或过期返回 401。

查询参数

名称	类型	必填	说明
`status`	string	否	按代付状态过滤。 `processing`：已受理，金额加手续费已冻结；正在付款或结果尚未确认，不是失败 `succeeded`：代付成功；实付可能小于 amount，差额已退回可结算 `failed`：代付明确失败，金额和手续费已退回可结算；终态 `reversed`：成功后被收款方退回，收款人没有收到钱；本金和手续费已退回可结算；终态将来可能新增取值；不认识的状态不要当作成功。示例：`processing`
`currency`	string	否	按币种过滤。约束：`格式 ^[A-Z]{3}$` 示例：`PKR`
`merchant_disbursement_no`	string	否	按商户代付单号精确匹配，区分大小写；超时后用它确认这一单是否已受理。约束：`格式 ^[A-Za-z0-9._:-]{1,64}$` 示例：`DSB-DEMO-001`
`batch_id`	string	否	按批次号过滤，只有商户后台批量发起的代付才有批次号。约束：`长度 1–64` 示例：`dsbb_demo_001`
`limit`	integer	否	每页条数，默认 20，最大 100。约束：`1–100默认 20`
`cursor`	string	否	上一页响应中的 next_cursor。不透明字符串，客户端不得解析或拼接；须与首页使用相同的过滤条件。约束：`长度 1–512`
`created_gte`	string(date-time)	否	创建时间下界（含），带时区的 ISO 8601。示例：`2026-09-23T00:00:00Z`
`created_lt`	string(date-time)	否	创建时间上界（不含），带时区的 ISO 8601。示例：`2026-09-24T00:00:00Z`

请求示例

curl

curl -X GET 'https://api.fluxan.co/v1/disbursements?limit=20' \
  -H 'Authorization: Bearer <TEST_SERVER_API_KEY>'

需要替换的占位符

<TEST_SERVER_API_KEY>：测试环境服务端 API Key：在商户后台「API Key」页面创建

说明

服务端 API Key 只能在你的服务端使用，文档站不提供在线调试。获取测试 Key：商户后台 API Key（在新标签页打开商户后台）（测试环境；需要所有者、管理员或开发者）

响应

代付列表。

代付列表

{
  "data": [
    {
      "id": "dsb_demo_002",
      "version": 2,
      "merchant_disbursement_no": "DSB-DEMO-002",
      "environment": "test",
      "amount": 60000,
      "currency": "PKR",
      "fee": 800,
      "method": "jazzcash",
      "payee": {
        "account_last4": "7654",
        "name": "Test Payee",
        "bank_code": null,
        "bank_name": null,
        "utr": null
      },
      "customer_ip": null,
      "status": "failed",
      "resolution_status": "known",
      "failure": {
        "code": "upstream_rejected",
        "message": "代付通道拒绝了这笔代付。"
      },
      "paid_amount": null,
      "succeeded_at": null,
      "failed_at": "2026-10-29T09:00:05Z",
      "reversed_at": null,
      "description": null,
      "metadata": {},
      "source": "portal",
      "batch_id": null,
      "created_at": "2026-10-29T09:00:00Z",
      "updated_at": "2026-10-29T09:00:05Z"
    },
    {
      "id": "dsb_demo_001",
      "version": 2,
      "merchant_disbursement_no": "DSB-DEMO-001",
      "environment": "test",
      "amount": 30000,
      "currency": "PKR",
      "fee": 600,
      "method": "easypaisa",
      "payee": {
        "account_last4": "4567",
        "name": "Test Payee",
        "bank_code": null,
        "bank_name": null,
        "utr": "UTR-DEMO-001"
      },
      "customer_ip": "203.0.113.10",
      "status": "succeeded",
      "resolution_status": "known",
      "failure": null,
      "paid_amount": 30000,
      "succeeded_at": "2026-10-29T08:01:04Z",
      "failed_at": null,
      "reversed_at": null,
      "description": "示例代付",
      "metadata": {
        "customer_ref": "CUSTOMER-DEMO-001"
      },
      "source": "api",
      "batch_id": null,
      "created_at": "2026-10-29T08:00:00Z",
      "updated_at": "2026-10-29T08:01:04Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "request_id": "req_demo_105"
}

响应字段

分页列表：data 为对象数组，has_more 为 true 时用 next_cursor 继续翻页。字段说明见对象小节。

名称	类型	必填	说明
`data`	array<Disbursement>	必填
`id`	string	必填	代付号（dsb_）。示例：`dsb_demo_001`
`version`	integer(int64)	必填	对象版本，每次有效变更递增；处理事件时比较它，不要按状态名排序。约束：`≥ 1` 示例：`1`
`merchant_disbursement_no`	string	必填	商户代付单号，同一商户同一环境内唯一，区分大小写；商户后台发起时没填的，等于代付号。示例：`DSB-DEMO-001`
`environment`	string	必填	环境：test 为测试，live 为生产。测试与生产对象相互隔离。 `test` `live` 将来可能新增取值；不认识的状态不要当作成功。示例：`test`
`amount`	integer(int64)	必填	代付金额，最小货币单位。约束：`≥ 1` 示例：`30000`
`currency`	string	必填	大写三字母币种代码。约束：`格式 ^[A-Z]{3}$` 示例：`PKR`
`fee`	integer(int64)	必填	代付手续费，最小货币单位；受理时按当时的费率版本计算并冻结，之后调整费率不影响这笔。约束：`≥ 0` 示例：`600`
`method`	string	必填	收款方式。 easypaisa：EasyPaisa 钱包 jazzcash：JazzCash 钱包 bank：银行账户 `easypaisa`：EasyPaisa 钱包 `jazzcash`：JazzCash 钱包 `bank`：银行账户将来可能新增取值；不认识的状态不要当作成功。示例：`easypaisa`
`payee`	DisbursementPayee	必填	收款人。完整收款账号只在创建请求里出现，响应、事件、商户后台和导出都只返回后 4 位。
`customer_ip`	string可为空	必填	收款人在你的系统里提交付款申请时的 IP；商户后台发起的代付为 null。示例：`203.0.113.10`
`status`	string	必填	代付状态。客户端不得把未知状态当作成功，按"未完成"处理并查询。 processing：已受理，金额加手续费已冻结；正在付款或结果尚未确认，不是失败 succeeded：代付成功；实付可能小于 amount，差额已退回可结算 failed：代付明确失败，金额和手续费已退回可结算；终态 reversed：成功后被收款方退回，收款人没有收到钱；本金和手续费已退回可结算；终态 `processing`：已受理，金额加手续费已冻结；正在付款或结果尚未确认，不是失败 `succeeded`：代付成功；实付可能小于 amount，差额已退回可结算 `failed`：代付明确失败，金额和手续费已退回可结算；终态 `reversed`：成功后被收款方退回，收款人没有收到钱；本金和手续费已退回可结算；终态将来可能新增取值；不认识的状态不要当作成功。示例：`processing`
`resolution_status`	string	必填	结果确认程度。 known：结果已确认 needs_query：结果未知，平台正在用原标识向上游查证 manual_review：超过自动查询窗口，转人工跟进；不会自动判失败 `known`：结果已确认 `needs_query`：结果未知，平台正在用原标识向上游查证 `manual_review`：超过自动查询窗口，转人工跟进；不会自动判失败将来可能新增取值；不认识的状态不要当作成功。示例：`known`
`failure`	DisbursementFailure可为空	必填	status 为 failed 时的原因，否则为 null。
`paid_amount`	integer(int64)可为空	必填	实付金额，成功后才有；可能小于 amount，差额已退回可结算；冲正后保留。约束：`≥ 0` 示例：`null`
`succeeded_at`	string(date-time)可为空	必填	成功时间；冲正后保留。示例：`null`
`failed_at`	string(date-time)可为空	必填	失败时间。示例：`null`
`reversed_at`	string(date-time)可为空	必填	冲正时间。示例：`null`
`description`	string可为空	必填	代付说明，供你自己对账。约束：`最长 256` 示例：`示例代付`
`metadata`	object	否	商户自定义键值，最多 20 个键；键最长 40 字符，值为最长 200 字符的字符串。禁止放入卡号等敏感数据，平台会做检查并拒绝。约束：`最多 20 个键值最长 200` 示例：`{"business_order_type":"one_time_purchase"}`
`source`	string	必填	代付来源。 api：开放 API portal：商户后台单笔 batch：商户后台批量 `api`：开放 API `portal`：商户后台单笔 `batch`：商户后台批量将来可能新增取值；不认识的状态不要当作成功。示例：`api`
`batch_id`	string可为空	必填	批次号（dsbb_），只有商户后台批量发起的才有。示例：`null`
`created_at`	string(date-time)	必填	受理时间。示例：`2026-10-29T08:00:00Z`
`updated_at`	string(date-time)	必填	最近一次变更时间。示例：`2026-10-29T08:00:00Z`
`has_more`	boolean	必填	是否还有下一页。示例：`false`
`next_cursor`	string可为空	必填	下一页游标；没有下一页时为 null。示例：`null`
`request_id`	string	必填	本次请求的唯一标识。示例：`req_demo_105`

可能的错误码

HTTP	错误码	何时出现	如何处理
400	invalid_request	缺 `Idempotency-Key`；订单号含非法字符；`payment_method_data` 与 `payment_method_id` 同时提交；`confirm=false` 携带卡信息；`confirm=true` 缺 `return_url`；收银会话两组身份参数同时提交或都缺；缺少上游要求的 `browser_info` / `billing_details` 字段；币种的上游只收整数金额（如 PKR）而 `amount` 带小数；代付的收款信息（`payee.account`、`payee.name`、`payee.bank_code`）或 `customer_ip` 不合规；游标、时间格式、`limit` 不合法	按 `error.field` 修正后重新提交，不要自动重扣
401	unauthenticated通用	未带 `Authorization`；Key 复制不完整；轮换后旧 Key 已过期；Key 被撤销	检查凭据，在商户后台 API Key 页面核对 Key 状态与环境
403	forbidden通用	只读 Key 创建退款；Key 缺少代付范围时创建或查询代付；`getEvent` 缺少事件所属业务的读权限；请求来源 IP 不在 Key 的白名单时返回更具体的 `ip_not_allowed`	使用具备所需 scope 的 Key；不要绕过限制
429	rate_limited通用	商户、Key 维度的频率限制；换 Key 不能绕过商户总限额；代付创建按商户单独计算	等待 `Retry-After` 秒后用原幂等键重试
500	internal_error通用	—	用原幂等键重试或按商户订单号 / 退款号 / 代付单号查询；不能换键重扣
502 / 503	upstream_unavailable通用	上游或平台依赖故障，平台无法确认本次请求是否已生效；与代付失败码 `upstream_unavailable` 同名不同义	同上

注意事项

按 merchant_disbursement_no（精确匹配、区分大小写）、status、currency、batch_id、created_gte（含）/ created_lt（不含）过滤；按 created_at 倒序，同一时刻按 id 倒序。
包括商户后台单笔与批量发起的代付（看 source）；收款账号只返回后 4 位。
processing 且 resolution_status 为 needs_query 或 manual_review 表示结果未知，不是失败，不要另建。
只读取平台当前状态，查得再勤也不会更早得到结果；查询频率见代付接入：状态与结果。

这页有帮助吗？