能力概述

Paydify Payout 让商户把账户余额主动发给第三方收款人，资金可以发往：

• 链上钱包（稳定币付款，Crypto Withdraw）—— 如 P2P 平台用户提现、加密 KOL 打赏、跨境结算；
• 银行账户（法币付款，Fiat Withdraw）—— 如代发工资、跨境 B2B 结算、平台向供应商打款。

资金来源于您在 Paydify 平台的账户余额：先充值（Deposit）→ 再付款（Withdraw） 是基本节奏；如果您同时开通了 Payin 收单，收单成功的金额会自动结算进同一账户余额，可以直接用于付款，无需单独充值。

主要能力

• 钱包管理：查询入金地址、查询账户余额
• 稳定币付款：单笔 / 批量提交链上付款，按 txnId 跟踪状态
• 法币付款：先报价、再锁定、提交清算渠道，支持取消与详情查询
• Webhook 通知：实时推送付款终态，与 Payin 共用签名机制

接入步骤

[Deposit]      [Crypto Withdraw]        [Fiat Withdraw]           [Result]
  入金       →   链上付款           或    法币付款            →    Webhook + 主动查询

步骤 1：往 Paydify 账户充值（Deposit）

如果您只做 Payout、不开通 Payin，需要先从您自己的钱包向 Paydify 平台账户打入稳定币。

1.1 获取充值地址

每个（App + 链）下，Paydify 会给您一个固定的专属充值地址（KYC 通过后即生成，永久有效）。

• Portal 路径：「应用管理」，获取商户专属充值地址，按链切换查看；
• API 路径：POST /payout/v1/wallet/address，传 network（链 code，如 trx / eth / bnb）。

返回包含该链支持的币种列表与对应的链上充值地址，详见 查询钱包地址。

1.2 注册充值白名单（可选）

为了防止"来源不明的链上资金"被错误归集到您的账户余额，建议在 Portal 上提前登记可信的来源地址：

• 来源固定（公司财务钱包）：强烈建议开通，可挡住误转 / 钓鱼地址；
• 入金来源分散（大量 C 端用户充值）：白名单管理成本高，可不开通；
• 未开通白名单时，所有打到充值地址的入金都会被自动归集到账户余额。

1.3 链上发起转账

在您自己的钱包里向上一步获取的地址打款。到账时间取决于链：

链	通常到账时间
Kaia	1–2 分钟
TRON	1–3 分钟
BNB Chain / Solana / Base	1–5 分钟
Ethereum	3–10 分钟

Paydify 链上监听服务自动捕获到账事件并归集：

• 白名单匹配通过（IN）→ 自动入账，余额可用；
• 未通过 / 未配置白名单（OUT / NO_CONFIG）→ 资金先 FROZEN，由商户在 Portal 上人工"解除冻结入账"或"原路退回"。

1.4 查询充值记录

• Portal 路径：「交易查询 → 充值记录」，支持按链 / 状态 / 时间筛选；
• 充值订单状态机：INIT → FROZEN → UNFROZEN → DEPOSITED（成功）或 ... → REFUNDING → REFUNDED（原路退回）。

步骤 2：发起稳定币付款（Crypto Withdraw）

调用接口：POST /payout/v1/withdraw/apply，详见 发起提现。

核心规则：

• 幂等键：商户侧 mchWithdrawId 必传且需保证唯一；重复传相同值返回首次创建的结果；
• 余额校验：余额不足直接返回 INSUFFICIENT_BALANCE，不进入异步流程——余额不会扣减；
• Gas 费：链上 gas 默认由 Paydify 从 amount 中扣除（即商户填的是"用户应收"，Paydify 上链时按"应收 + gas"扣账户余额）；如希望"用户应收 = 上链金额"，请联系商务调整费用模式；
• 不可撤销：一旦链上广播，无法回滚——建议关键大额付款增加二次审批；
• 批量付款：批量代发场景可使用 批量提现，一次提交多笔；
• 查询单笔详情：按 mchWithdrawId 或 withdrawTxnId 调用 提现详情查询。

步骤 3：发起法币付款（Fiat Withdraw）

法币付款比稳定币多一步报价（quote），因为汇率随行就市，必须在用户确认前锁定。详见 法币提现。

阶段	接口	说明
预览报价	POST /payout/v1/fiat-withdraw/quote	提交"USDT → 法币"或反向折算，返回报价单（含汇率、手续费、有效期，默认 60 秒）
锁定报价 + 发起	POST /payout/v1/fiat-withdraw/apply	提交报价单 ID + 收款人信息（姓名 / 银行 / 账号 / 国家），Paydify 立即扣余额、提交清算渠道
取消	POST /payout/v1/fiat-withdraw/cancel	仅在 PENDING 状态可取消，资金回流余额
列表 / 详情	POST /payout/v1/fiat-withdraw/list / detail	按商户单号 / 状态 / 时间筛选

法币付款规则：

• 实际到账时间取决于收款银行清算窗口，通常 T+1 ～ T+5；
• 收款人信息错误（账号 / 姓名不符）会导致清算失败，资金原路回流余额并扣除 fail fee；
• 报价单过期需重新调用 quote 接口；
• 部分国家对单笔金额和收款人种类有合规限制，请提前与商务确认。

步骤 4：接收付款结果

Paydify 通过 Webhook 推送付款终态到您配置的 notificationUrl，签名机制与 Payin 一致，详见 回调通知。

state 取值：PENDING（已提交待上链）→ SUCCESS（链上 / 银行清算成功）/ FAILED（资金已回流余额，可查 errorMsg）。

双保险：

• Webhook 为主路径：状态变更主动推送，延迟最低；
• 主动查询为兜底：网络抖动 / 回调端临时不可用时，使用 提现详情查询 或 法币提现详情 补偿。

API 接口

接口	描述
POST /payout/v1/wallet/address	查询钱包入金地址
POST /payout/v1/wallet/balance	查询商户钱包余额
POST /payout/v1/withdraw/apply	单笔稳定币提现申请
POST /payout/v1/withdraw/detail	提现详情查询
POST /payout/v1/batch/apply	批量提现申请
POST /payout/v1/batch/query	批量提现查询
POST /payout/v1/fiat-withdraw/quote	法币提现报价
POST /payout/v1/fiat-withdraw/apply	法币提现申请
POST /payout/v1/fiat-withdraw/cancel	法币提现取消
POST /payout/v1/fiat-withdraw/list	法币提现列表
POST /payout/v1/fiat-withdraw/detail	法币提现详情

认证

所有 Payout API 接口使用与 Payin API 相同的认证机制，详见 签名算法。