Deploy XPayLabs and Create Your First Collection in Under 15 Minutes

Learn how to deploy XPayLabs with Docker Compose, configure your merchant token, and create your first crypto payment collection via the REST API.

This quickstart walks you through deploying XPayLabs on your own server and making your first collection order. By the end, you’ll have a running payment gateway and 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)

---

Steps

1. Deploy XPayLabs with Docker Compose

   Clone the repository and start all services:

   git clone https://github.com/xpaylabs/gateway.git
   cd gateway
   docker compose up -d
   

   This starts the core API server (port 3010), blockchain scanners, webhook dispatcher, and the checkout UI. Verify everything is running:

   docker compose ps
   

   All services should show a Up status.

2. Configure your merchant token

   XPayLabs authenticates API requests using HMAC-SHA256 signatures. Your merchant token is configured in the gateway configuration file:

   # config/application.yml
   xpay:
     merchant:
       token: "your-merchant-token-here"
       webhook-secret: "your-webhook-secret-here"
   

   Restart the core container after making changes:

   docker compose restart core
   

   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.

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

4. Verify the collection response

   A successful response returns a payment 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.