创建代付

契约 v1.0.0

本页目录

createDisbursement

POST/v1/disbursements

所需权限disbursements:write需要幂等键

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

说明

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

按你的指令从该币种的可结算余额付款给第三方收款人。商户与环境只由 API Key 决定，手续费由平台计算，请求里没有商户号、手续费或通道字段。需要当前环境已开通代付能力；merchant_disbursement_no 在商户、环境内唯一，必须带幂等键。受理时在同一原子操作中冻结金额加手续费，可结算不够返回 422 insufficient_balance，不建单。按请求格式、幂等、商户状态与能力、币种与通道、整数金额与收款信息、单号唯一、手续费、限额、平台暂停、风控名单、可结算余额的顺序检查，前一项不通过就返回，除 201 外都不建单、不冻结资金。 201 与 200 只代表受理（status=processing），钱是否付出看 status 或经验签的 disbursement.* 事件。超时或 5xx 时只能用原幂等键重试或按单号查询，绝不换单号或换键重发：付出的钱不能撤回。没有取消接口。

请求头

请求头	必填	格式	说明
Authorization	是	Bearer <API_KEY>	服务端密钥，只能在商户服务端使用；商户与环境由密钥推导。缺失、无效、撤销或过期返回 401。
Content-Type	是	application/json	请求体为 UTF-8 编码的 JSON。
Idempotency-Key	是	1–255 个可见 ASCII 字符	幂等键，1–255 个可见 ASCII 字符。作用域为商户、环境、方法与路径：同键且安全业务参数一致时复用原业务对象，参数冲突返回 409 idempotency_conflict。一次提交使用一个键，网络重试沿用原键；换卡等新的提交使用新键。同键并发时只有一个请求取得执行权，其余请求等待其事务提交后返回同一对象（200）；等待超时返回 409 operation_in_progress（retryable=true），稍后用原键重试。被 400、401、403、422 拒绝的请求不占用幂等键，修正后用新键提交。

请求体

JSON 对象 CreateDisbursementRequest

名称	类型	必填	说明
`merchant_disbursement_no`	string	必填	商户代付单号，1-64 个字母、数字、点、下划线、冒号或横线；同一商户同一环境内唯一，区分大小写。发起前生成并保存，超时后用它查询。约束：`格式 ^[A-Za-z0-9._:-]{1,64}$` 示例：`DSB-DEMO-001`
`amount`	integer(int64)	必填	代付金额，最小货币单位。代付通道只收整数金额的币种必须是整数个货币单位：PKR 的 30000可以，30050 不行。约束：`≥ 1` 示例：`30000`
`currency`	string	必填	大写三字母币种代码；首期只有 PKR。约束：`格式 ^[A-Z]{3}$` 示例：`PKR`
`method`	string	必填	收款方式。 easypaisa：EasyPaisa 钱包 jazzcash：JazzCash 钱包 bank：银行账户 `easypaisa`：EasyPaisa 钱包 `jazzcash`：JazzCash 钱包 `bank`：银行账户将来可能新增取值；不认识的状态不要当作成功。示例：`easypaisa`
`payee`	CreateDisbursementPayee	必填	收款人。完整收款账号只在创建请求里出现，之后的响应、事件、商户后台和导出都只返回后 4 位；你的日志、错误上报、工单里也不要记录完整账号。代付付出后不能撤回：账号写错而户名恰好对上时，钱会进入那个账户。
`account`	string	必填	收款账号，不合规时返回 400 invalid_request（field 为 payee.account）。 easypaisa、jazzcash：03 开头的 11 位数字；平台不做任何规整，去掉空格、横线或把 +92 改成 0 由你的系统完成 bank：去掉空格、转大写后为 9–24 位字母和数字；以 PK 开头的按 IBAN 校验（24 位，mod 97 校验位正确）平台不对收款账号做卡号（Luhn）检查；格式正确但账号不存在的，受理后失败。约束：`长度 1–64` 示例：`03001234567`
`name`	string	必填	收款人户名，必须与账户真实户名一致：不一致时受理成功、之后代付失败（payee_account_invalid）。不能含卡号样式的数字（400 sensitive_data_rejected）。约束：`长度 2–64` 示例：`Test Payee`
`bank_code`	string	否	收款银行代码，method 为 bank 时必填，其他收款方式不能传。 HBL：Habib Bank Limited UBL：United Bank Limited MCB：MCB Bank Limited MCB_ARIF_HABIB：MCB Arif Habib NBP：National Bank of Pakistan ALFALAH：Bank Alfalah Limited ALLIED：Allied Bank Limited ASKARI：Askari Bank Limited FAYSAL：Faysal Bank Limited MEEZAN：Meezan Bank AL_HABIB：Bank Al Habib Limited HABIB_METRO：Habib Metropolitan Bank BANK_ISLAMI：Bank Islami Pakistan Limited DUBAI_ISLAMIC：Dubai Islamic Bank Pakistan PUNJAB_BANK：The Bank of Punjab SINDH_BANK：Sindh Bank Limited SONERI：Soneri Bank Limited SUMMIT：Summit Bank Limited SILK：Silk Bank Limited SAMBA：Samba Bank Limited JS：JS Bank Limited NIB：NIB Bank Limited APNA：Apna Microfinance Bank CITI：Citi Bank NA NRSP：NRSP Microfinance Bank CDNS：Central Directorate of National Savings `HBL`：Habib Bank Limited `UBL`：United Bank Limited `MCB`：MCB Bank Limited `MCB_ARIF_HABIB`：MCB Arif Habib `NBP`：National Bank of Pakistan `ALFALAH`：Bank Alfalah Limited `ALLIED`：Allied Bank Limited `ASKARI`：Askari Bank Limited `FAYSAL`：Faysal Bank Limited `MEEZAN`：Meezan Bank `AL_HABIB`：Bank Al Habib Limited `HABIB_METRO`：Habib Metropolitan Bank `BANK_ISLAMI`：Bank Islami Pakistan Limited `DUBAI_ISLAMIC`：Dubai Islamic Bank Pakistan `PUNJAB_BANK`：The Bank of Punjab `SINDH_BANK`：Sindh Bank Limited `SONERI`：Soneri Bank Limited `SUMMIT`：Summit Bank Limited `SILK`：Silk Bank Limited `SAMBA`：Samba Bank Limited `JS`：JS Bank Limited `NIB`：NIB Bank Limited `APNA`：Apna Microfinance Bank `CITI`：Citi Bank NA `NRSP`：NRSP Microfinance Bank `CDNS`：Central Directorate of National Savings 将来可能新增取值；不认识的状态不要当作成功。示例：`MEEZAN`
`customer_ip`	string	否	收款人（你的用户）在你的系统里提交这笔付款申请时的 IP，IPv4 或 IPv6；按受信代理链解析，不要填你服务器的 IP。用于风控检查，可不传。约束：`长度 1–45` 示例：`203.0.113.10`
`description`	string	否	代付说明，供你自己对账；不能含卡号样式的数字。约束：`最长 256` 示例：`示例代付`
`metadata`	object	否	商户自定义键值，最多 20 个键；键最长 40 字符，值为最长 200 字符的字符串。禁止放入卡号等敏感数据，平台会做检查并拒绝。约束：`最多 20 个键值最长 200` 示例：`{"business_order_type":"one_time_purchase"}`

请求示例

钱包代付：PKR 金额必须是 100 的倍数

curl

curl -X POST 'https://api.fluxan.co/v1/disbursements' \
  -H 'Authorization: Bearer <TEST_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <UNIQUE_OPERATION_KEY>' \
  -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"
  }
}'

需要替换的占位符

<TEST_SERVER_API_KEY>：测试环境服务端 API Key：在商户后台「API Key」页面创建
<UNIQUE_OPERATION_KEY>：你为这次提交生成的幂等键（如 UUID），网络重试沿用同一个

银行账户代付：method=bank 时必须带 bank_code

curl

curl -X POST 'https://api.fluxan.co/v1/disbursements' \
  -H 'Authorization: Bearer <TEST_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <UNIQUE_OPERATION_KEY>' \
  -d '{
  "merchant_disbursement_no": "DSB-DEMO-002",
  "amount": 30000,
  "currency": "PKR",
  "method": "bank",
  "payee": {
    "account": "012345678901",
    "name": "Test Payee",
    "bank_code": "MEEZAN"
  }
}'

需要替换的占位符

<TEST_SERVER_API_KEY>：测试环境服务端 API Key：在商户后台「API Key」页面创建
<UNIQUE_OPERATION_KEY>：你为这次提交生成的幂等键（如 UUID），网络重试沿用同一个

说明

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

响应

同键幂等复用，返回原代付的最新状态。

同键重放：返回原代付的最新状态，不会再付一次

{
  "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_103"
}

响应字段

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

名称	类型	必填	说明
`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	错误码	何时出现	如何处理
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` 修正后重新提交，不要自动重扣
400	sensitive_data_rejected	`description`、`metadata` 中出现卡号样式的数字等；代付的 `payee.name` 同样检查	删除敏感内容后重新提交；检查你的系统为何把卡数据写进这些字段
403	capability_disabled	未开通直接传卡；支付或退款申请能力被关闭；该币种未开放；当前环境没开通代付能力	改用托管收银台或联系平台运营
403	merchant_not_active	商户被暂停或关闭；已受理业务的回调、查询、通知不受影响	联系平台运营
409	idempotency_conflict	复用了键但金额、币种、订单号等不同；代付同键但任一请求字段（含收款信息）不同	属于集成缺陷：检查幂等键生成逻辑；不要改参数后重放原键；新操作使用新键。代付的冲突带 `related_resource_id`，指向这个键已受理的代付：先查询它，不要再付一笔
409	operation_in_progress	并发发送了同键请求	稍后用同一个键重试，或查询 `related_resource_id`；不要换键
422	currency_not_supported	商户配置与上游能力的交集不含该币种；代付：商户没开通该币种、该币种没有可用的代付通道、没配代付限额或代付费率	改用已启用币种或联系平台运营
409	disbursement_no_conflict	换幂等键重复提交同一商户代付单号	查询 `related_resource_id` 指向的代付；这个单号已经付过或正在付，不要换单号重发
422	fee_exceeds_amount	金额过小，按费率计算的手续费超过金额；代付金额不大于按代付费率计算的手续费	提高金额或联系平台调整配置
422	amount_out_of_range	低于最低 / 高于最高单笔金额，或超过日累计限额；代付超过单笔下限、单笔上限、日累计金额或日笔数；错误中不回传具体阈值	调整金额或联系平台
503	temporarily_unavailable	平台暂停了该通道的新交易，或暂停了代付；响应不说明内部原因	稍后用原幂等键重试；本次没有产生 Payment 或扣款；持续出现时联系平台运营
422	risk_rejected	命中风险名单等基础规则，代付同样检查；不说明具体规则与阈值	不要尝试绕过；有疑问联系平台
422	insufficient_balance	该币种的可结算余额小于代付金额加代付手续费	`message` 与 `error.details`（`shortfall`、`currency`）给出差额；本次不建单、不冻结资金；等可结算足够后，用同一商户代付单号、新的幂等键重新提交；平台不会自动缩减金额
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` 同名不同义	同上

注意事项

需要平台为当前环境开通代付能力，否则返回 403 capability_disabled。代付是按你的指令把可结算余额付给第三方收款人，不是打款，也不是提现。
merchant_disbursement_no 在商户、环境内唯一；换幂等键重复提交同一单号返回 409 disbursement_no_conflict（related_resource_id 为已有代付号），不会建第二笔。
请求中没有商户号、手续费或通道字段：商户与环境由 API Key 决定，手续费由平台计算。PKR 金额必须是 100 的倍数。
受理时冻结金额加手续费；可结算不够返回 422 insufficient_balance（error.details 带 shortfall、currency），不建单。超出限额返回 422 amount_out_of_range，不回传阈值。
201 / 200 只代表受理（status=processing），钱是否付出看 status 或 disbursement.* 事件。没有取消接口。
受理顺序与收款信息规则见代付接入：错误码与限流、收款信息规则。

警告

超时或 5xx 后只能用原幂等键重试或按单号查询，绝不换单号或换键重发：付出的钱不能撤回。

这页有帮助吗？

创建代付

请求头

请求体

请求示例

响应

响应字段

可能的错误码

注意事项

相关