Collection Orders: How Crypto Payments Work in XPayLabs

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?

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.

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.

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.

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.

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.

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.

Get Started

Core Concepts

Guides

x402 Protocol

Support

Collection Orders: How Crypto Payments Work in XPayLabs

What is the collection order lifecycle?

What order statuses does XPayLabs use?

How do collections flow from server to blockchain?

PaymentAddress Object

Amount Format

Deposit Addresses

​What is the collection order lifecycle?

​What order statuses does XPayLabs use?

​How do collections flow from server to blockchain?

​PaymentAddress Object

​Amount Format

​Deposit Addresses

What is the collection order lifecycle?

What order statuses does XPayLabs use?

How do collections flow from server to blockchain?

PaymentAddress Object

Amount Format

Deposit Addresses