Deploy XPayLabs: Docker Compose Crypto Payment Quickstart

Deploy XPayLabs with Docker Compose and create your first collection order in under 15 minutes. By the end of this guide, you’ll have a running crypto payment gateway on your own infrastructure with a working test collection.

Prerequisites

A server with 8GB RAM / 4 vCPU (Ubuntu 22.04+ recommended)
Docker and Docker Compose installed
RPC endpoints for the blockchains you want to support (TRON, EVM, SUI)

How to deploy XPayLabs in 4 steps

Deploy XPayLabs with Docker Compose

Clone the repository and start all services:

git clone https://github.com/yan253319066/XPayLabs-docker.git
cd XPayLabs-docker
docker compose up -d

This starts all services including Java backends (xpay-user, xpay-merchant, xpay-eth, xpay-tron, xpay-sui), blockchain scanners, and the checkout UI. Verify everything is running:

docker compose ps

All services should show a Up status.

Configure your merchant token

XPayLabs authenticates API requests using HMAC-SHA256 signatures. Your merchant token is generated in the gateway dashboard when you create your merchant account.

The merchant token is a shared secret. It never appears in API requests directly — instead, you use it to sign request payloads. Store it securely and never commit it to version control.

Create a test collection

Send a POST request to create a collection order. The request body must include a sign field computed over the payload.

# Replace TOKEN with your merchant token
curl --request POST \
  --url http://your-server:180/v1/order/createCollection \
  --header "Content-Type: application/json" \
  --data '{
    "sign": "generated_hmac_signature",
    "timestamp": 1717000000,
    "nonce": "unique_nonce_123",
    "data": {
      "amount": "100.00",
      "symbol": "USDT",
      "chain": "TRON",
      "orderId": "merchant_order_001"
    }
  }'

See the Authentication page for how to compute the sign value.

Verify the collection response

A successful response returns a deposit address and checkout URL:

{
  "code": 200,
  "msg": "success",
  "data": {
    "address": "TWkKZkmuB8DpVeiMoHiKf99ZoFHzk73CqR",
    "amount": "100.00",
    "symbol": "USDT",
    "chain": "TRON",
    "orderId": "merchant_order_001",
    "expiredTime": 1717086400,
    "paymentUrl": "http://your-server/checkout?orderId=merchant_order_001"
  }
}

The address field is where your customer sends funds. The paymentUrl leads to a hosted checkout page with a QR code and payment instructions.

What’s Next?

Authentication

Learn how the HMAC signing algorithm works and how to implement it in your language.

API Reference

Explore all endpoints for collections, payouts, and webhooks.

During development, use testnet networks (TRON Shasta, ETH Sepolia, BSC Testnet) to avoid real gas costs. See the Testing guide for testnet configuration and test token faucets.

​Prerequisites

​How to deploy XPayLabs in 4 steps

​What’s Next?

Authentication

API Reference

Prerequisites

How to deploy XPayLabs in 4 steps

What’s Next?