Skip to main content

Documentation Index

Fetch the complete documentation index at: https://neilyan.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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.