Payout（付款/代付）是商户通过 NUSDpay 向收款方发起付款的能力。商户集成 Payout API 后，可以从自己的 NUSD 钱包余额向收款方付款，实现提现、分润、退款、给 NUSD Wallet 用户打款等业务场景。 NUSDpay 提供两种付款方式，二者效果不同，请根据收款方类型选择：
付款方式接口效果收款方适用场景
链上付款（提币）POST /nps/withdraw/onchain链上支付：构造区块链交易，向链上地址转出 USDT/USDC，需区块确认、产生 Gas外部链上钱包地址（to，如 0x...）提现、分润、退款到加密钱包
站内付款（划转）POST /nps/withdraw/internal站内支付：在 NUSDpay 系统账本内完成，资金从一个钱包转到另一个钱包，实时到账、不上链、无 GasNUSD 体系内的钱包（wallet_to），可指定 NUSD Wallet 终端用户（user_token）给 NUSD Wallet 用户付款、项目间结算
关键区别：链上付款（提币）的钱真正离开 NUSDpay 走到区块链上的外部地址；站内付款（划转）的钱始终留在 NUSDpay 体系内，只是改变归属钱包。前者用于付给链上加密钱包，后者用于付给 NUSD Wallet 体系内的收款方。

​
一、链上付款（提币）

向外部链上钱包地址发起加密货币付款，经区块链网络转账，适合提现、分润、退款到加密钱包。

​
时序图

以下是一笔链上付款（提币）交易的完整生命周期：
Payout 付款时序

​
操作步骤

1

发起提币请求

调用 POST /nps/withdraw/onchain 接口，传入收款链上地址、金额、链和币种。
{
  "request_id": "d8551182-0aee-4346-929e-05c99081352a",
  "wallet_id": "e9167870-e18b-4e82-8b87-92ec7ede8e45",
  "to": "0xdc2e6b357766aa4b66f41dc29598379ce7d61d46",
  "amount": "100.00",
  "chain_id": "BASE_ETH",
  "token_id": "BASE_USDT",
  "payer": "App"
}
request_id 必须全局唯一，用于防止重复提交。相同的 request_id 不会创建新交易。
2

系统校验与冻结

NUSDpay 系统执行以下校验：
  • 余额是否充足（含手续费）
  • 链和币种是否支持
  • 收款地址格式是否合法
校验通过后，对应金额从可用余额（available）转入冻结余额（hold）。
3

风控审核

交易进入风控流程：
  • AML/KYC 审核：反洗钱与客户身份验证
  • 地址白名单检查：收款地址是否在允许列表内
  • 风控规则引擎：交易金额、频率等是否触发风控规则
4

链上广播与确认

审核通过后，系统构造链上交易并广播到区块链网络。等待区块确认后，交易完成。
5

Webhook 通知

交易完成后，系统向商户配置的 Webhook 地址推送提币结果事件。详见 提币 Webhook。

​
二、站内付款（划转）

向 NUSDpay 体系内的钱包付款（如 NUSD Wallet 终端用户）。资金在系统账本内从一个钱包转到另一个钱包，实时到账、不上链、无 Gas 费，适合给 NUSD Wallet 用户打款、项目间结算。

​
时序图

站内付款（划转）时序

​
操作步骤

1

发起划转请求

调用 POST /nps/withdraw/internal 接口，传入转出钱包、接收钱包和金额。与提币不同，划转不需要链和币种（因为不上链）。
{
  "request_id": "ea6f928b-0b1f-4fd3-a4fe-fc10695d2642",
  "wallet_from": "332cf3e4-af07-46f9-a3da-4aa2cbe3bdd4",
  "wallet_to": "1b8d5efd-d7a8-48ac-a195-cc8e043ae36b",
  "amount": "50.00",
  "user_token": "10001",
  "user_name": "张三",
  "notes": "6月分润"
}
其中 user_token、user_name、notes 为可选字段：当收款方是 NUSD Wallet 终端用户时，可用 user_token 指定对应的 app 用户、user_name 记录收款人姓名、notes 备注用途。
2

系统校验

NUSDpay 校验转出钱包可用余额是否充足、接收钱包是否有效。
3

站内账本入账

校验通过后，金额从 wallet_from 的可用余额扣除，实时计入 wallet_to。不构造链上交易、无需区块确认、无 Gas 费。
4

Webhook 通知

划转完成后，系统向商户配置的 Webhook 地址推送划转结果事件。详见 划转 Webhook。
站内付款（划转）与 划转方案 使用同一接口能力：本页侧重通过 API 向 NUSD 体系内收款方（如 NUSD Wallet 用户）付款；划转方案 侧重商户在自有项目钱包之间调拨备款。两者都不涉及链上交易。

​
资金流转

​
余额模型

商户钱包余额分为两部分：
类型说明
可用余额（available）可用于发起付款（提币 / 划转）的金额
冻结余额（hold）已发起但尚未完成的链上提币金额
总余额可用余额 + 冻结余额
余额变动示例（链上提币）： 
初始状态：available = 1000, hold = 0

发起提币 100 NUSD：
  → available = 900, hold = 100

提币完成（成功）：
  → available = 900, hold = 0  （扣除手续费后）

提币失败：
  → available = 1000, hold = 0  （冻结释放，余额恢复）
站内付款（划转）在系统账本内实时完成，金额直接从转出钱包可用余额扣减、计入接收钱包，一般不经过「冻结」中间态。

​
备款模式

付款资金来自商户的 NUSD 钱包余额。商户需确保钱包中有足够的可用 NUSD 余额，备款方式有两种：
  • 方式一：内部划转 — 通过站内划转，从商户的其他项目钱包（如 Payin 收款钱包）调拨 NUSD 到付款钱包（详见 划转方案）
  • 方式二：外部充值 — 商户直接向付款钱包地址转入 USDT/USDC，系统自动换算为 NUSD 入账
建议在管理后台设置余额告警，当可用余额低于阈值时及时补充资金，避免付款因余额不足失败。

​
手续费模型

项目链上付款（提币）站内付款（划转）
Gas 费有（由平台垫付，已包含在服务费中）无（不上链）
手续费承担方由请求中的 payer 决定（App 项目方承担 / User 用户承担，默认用户承担）站内划转无 Gas；服务费以签约协议为准
链上提币的两种手续费模式：

​
App 付费模式（商户承担手续费）

手续费由商户承担，收款方全额到账。 
收款方到账 = 支付金额 × 汇率
手续费从商户余额额外扣除
适用场景：商户希望确保收款方收到约定的精确金额（如退款、发薪）。

​
User 付费模式（收款方承担手续费）

手续费从支付金额中扣除，收款方实际到账金额减少。 
收款方到账 = 支付金额 × (1 - 服务费率) × 汇率
适用场景：商户希望控制成本，由收款方承担手续费（如提现）。

​
费率说明

费率类型说明
服务费率按项目配置，支持自定义费率
汇率参考市场实时汇率（USDC/USDT），接口返回实际汇率
Gas 费由平台垫付，已包含在服务费中（仅链上付款产生）
具体费率以签约协议为准。您可通过 查询平台费用 接口获取当前费率配置。

​
交易状态

链上付款（提币）交易的完整状态流转：
Payout 状态流转
状态说明
Reviewing交易审核中
Pending等待处理（含 AML 审核、风控审核、地址白名单检查等子状态）
Confirming已广播到链上，等待区块确认
Completed交易完成，资金已到账
Failed交易失败（含具体失败原因）
站内付款（划转）不上链，没有 Confirming（链上确认）阶段，校验通过后即实时完成。
详细的状态与子状态说明请参阅 交易状态说明。

​
异常处理

​
余额不足

发起付款时，如果可用余额不足（链上提币还需含手续费），接口将返回错误。请确保钱包中有足够的可用余额。

​
风控拦截

链上提币被风控规则拦截时，状态变为 Failed，冻结资金自动释放。Webhook 通知中包含具体的失败原因。常见拦截原因：
  • 收款地址未在白名单中
  • 单笔金额超过限额
  • 触发 AML 规则

​
链上失败（仅链上付款）

极少数情况下，提币在链上执行失败（如 Gas 不足、合约异常）。NUSDpay 系统会自动重试或将交易标记为失败，并释放冻结 NUSD 资金。站内付款（划转）不上链，不存在此类异常。

​
Webhook 未收到

如果 Webhook 推送失败（超时或非 200/201 响应），系统会自动重试，最多 10 次。建议：
  • 确保 Webhook 端点在 2 秒内响应
  • 使用 request_id 做幂等处理
  • 定期调用 交易记录 接口做对账兜底

​
下一步

Payin 收款方案

了解如何接收客户的加密货币充值。

划转方案

了解商户自有项目钱包间资金调拨的使用方式。