> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpaylabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Collection Orders: How Crypto Payments Work in XPayLabs

> XPayLabs collection orders generate unique deposit addresses for each transaction. Track the lifecycle from creation to on-chain confirmation with order statuses and webhook events.

A **Collection Order** is the core payment primitive in XPayLabs. When a customer wants to pay you in cryptocurrency, your server creates a collection order through the API. The gateway generates a unique deposit address for that specific transaction, monitors the blockchain for incoming funds, and notifies your server when payment is confirmed.

## What is the collection order lifecycle?

<Steps>
  <Step title="Order Created">
    Your server calls `POST /v1/order/createCollection` with the amount, symbol, and chain. The gateway creates an order with status `INIT` and returns a unique deposit address and checkout URL.
  </Step>

  <Step title="Awaiting Payment">
    The order moves to `PENDING`. The customer sees the deposit address and a QR code on the checkout page. The order has a configurable expiry time.
  </Step>

  <Step title="Transaction Detected">
    The blockchain scanner detects an incoming transaction matching the amount and deposit address. The status changes to `PENDING_CONFIRMATION`. A webhook (`ORDER_PENDING_CONFIRMATION`) is sent with the transaction details.
  </Step>

  <Step title="Confirmed">
    After the required number of block confirmations (configurable per chain), the order status changes to `SUCCESS`. A webhook (`ORDER_SUCCESS`) is sent. The funds are now in your gateway hot wallet.
  </Step>

  <Step title="Expired or Failed">
    If no payment arrives before the expiry time, the order status moves to `EXPIRED`. If the transaction fails validation, it moves to `FAILED`.
  </Step>
</Steps>

## What order statuses does XPayLabs use?

| Status                 | Description                                           |
| ---------------------- | ----------------------------------------------------- |
| `INIT`                 | Order created, deposit address generated              |
| `PENDING`              | Awaiting customer payment                             |
| `PENDING_CONFIRMATION` | Transaction detected, waiting for block confirmations |
| `SUCCESS`              | Payment confirmed, funds available                    |
| `EXPIRED`              | Order expired without receiving payment               |
| `FAILED`               | Collection or payout failed                           |

## How do collections flow from server to blockchain?

```
Merchant Server          XPayLabs Gateway          Blockchain           Customer
     |                         |                       |                    |
     |-- POST /createCollection -->|                    |                    |
     |<-- PaymentAddress ---------|                    |                    |
     |                         |                       |                    |
     |                         |                       |<-- sends funds ----|
     |                         |<-- scanner detects ---|                    |
     |<-- Webhook: PENDING_CONFIRMATION                |                    |
     |                         |                       |                    |
     |                         |<-- block confirmed ---|                    |
     |<-- Webhook: ORDER_SUCCESS                       |                    |
```

## PaymentAddress Object

When you create a collection, the gateway returns a `PaymentAddress` object:

| Field         | Description                                |
| ------------- | ------------------------------------------ |
| `address`     | Unique deposit address for this collection |
| `amount`      | The requested amount                       |
| `symbol`      | Token symbol (e.g., USDT)                  |
| `chain`       | Blockchain network                         |
| `orderId`     | Your order identifier                      |
| `uid`         | Your user identifier                       |
| `expiredTime` | Order expiry timestamp                     |
| `paymentUrl`  | Checkout page URL with QR code             |

## Amount Format

All amounts are **string-formatted decimals** (e.g., `"100.00"`). This avoids floating-point precision issues common in JavaScript when dealing with large numbers.

## Deposit Addresses

Each collection order gets a **unique, single-use deposit address**. This provides clear on-chain attribution — you can always identify which customer paid for which order by looking at the deposit address in the blockchain transaction. Addresses are generated deterministically from your gateway's HD wallet seed, so they never need to be pre-generated or stored externally.