代付接入

代付是什么

代付是按你的指令，把某币种的可结算余额付给你指定的第三方收款人。它和打款是两回事：

代付不经人工审核，通过受理检查就提交。代付也不是提现：平台不提供把任意金额转到你自己账户的自助提现，你自己的资金只能经结算和打款到账。首期只支持 PKR；不支持跨币种代付；平台不保存收款人，每笔都提交完整收款信息；代付没有撤销。

开通与准备

• 管理 API Key：商户后台 API Key（在新标签页打开商户后台）（测试环境；需要所有者、管理员或开发者）（开发者需已被授予代付范围）。
• 订阅代付事件：配置 Webhook（在新标签页打开商户后台）（测试环境；需要所有者、管理员或开发者）。

资金规则

• 算例：可结算 PKR 1,000.00，发起金额 300.00、手续费 6.00 的代付。受理后可结算 694.00、代付占用 306.00；成功后代付占用归零；如果失败，可结算回到 1,000.00。
• 退回可结算的钱（失败、冲正、少付差额）立即可用，不再等锁定周期。
• 查询：GET /v1/balances 的 available 与 disbursement_pending；GET /v1/balance-transactions 中代付流水的 source_type 为 disbursement，记账类型有 disbursement_reserved（冻结）、disbursement_succeeded（成功扣减，含少付差额退回）、reservation_released（失败退回）、disbursement_reversed（冲正退回）。两个接口都需要 finance:read。

创建代付

POST/v1/disbursements，必须带 Idempotency-Key，scope disbursements:write。请求里没有商户号、手续费或通道字段：商户与环境只由 API Key 决定，手续费由平台计算。

完整字段与约束见 API 参考：创建代付。占位符 <TEST_SERVER_API_KEY> 换成带 disbursements:write 的测试 Key；示例里的手续费只作演示，以你的费率为准。

curl https://api.fluxan.example/v1/disbursements \
  -H "Authorization: Bearer <TEST_SERVER_API_KEY>" \
  -H "Idempotency-Key: disbursement.create:DSB-DEMO-001:1" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_disbursement_no": "DSB-DEMO-001",
    "amount": 30000,
    "currency": "PKR",
    "method": "easypaisa",
    "payee": { "account": "03001234567", "name": "Test Payee" },
    "customer_ip": "203.0.113.10",
    "description": "示例代付",
    "metadata": { "customer_ref": "CUSTOMER-DEMO-001" }
  }'

201 响应（同键重放返回 200 和同一代付的最新状态）：

{
  "id": "dsb_demo_001",
  "version": 1,
  "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": null
  },
  "customer_ip": "203.0.113.10",
  "status": "processing",
  "resolution_status": "known",
  "failure": null,
  "paid_amount": null,
  "succeeded_at": null,
  "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:00:00Z",
  "request_id": "req_demo_101"
}

银行账户代付的请求体差异："method": "bank"，"payee": { "account": "012345678901", "name": "Test Payee", "bank_code": "MEEZAN" }。

Disbursement 对象

逐字段的类型与可空性见 API 参考：Disbursement 对象。

查询代付

GET/v1/disbursements/{disbursement_id} 按代付号查询，GET/v1/disbursements 按条件列出，都需要 disbursements:read。

# 按代付号查询（scope disbursements:read）
curl https://api.fluxan.example/v1/disbursements/dsb_demo_001 \
  -H "Authorization: Bearer <TEST_SERVER_API_KEY>"

# 按商户代付单号查询：超时后确认这一单是否已受理
curl "https://api.fluxan.example/v1/disbursements?merchant_disbursement_no=DSB-DEMO-001" \
  -H "Authorization: Bearer <TEST_SERVER_API_KEY>"

# 对账：某天仍在处理中的代付
curl "https://api.fluxan.example/v1/disbursements?status=processing&currency=PKR&created_gte=2026-10-29T00:00:00Z&created_lt=2026-10-30T00:00:00Z&limit=100" \
  -H "Authorization: Bearer <TEST_SERVER_API_KEY>"

• 列表筛选：status、currency、created_gte（含）、created_lt（不含）、merchant_disbursement_no（精确匹配、区分大小写）、batch_id；limit 默认 20、最大 100；cursor 用上一页的 next_cursor；按创建时间倒序，同一时间按 id 倒序（同分页）。返回 data、has_more、next_cursor、request_id。
• 只返回当前商户、当前环境的代付；其他商户或其他环境的代付号返回 404，不透露是否存在。受理时被拒的请求没有代付记录，查不到。
• 商户后台单笔、批量发起的代付也能查到（看 source）：查看代付记录（在新标签页打开商户后台）（测试环境；需要所有者、管理员、财务或开发者）。

收款信息规则

• 不通过时返回 400 invalid_request，field 为 payee.account、payee.name 或 payee.bank_code。
• 钱包号由你的系统先规整再提交：去掉空格和横线；+92 或 92 开头加 10 位数字的，换成 0 加 10 位；10 位且以 3 开头的（表格软件吃掉了开头的 0），前面补 0。商户后台的表单与批量文件会自动规整，开放 API 不会。
• payee.name 不能含 13–19 位连续数字（卡号样式）。户名与账户真实户名不一致时，受理成功，之后代付失败（payee_account_invalid）。平台不对收款账号做卡号（Luhn）检查；格式正确但账号不存在的，同样受理后失败。
• 完整收款账号只在创建请求里出现，之后 API 响应、事件、商户后台和导出都只显示后 4 位；你的日志、错误上报、工单里也不要记录完整账号。

银行代码

method=bank 时 payee.bank_code 取下表的代码（取自契约，区分大小写）：

幂等与重试

• 幂等键由单号确定：disbursement.create:<单号>:<序号>，序号只在被 4xx 拒绝、修正后重新提交时加 1。用随机 UUID 时必须先写库再发送，重试时从库里读，不能重新生成。
• 参与比较的是全部请求字段；幂等记录保留 7 天，单号唯一一直有效。
• 重试封装沿用重试参考实现的 postWithRetry。

状态与结果

• 没有取消、撤回或重试接口；failed、reversed 是终态。只有代付通道明确失败、连续 30 分钟提交不出去、或平台人工核实后，才会变成 failed。
• 冲正可能在成功之后才出现：平台在成功后第 1 天、第 3 天各再核对一次，也随时处理冲正通知。
• 查询频率：以 Webhook 为主。受理 10 分钟后仍是 processing 且没收到事件时，在 30 分钟、2 小时、6 小时、24 小时各查一次，之后每天一次直到终态；同一代付两次查询间隔不少于 10 秒。查询只读平台当前状态，查得再勤也不会更早得到结果。
• 单笔查看与导出：代付记录（在新标签页打开商户后台）（需要所有者、管理员、财务或开发者）。

失败码

status=failed 时 failure.code 取下表的值（取自契约）：

• 每种失败都已把金额和手续费全额退回可结算。
• 客户端须容忍新增的失败码，不认识的按 upstream_failed 处理。

Webhook 事件

data.object 是事件发生时的 Disbursement 快照（字段同 Disbursement 对象）；用 GET/v1/events/{event_id} 补查代付事件需要 disbursements:read。订阅事件：配置 Webhook（在新标签页打开商户后台）（需要所有者、管理员或开发者）。

示例载荷（生产环境的冲正事件；测试环境无法触发冲正）：

{
  "id": "evt_demo_203",
  "type": "disbursement.reversed",
  "api_version": "v1",
  "created_at": "2026-10-30T02:10:00Z",
  "environment": "live",
  "merchant_id": "mer_demo_001",
  "data": {
    "object": {
      "id": "dsb_demo_009",
      "version": 3,
      "merchant_disbursement_no": "DSB-DEMO-009",
      "environment": "live",
      "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": "reversed",
      "resolution_status": "known",
      "failure": null,
      "paid_amount": 30000,
      "succeeded_at": "2026-10-29T08:01:04Z",
      "failed_at": null,
      "reversed_at": "2026-10-30T02:09:58Z",
      "description": "示例代付",
      "metadata": { "customer_ref": "CUSTOMER-DEMO-001" },
      "source": "api",
      "batch_id": null,
      "created_at": "2026-10-29T08:00:00Z",
      "updated_at": "2026-10-30T02:09:58Z"
    }
  }
}

处理代付事件（先按验签校验签名与环境、按事件 ID 去重并返回 2xx）：

// 先按 Webhook 文档验签、校验环境、按事件 ID 去重并返回 2xx，再异步调用本函数
export async function onDisbursementEvent(event) {
  const d = event.data.object;
  const local = await findDisbursement(d.id); // 你保存的代付快照；后台发起的代付（source 为 portal、batch）本地可能没有
  if (local && local.version >= d.version) return; // 旧版本事件：丢弃
  await saveDisbursementSnapshot(d);
  if (d.status === 'succeeded')
    return markPaid(d.merchant_disbursement_no, d.paid_amount, d.payee.utr); // 按实付记账
  if (d.status === 'failed') return markFailed(d.merchant_disbursement_no, d.failure.code); // 资金已退回可结算
  if (d.status === 'reversed') return markReversed(d.merchant_disbursement_no); // 已付改回未付、通知运营；不要自动重发
  // processing 或不认识的状态：继续等待，绝不当作成功
}

同一代付的事件可能乱序、重复到达：reversed（version 3）可能先于 succeeded（version 2）到达，按 version 处理后晚到的 succeeded 被丢弃，不会把已冲正的单改回已付（乱序与版本比较）。冲正后要再付，用新单号另建；后台发起的代付不填单号时，merchant_disbursement_no 等于代付号。

错误码与限流

创建代付按下表顺序检查，前一项不通过就返回，不再往下检查；除 201 外都不建单、不冻结资金。

{
  "error": {
    "code": "insufficient_balance",
    "message": "可结算余额不足以支付代付金额与手续费，差额 PKR 56.00",
    "field": null,
    "related_resource_id": null,
    "retryable": false,
    "details": { "shortfall": 5600, "currency": "PKR" }
  },
  "request_id": "req_demo_102"
}

通用错误：401 unauthenticated；403 forbidden（Key 缺少所需 scope）、ip_not_allowed；查询不存在或不属于当前商户、环境的代付 404 not_found；429 rate_limited；500 internal_error、502 / 503 upstream_unavailable（结果未知，按幂等与重试处理）。全部错误码见错误码字典。

限流

代付创建按商户单独计算频率限制，不占用支付、退款的额度，换 Key 不能绕过；超过时返回 429，本次未执行，等 Retry-After 秒后用原幂等键重试。一次要付很多笔时控制并发，或使用商户后台的批量代付。查询接口的限流同 API 参考的限流说明。

在测试环境验证

• 前提与生产相同（见开通与准备）：平台为测试环境开通代付能力并配好 PKR 通道与限额，你用带代付范围的测试 Key。测试环境不产生真实资金。
• 测试可结算同样来自 PKR 代收，过了测试环境的锁定周期才转入；需要尽快演练时，联系平台缩短测试环境的锁定周期。
• 金额小于 500.00 PKR（amount < 50000）的代付成功；500.00 PKR 及以上的失败，失败码以 failure.code 为准，不固定为某一个码。
• 银行账号长度不在 9–20 位之间的，受理后直接失败，所以 24 位的 IBAN 在测试环境总是失败，测试银行代付用 9–20 位的本地账号；生产环境没有这条限制。
• 冲正与结果未知（needs_query、manual_review）暂不支持模拟。自测方法：用单元测试把示例载荷交给事件处理函数，确认已付改回未付、不自动重发；把 processing + needs_query 的响应交给你的代码，确认不当作失败、不另建；在 Webhook 配置（在新标签页打开商户后台）（测试环境；需要所有者、管理员或开发者） 用“发送测试事件”发一条 disbursement.reversed，只核对接收与验签（测试事件不对应真实代付，不要据此改业务数据）。

通用的测试环境说明见测试指南。

上线检查

上线代付前逐项确认（勾选只保存在本机，可复制为 Markdown）；通用的上线检查见上线检查清单。

常见问题