Send Crypto Payouts with XPayLabs Payout Orders

Learn how to send crypto payments from your gateway wallet to external blockchain addresses using the XPayLabs payout API.

Payouts let you transfer funds from your gateway-managed wallet to any external blockchain address. This is useful for withdrawing collected funds, paying vendors or affiliates, or moving tokens to exchange wallets.

Creating a Payout

Call POST /v1/order/createPayout with the destination address, amount, symbol, and chain:

import crypto from "crypto";

const GATEWAY_URL = "http://your-gateway:3010";
const MERCHANT_TOKEN = process.env.XPAYLABS_TOKEN;

function signRequest(data) {
  return crypto
    .createHmac("sha256", MERCHANT_TOKEN)
    .update(JSON.stringify(data), "utf8")
    .digest("hex");
}

async function createPayout({ amount, symbol, chain, receiveAddress, orderId }) {
  const data = {
    amount,
    symbol,
    chain,
    receiveAddress,
    orderId,
  };

  const payload = {
    sign: signRequest(data),
    timestamp: Math.floor(Date.now() / 1000),
    nonce: crypto.randomUUID(),
    data,
  };

  const response = await fetch(`${GATEWAY_URL}/v1/order/createPayout`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });

  const result = await response.json();
  if (result.code !== 200) throw new Error(result.msg);

  return result.data;
}

// Send 50 USDT on TRON to an external address
const payout = await createPayout({
  amount: "50.00",
  symbol: "USDT",
  chain: "TRON",
  receiveAddress: "TYourExternalAddress...",
  orderId: "payout_001",
});

console.log(`Payout created: ${payout.orderId}`);

Request Parameters

Parameter	Required	Description
amount	Yes	Amount as decimal string (e.g., "50.00")
symbol	Yes	Token symbol (e.g., "USDT")
chain	Yes	Blockchain network
receiveAddress	Yes	Destination blockchain address
orderId	No	Your identifier for this payout
uid	No	Your user identifier

Address Validation

The gateway validates the receiveAddress format for the specified chain before processing:

Chain	Address Format	Example
TRON	Base58, starts with T	TWkKZkmuB8DpVeiMoHiKf99ZoFHzk73CqR
EVM (ETH, BSC, POLYGON)	Hex, starts with 0x	0x05E833cF6a895a9ABe408FD6a8d5e0d3DB2Fec5A
SUI	Hex, starts with 0x	0x24f672b38299ae651f7598f4994ade780c38aeffa4e595c79ab73d3d176543cd

If the address format is invalid, the API returns "ReceiveAddress error".

---

Payout Status Tracking

After creating a payout, track its status using the order status endpoint:

async function getPayoutStatus(orderId, token) {
  const response = await fetch(
    `${GATEWAY_URL}/v1/order/status/${orderId}`,
    { headers: { "Content-Type": "application/json" } }
  );
  const result = await response.json();
  return result.data;
}

// Poll until completed
const status = await getPayoutStatus("payout_001");
console.log(status.status); // "PENDING", "PENDING_CONFIRMATION", "SUCCESS", "FAILED"
if (status.transaction) {
  console.log(`TxID: ${status.transaction.txid}`);
}

Payout Statuses

Status	Description
PENDING	Payout created, awaiting processing
PENDING_CONFIRMATION	Transaction submitted to blockchain
SUCCESS	Payout confirmed on-chain
FAILED	Payout failed (insufficient balance, etc.)

---

Webhook Notifications

Payouts also trigger webhook events:

Event	When
ORDER_PENDING	Payout order created
ORDER_PENDING_CONFIRMATION	Transaction submitted
ORDER_SUCCESS	Payout confirmed on-chain
ORDER_FAILED	Payout failed

---

Important Security Notes

• Blockchain transactions are irreversible. Double-check the receiveAddress before submitting.
• The gateway validates address format but cannot verify the address is owned by the intended recipient.
• Payouts consume blockchain gas fees (TRX for TRON, ETH gas for EVM chains).
• Ensure your hot wallet has sufficient balance (including gas tokens) before initiating payouts.