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:3010/v1/order/createCollection

Headers

Header	Value
Content-Type	application/json

Body Parameters (data field)

amount · string · required

The payment amount as a decimal string, e.g. "100.00". Must be greater than zero.

symbol · string · required

The token symbol to accept, e.g. "USDT". Must be a supported symbol on the specified chain.

chain · 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

orderId · string

Your unique order identifier. Required for V3 merchants. Used to correlate the collection with your internal order system.

uid · string

Your internal user identifier. Required for V2 merchants. Cannot be "0".

cURL

curl -X POST http://your-gateway:3010/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

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:3010/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

address · string

The generated deposit address where the customer sends funds. Example: "TWkKZkmuB8DpVeiMoHiKf99ZoFHzk73CqR".

amount · string

The collection amount as a decimal string. Matches the request amount.

symbol · string

The token symbol for this collection. Example: "USDT".

chain · string

The blockchain network. Example: "TRON".

orderId · string

Your order identifier, echoed back from the request.

uid · string

Your user identifier, echoed back from the request.

expiredTime · integer

Unix timestamp when this collection expires. After expiry, the deposit address is no longer valid for new transactions.

paymentUrl · string

URL to the hosted checkout page where the customer can view payment instructions and a QR code.

Example Response

{
  "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:3010/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

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