Understanding Collection Orders — The Core of XPayLabs Payments

Learn how XPayLabs models payment collection: the lifecycle of a collection order from creation to on-chain confirmation, order statuses, and the PaymentAddress object.

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.

Collection Lifecycle

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

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

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

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

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

Order Statuses

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

Collection Flow Diagram

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. The internal representation uses BigDecimal in the Java backend, ensuring exact precision.

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.