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.

XPayLabs sends webhook notifications based on the NotifyType enum. Each notification corresponds to a change in state of an order or a collection sweep.

​
Event Types

Event TypeTriggered WhenPayload
ORDER_PENDINGA new order is created and is awaiting customer paymentNotifyOrder
ORDER_PENDING_CONFIRMATIONA blockchain transaction is detected but awaiting confirmationsNotifyOrder
ORDER_SUCCESSPayment confirmed and order completed successfullyNotifyOrder
ORDER_EXPIREDOrder expired before payment was receivedNotifyOrder
ORDER_FAILEDPayment transaction failedNotifyOrder
COLLECT_PENDINGCollection sweep (hot-to-cold transfer) is initiatedNotifyCollect
COLLECT_SUCCESSCollection sweep completed successfullyNotifyCollect
COLLECT_FAILEDCollection sweep failedNotifyCollect

​
Order Events (ORDER_*)

​
ORDER_PENDING

Sent when a collection or payout order is created and is awaiting the next action (customer payment for collections, processing for payouts). 
{
  "sign": "a1b2c3d4e5f6...",
  "timestamp": 1717000000,
  "nonce": "nonce_001",
  "notifyType": "ORDER_PENDING",
  "data": {
    "orderId": "order_1042",
    "uid": "user_42",
    "orderType": "COLLECTION",
    "status": "PENDING",
    "reason": null,
    "amount": "250.00",
    "actualAmount": null,
    "fee": "0.00",
    "transaction": null
  }
}

​
ORDER_PENDING_CONFIRMATION

Sent when a blockchain transaction is detected but has not yet reached the required number of block confirmations. The transaction field is populated with the detected transaction details. 
{
  "sign": "a1b2c3d4e5f6...",
  "timestamp": 1717000050,
  "nonce": "nonce_002",
  "notifyType": "ORDER_PENDING_CONFIRMATION",
  "data": {
    "orderId": "order_1042",
    "orderType": "COLLECTION",
    "status": "PENDING_CONFIRMATION",
    "amount": "250.00",
    "actualAmount": "250.00",
    "fee": "0.00",
    "transaction": {
      "chain": "TRON",
      "symbol": "USDT",
      "txid": "a1b2c3d4e5f6...",
      "from": "TXyz...",
      "to": "TWkKZkmuB8DpVeiMoHiKf99ZoFHzk73CqR",
      "amount": "250.00",
      "blockNum": 12345678,
      "confirmedNum": 1,
      "status": "PENDING",
      "timestamp": 1717000045
    }
  }
}

​
ORDER_SUCCESS

Sent when the payment is fully confirmed (required block confirmations reached) or a payout completes successfully. 
{
  "sign": "a1b2c3d4e5f6...",
  "timestamp": 1717000100,
  "nonce": "nonce_003",
  "notifyType": "ORDER_SUCCESS",
  "data": {
    "orderId": "order_1042",
    "orderType": "COLLECTION",
    "status": "SUCCESS",
    "amount": "250.00",
    "actualAmount": "250.00",
    "fee": "0.00",
    "transaction": {
      "chain": "TRON",
      "symbol": "USDT",
      "txid": "a1b2c3d4e5f6...",
      "from": "TXyz...",
      "to": "TWkKZkmuB8DpVeiMoHiKf99ZoFHzk73CqR",
      "amount": "250.00",
      "confirmedNum": 19,
      "status": "SUCCESS",
      "timestamp": 1717000045
    }
  }
}

​
ORDER_EXPIRED

Sent when an order reaches its expiry time without receiving the required payment. 
{
  "sign": "a1b2c3d4e5f6...",
  "timestamp": 1717086401,
  "nonce": "nonce_004",
  "notifyType": "ORDER_EXPIRED",
  "data": {
    "orderId": "order_1042",
    "orderType": "COLLECTION",
    "status": "EXPIRED",
    "reason": "Order expired",
    "amount": "250.00",
    "actualAmount": null,
    "fee": "0.00",
    "transaction": null
  }
}

​
ORDER_FAILED

Sent when a payout transaction fails or a collection transaction is rejected by the blockchain. 
{
  "sign": "a1b2c3d4e5f6...",
  "timestamp": 1717000200,
  "nonce": "nonce_005",
  "notifyType": "ORDER_FAILED",
  "data": {
    "orderId": "payout_001",
    "orderType": "PAYOUT",
    "status": "FAILED",
    "reason": "Insufficient balance",
    "amount": "50.00",
    "actualAmount": "0.00",
    "fee": "0.00",
    "transaction": null
  }
}

​
Collection Events (COLLECT_*)

Collection events are sent when the gateway performs automatic hot-to-cold wallet sweeps (settlement). These are distinct from order events — they relate to the internal movement of funds between the gateway’s wallets.
Event TypeTriggered When
COLLECT_PENDINGA sweep from the hot wallet to the cold wallet is initiated
COLLECT_SUCCESSThe sweep transaction confirmed on-chain
COLLECT_FAILEDThe sweep transaction failed

​
Best Practices

  1. Respond with 200 quickly. Return 200 OK immediately and process the event asynchronously in a background worker.
  2. Verify the signature. Always validate the sign field using your webhook-secret before acting on any event.
  3. Deduplicate with nonce. The same event may be delivered more than once. Store processed nonces in your database and skip duplicates.
  4. Check notifyType first. Route to different handlers based on the event type.
  5. Handle ORDER_PENDING_CONFIRMATION. Use this event to show “payment detected” in your UI before the transaction is fully confirmed.