> ## 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.

# Create a Collection Order | POST /v1/order/createCollection

> Create a collection order to receive crypto payments. Returns a unique deposit address and checkout URL for the customer to send funds.

Creates a new collection order. The gateway generates a unique deposit address for the specified blockchain and token. Your customer sends funds to this address, and the blockchain scanner detects the transaction automatically.

## Request

**`POST http://your-gateway:180/v1/order/createCollection`**

### Headers

| Header         | Value              |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

### Body Parameters (`data` field)

<ParamField body="amount" type="string" required>
  The payment amount as a decimal string, e.g. `"100.00"`. Must be greater than zero.
</ParamField>

<ParamField body="symbol" type="string" required>
  The token symbol to accept, e.g. `"USDT"`. Must be a supported symbol on the specified chain.
</ParamField>

<ParamField body="chain" type="string" required>
  The blockchain network:

  * `TRON` — TRC20 tokens (USDT, USDC)
  * `ETH` — Ethereum ERC20
  * `BSC` — BNB Smart Chain BEP20
  * `POLYGON` — Polygon
  * `AVAX_C_CHAIN` — Avalanche C-Chain
  * `SUI` — SUI Network
</ParamField>

<ParamField body="orderId" type="string" optional>
  Your unique order identifier. Required for V3 merchants. Used to correlate the collection with your internal order system.
</ParamField>

<ParamField body="uid" type="string" optional>
  Your internal user identifier. Required for V2 merchants. Cannot be `"0"`.
</ParamField>

### cURL

```bash theme={null}
curl -X POST http://your-gateway:180/v1/order/createCollection \
  -H "Content-Type: application/json" \
  -d '{
    "sign": "a1b2c3d4e5f6...",
    "timestamp": 1717000000,
    "nonce": "550e8400-e29b-41d4-a716-446655440000",
    "data": {
      "amount": "250.00",
      "symbol": "USDT",
      "chain": "TRON",
      "orderId": "order_1042"
    }
  }'
```

### Node.js

```javascript theme={null}
import crypto from "crypto";

const MERCHANT_TOKEN = process.env.XPAYLABS_TOKEN;

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

const data = { amount: "250.00", symbol: "USDT", chain: "TRON", orderId: "order_1042" };
const payload = {
  sign: signRequest(data),
  timestamp: Math.floor(Date.now() / 1000),
  nonce: crypto.randomUUID(),
  data,
};

const response = await fetch("http://your-gateway:180/v1/order/createCollection", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

const result = await response.json();
console.log(result.data.address);    // Deposit address
console.log(result.data.paymentUrl); // Checkout URL
```

***

## Response

A successful request returns HTTP `200` with the `R<PaymentAddress>` envelope.

### PaymentAddress Object

<ResponseField name="address" type="string">
  The generated deposit address where the customer sends funds. Example: `"TWkKZkmuB8DpVeiMoHiKf99ZoFHzk73CqR"`.
</ResponseField>

<ResponseField name="amount" type="string">
  The collection amount as a decimal string. Matches the request amount.
</ResponseField>

<ResponseField name="symbol" type="string">
  The token symbol for this collection. Example: `"USDT"`.
</ResponseField>

<ResponseField name="chain" type="string">
  The blockchain network. Example: `"TRON"`.
</ResponseField>

<ResponseField name="orderId" type="string">
  Your order identifier, echoed back from the request.
</ResponseField>

<ResponseField name="uid" type="string">
  Your user identifier, echoed back from the request.
</ResponseField>

<ResponseField name="expiredTime" type="integer">
  Unix timestamp when this collection expires. After expiry, the deposit address is no longer valid for new transactions.
</ResponseField>

<ResponseField name="paymentUrl" type="string">
  URL to the hosted checkout page where the customer can view payment instructions and a QR code.
</ResponseField>

### Example Response

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "data": {
    "address": "TWkKZkmuB8DpVeiMoHiKf99ZoFHzk73CqR",
    "amount": "250.00",
    "symbol": "USDT",
    "chain": "TRON",
    "orderId": "order_1042",
    "uid": null,
    "expiredTime": 1717086400,
    "paymentUrl": "http://your-gateway:180/checkout?orderId=order_1042"
  }
}
```

***

## Error Responses

### `400` — Validation Error

| Message                               | Cause                                              |
| ------------------------------------- | -------------------------------------------------- |
| `"The amount cannot be left blank."`  | `amount` is missing or null                        |
| `"The symbol cannot be left blank."`  | `symbol` is missing or empty                       |
| `"The chain cannot be left blank."`   | `chain` is missing or invalid                      |
| `"The orderId cannot be left blank."` | `orderId` is required for V3 merchants but missing |
| `"The uid cannot be left blank."`     | `uid` is required for V2 merchants but missing     |
| `"The uid cannot be zero."`           | `uid` is set to `"0"`                              |

### `429` — Rate Limit Exceeded

```json theme={null}
{
  "code": 429,
  "msg": "Too many requests. Please slow down.",
  "data": null
}
```