跳到正文
Fluxan开发者文档
English

查询代付

契约 v1.0.0

getDisbursement
GET/v1/disbursements/{disbursement_id}
所需权限disbursements:read

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

说明

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

查询单笔代付。processing 时不要当作失败，也不要另建；failed、reversed 是终态，金额和手续费已退回可结算。 冲正后 succeeded_at、paid_amount 与 payee.utr 保留。不属于当前商户、当前环境的代付号返回 404，不透露是否存在。

请求头

请求头必填格式说明
Authorization是Bearer <API_KEY>

服务端密钥，只能在商户服务端使用；商户与环境由密钥推导。缺失、无效、撤销或过期返回 401。

请求示例

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

需要替换的占位符

  • <DISBURSEMENT_ID>：按说明替换为你的实际值
  • <TEST_SERVER_API_KEY>：测试环境服务端 API Key：在商户后台「API Key」页面创建

说明

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

响应

代付详情。

JSON
{
  "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",
  "request_id": "req_demo_104"
}

响应字段

返回对象 字段说明见 对象小节。

名称类型必填说明
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 位。

account_last4
string必填

收款账号后 4 位。

示例：4567

name
string必填

收款人户名，与请求一致。

示例：Test Payee

bank_code
DisbursementBankCode可为空必填

银行代码；收款方式不是 bank 时为 null。

  • HBL
  • UBL
  • MCB
  • MCB_ARIF_HABIB
  • NBP
  • ALFALAH
  • ALLIED
  • ASKARI
  • FAYSAL
  • MEEZAN
  • AL_HABIB
  • HABIB_METRO
  • BANK_ISLAMI
  • DUBAI_ISLAMIC
  • PUNJAB_BANK
  • SINDH_BANK
  • SONERI
  • SUMMIT
  • SILK
  • SAMBA
  • JS
  • NIB
  • APNA
  • CITI
  • NRSP
  • CDNS
  • 将来可能新增取值；不认识的状态不要当作成功。
bank_name
string可为空必填

收款银行名称，由代付通道回传，可能为 null。

示例：null

utr
string可为空必填

收款方钱包或银行的流水号，成功后才有，收款人凭它向钱包或银行查账；冲正后保留。

示例：null

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。

code
string必填

失败原因码，取值见 x-failure-codes.disbursement；须容忍新增取值，不认识的按 upstream_failed 处理。

示例：payee_account_invalid

message
string必填

脱敏说明。

示例：收款账号无效或户名不符。

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

request_id
string必填

本次请求的唯一标识，用于排查与支持。

示例：req_demo_001

可能的错误码

HTTP错误码何时出现如何处理
404not_foundID 错误；用测试 Key 查询生产对象；查询平台异常退款（不通过开放 API 返回）核对 ID 与 Key 的环境；平台不会透露对象是否属于其他商户
401unauthenticated通用未带 Authorization；Key 复制不完整；轮换后旧 Key 已过期；Key 被撤销检查凭据，在 商户后台 API Key 页面 核对 Key 状态与环境
403forbidden通用只读 Key 创建退款；Key 缺少代付范围时创建或查询代付；getEvent 缺少事件所属业务的读权限；请求来源 IP 不在 Key 的白名单时返回更具体的 ip_not_allowed使用具备所需 scope 的 Key；不要绕过限制
429rate_limited通用商户、Key 维度的频率限制；换 Key 不能绕过商户总限额；代付创建按商户单独计算等待 Retry-After 秒后用原幂等键重试
500internal_error通用—用原幂等键重试或按商户订单号 / 退款号 / 代付单号查询；不能换键重扣
502 / 503upstream_unavailable通用上游或平台依赖故障，平台无法确认本次请求是否已生效；与代付失败码 upstream_unavailable 同名不同义同上

注意事项

  • 收款账号只返回后 4 位（payee.account_last4），完整账号不出现在任何响应和事件里。
  • processing 且 resolution_status 为 needs_query 或 manual_review 表示结果未知，不是失败，不要另建。
  • reversed 表示成功后被收款方退回，收款人没有收到钱；succeeded_at、paid_amount、payee.utr 保留。
  • 只读取平台当前状态；不属于当前商户或环境的代付返回 404，不透露是否存在。
  • failure.code 的取值与处理见代付失败码。
这页有帮助吗？