Skip to main content

Documentation Index

Fetch the complete documentation index at: https://neilyan.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Settlement in XPayLabs refers to the automatic transfer of received funds from your gateway’s hot wallet (where customer payments arrive) to your cold storage wallet (where funds are secured for long-term holding). This process is known as a “sweep” or “collection.” Unlike traditional payment processors that batch settlements to bank accounts on a T+2 schedule, XPayLabs settlement is a blockchain-native process — funds move directly between your wallets on-chain.

​
How Settlement Works

Customer Payment        Hot Wallet           Cold Wallet
     |                     |                     |
     |--- USDT arrives --->|                     |
     |                     |-- sweep triggered ->|
     |                     |   (auto or manual)  |
     |                     |                     |
     |                     |<-- sweep confirmed -|
     |<-- Webhook: COLLECT_SUCCESS              |
1

Funds arrive in hot wallet

When a customer’s payment is confirmed (ORDER_SUCCESS), the USDT (or other token) sits in the gateway’s hot wallet — an online wallet used for receiving payments.
2

Sweep is triggered

Settlement can be triggered in two ways:
  • Automatic: The gateway monitors accumulated balances and initiates a sweep when configurable thresholds are met (e.g., every 1000 USDT or every hour).
  • Manual: An administrator triggers a sweep through the gateway dashboard.
3

On-chain transfer

The gateway constructs and signs a blockchain transaction that transfers the accumulated tokens from the hot wallet to the cold storage address. This transaction pays standard blockchain gas fees.
4

Sweep confirmed

Once the transfer transaction reaches sufficient block confirmations, a COLLECT_SUCCESS webhook is sent. If the transaction fails, COLLECT_FAILED is sent.

​
Configuration

You configure settlement in the gateway’s application.yml: 
xpay:
  settlement:
    cold-wallet-addresses:
      TRON: "TYourColdWalletAddress..."
      ETH: "0xYourColdWalletAddress..."
      BSC: "0xYourColdWalletAddress..."
    auto-sweep:
      enabled: true
      min-amount: "1000"     # Minimum USDT to trigger sweep
      max-amount: "10000"    # Maximum USDT per sweep transaction
      interval: 3600         # Check interval in seconds (1 hour)
    sweep-on-collect: true   # Sweep immediately after each collection

​
Settlement vs. Payout

SettlementPayout
DirectionHot wallet → Cold walletGateway wallet → External address
PurposeSecure funds in cold storagePay vendors, suppliers, or users
TriggerAutomatic by thresholdManual via API (/createPayout)
DestinationYour own cold walletAny valid blockchain address

​
Webhook Events

Settlement events are delivered via the same webhook system as order events:
EventWhen
COLLECT_PENDINGSweep transaction submitted to the blockchain
COLLECT_SUCCESSSweep transaction confirmed
COLLECT_FAILEDSweep transaction failed
Settlement is a non-custodial process — the gateway is just software that moves funds according to your rules. At no point does any third party have access to your private keys or the ability to redirect funds. All transactions are signed locally within your Docker container.