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

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)

string

required

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

string

required

The token symbol to accept, e.g. "USDT". Must be a supported symbol on the specified 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

string

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

string

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

cURL

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

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

string

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

string

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

string

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

string

The blockchain network. Example: "TRON".

string

Your order identifier, echoed back from the request.

string

Your user identifier, echoed back from the request.

integer

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

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

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

Overview

Orders

Symbols

Webhooks

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

Request

Headers

Body Parameters (`data` field)

cURL

Node.js

Response

PaymentAddress Object

Example Response

Error Responses

`400` — Validation Error

`429` — Rate Limit Exceeded

​Request

​Headers

​Body Parameters (data field)

​cURL

​Node.js

​Response

​PaymentAddress Object

​Example Response

​Error Responses

​400 — Validation Error

​429 — Rate Limit Exceeded

Request

Headers

Body Parameters (`data` field)

cURL

Node.js

Response

PaymentAddress Object

Example Response

Error Responses

`400` — Validation Error

`429` — Rate Limit Exceeded