Payout (payment/disbursement) is the capability for merchants to initiate cryptocurrency payments to end users through NUSDpay. After integrating the Payout API, merchants can initiate on-chain transfers (USDT/USDC) from their NUSD wallet balance to end users’ wallet addresses, enabling business scenarios such as withdrawals, revenue sharing, and refunds.

​
Business Flow

​
Sequence Diagram

The following shows the complete lifecycle of a Payout transaction:
Payout sequence diagram

​
Operation Steps

1

Initiate the payment request

Call the POST /nps/withdraw API, passing the recipient address, amount, chain, and token.
{
  "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"
}
request_id must be globally unique and is used to prevent duplicate submissions. The same request_id will not create a new transaction.
2

System validation and freezing

The NUSDpay system performs the following validations:
  • Whether the balance is sufficient (including fees)
  • Whether the chain and token are supported
  • Whether the recipient address format is valid
Once validation passes, the corresponding amount is moved from the available balance into the frozen (hold) balance.
3

Risk control review

The transaction enters the risk control workflow:
  • AML/KYC review: Anti-money laundering and customer identity verification
  • Address allowlist check: Whether the recipient address is in the allowlist
  • Risk control rule engine: Whether the transaction amount, frequency, etc., trigger risk control rules
4

On-chain broadcast and confirmation

After the review passes, the system constructs the on-chain transaction and broadcasts it to the blockchain network. After block confirmation, the transaction is complete.
5

Webhook notification

After the transaction is complete, the system pushes a wallets.transaction.succeeded event to the Webhook URL configured by the merchant.

​
Fund Flow

​
Balance Model

The merchant wallet balance is divided into two parts:
TypeDescription
Available balance (available)Amount that can be used to initiate Payouts or transfers
Frozen balance (hold)Payout / transfer amounts that have been initiated but not yet completed
Total balanceAvailable balance + frozen balance
Balance change example: 
Initial state: available = 1000, hold = 0

Initiate Payout of 100 NUSD:
  → available = 900, hold = 100

Payout completed (success):
  → available = 900, hold = 0  (after fee deduction)

Payout failed:
  → available = 1000, hold = 0  (freeze released, balance restored)

​
Funding Modes

Payout funds come from the merchant’s NUSD wallet balance. Merchants need to ensure that the wallet has sufficient available NUSD balance. There are two ways to fund:
  • Option 1: Internal transfer — Transfer NUSD from another project wallet of the merchant (such as a Payin wallet) to the Payout wallet
  • Option 2: External top-up — The merchant deposits USDT/USDC directly to the Payout wallet address, and the system automatically converts it to NUSD for crediting
We recommend setting up a balance alert in the admin console to top up funds promptly when the available balance falls below the threshold, avoiding Payout failures due to insufficient balance.

​
Fee Model

NUSDpay Payout supports two fee modes:

​
App-Pays Mode (Merchant Pays the Fee)

The fee is borne by the merchant; the end user receives the full amount. 
End user receives = Payment amount × Exchange rate
The fee is additionally deducted from the merchant's balance
Applicable scenarios: The merchant wants to ensure the end user receives the precise agreed amount (e.g., refunds, payroll).

​
User-Pays Mode (End User Pays the Fee)

The fee is deducted from the payment amount; the amount actually received by the end user is reduced. 
End user receives = Payment amount × (1 - Service fee rate) × Exchange rate
Applicable scenarios: The merchant wants to control costs and have the end user pay the fee (e.g., withdrawals).

​
Fee Description

Fee TypeDescription
Service fee rateConfigured per project; supports custom rates
Exchange rateRefers to the real-time market exchange rate (USDC/USDT); the API returns the actual rate
Gas feeAdvanced by the platform; already included in the service fee
The specific fee rates are subject to the contractual agreement. You can obtain the current fee configuration via the Query Platform Fees API.

​
Transaction Status

Complete status flow of a Payout transaction:
Payout status flow
StatusDescription
ReviewingTransaction under review
PendingWaiting to be processed (including sub-statuses such as AML review, risk control review, and address allowlist check)
ConfirmingBroadcast to the chain, waiting for block confirmation
CompletedTransaction completed; funds delivered
FailedTransaction failed (includes specific failure reasons)
For detailed status and sub-status descriptions, see Transaction Status Reference.

​
Exception Handling

​
Insufficient Balance

When initiating a Payout, if the available balance is insufficient (including fees), the API will return an error. Please ensure the wallet has sufficient available balance.

​
Risk Control Interception

When a transaction is intercepted by risk control rules, the status changes to Failed, and the frozen funds are automatically released. The Webhook notification contains the specific failure reason. Common interception reasons:
  • Recipient address is not on the allowlist
  • Single transaction amount exceeds the limit
  • AML rule triggered

​
On-Chain Failure

In rare cases, the transaction fails on-chain (e.g., insufficient gas, contract exception). The NUSDpay system will automatically retry or mark the transaction as failed and release the frozen NUSD funds.

​
Webhook Not Received

If Webhook delivery fails (timeout or non-200/201 response), the system automatically retries up to 10 times. We recommend:
  • Ensure the Webhook endpoint responds within 2 seconds
  • Use request_id for idempotent handling
  • Periodically call the Transaction Records API as a reconciliation fallback

​
Next Steps

Payin Solution

Learn how to receive cryptocurrency deposits from customers.

Transfer Solution

Learn how to use inter-project fund transfers.