Troubleshooting: XPayLabs Gateway Error Solutions

​

API Issues

​

Why am I getting 401 sign verification failed?

1. JSON serialization — Ensure the data object is serialized as compact JSON (no spaces, no newlines). JSON.stringify(obj) in JavaScript produces the correct format by default.
2. Data content — The sign is computed over only the data field, not the full request envelope. The sign, timestamp, and nonce fields are excluded.
3. Token mismatch — Confirm the MERCHANT_TOKEN used to compute the signature matches the token configured in the gateway.
4. Character encoding — Ensure the token and JSON string are UTF-8 encoded.
5. Test your signature — Compute the signature for a known payload and compare:

const crypto = require("crypto");
const token = "your-merchant-token";
const data = { amount: "100.00", symbol: "USDT", chain: "TRON" };
const sign = crypto
  .createHmac("sha256", token)
  .update(JSON.stringify(data), "utf8")
  .digest("hex");
console.log(sign); // Should match what gateway expects

​

Why am I getting 400 validation errors?

​

Blockchain Scanner Issues

​

Why are blockchain payments not detected?

1. Check scanner logs: docker logs <scanner-container-name>
2. Verify RPC endpoints: Ensure the configured RPC URL is accessible from the gateway server.
3. Check block height: The scanner syncs from the last processed block. If the gateway was recently deployed, it may need time to catch up.
4. Confirm token configuration: Verify the token contract address is correctly configured for the chain.
5. Check blockchain explorer: Confirm the transaction actually exists on-chain at the expected address.

​

Why is the scanner slow?

• RPC rate limits: Public RPC endpoints may throttle high-frequency requests. Consider using dedicated RPC endpoints.
• Block time: Different chains have different block times. TRON produces blocks every 3 seconds, Ethereum every 12 seconds.
• Confirmation requirements: Configure the required number of block confirmations per chain in the gateway settings.

​

Webhook Problems

​

Why am I not receiving webhooks?

1. Verify callback URL: Check the callback-url in your gateway configuration.
2. Network accessibility: The gateway must be able to reach your callback URL. If testing locally, use a tunneling tool like ngrok.
3. Check gateway logs: docker compose logs xpay-user to see webhook delivery attempts.
4. Check your endpoint logs: Ensure your server is listening on the correct path and returning HTTP 200.

​

Why is webhook signature verification failing?

1. Raw data vs. full payload: Verify the signature over the data field only, not the full NotifyPayload.
2. Webhook secret mismatch: Confirm the webhook-secret used for verification matches what is configured in the gateway.
3. JSON format: The data field must be serialized as compact JSON for verification.

​

Deployment Issues

​

Why are Docker containers not starting?

# Check container status
docker compose ps

# View logs for a specific service
docker compose logs xpay-user
docker compose logs xpay-tron

• Port 180 already in use
• Insufficient disk space
• Missing environment variables in configuration

​

Why is the gateway not responding?

1. Verify container is running: docker compose ps should show Up status.
2. Check port binding: docker compose port gateway 180
3. Test locally: curl http://localhost:180/v1/symbol/supportSymbols
4. Check firewall: Ensure port 180 is open in your server firewall.

​

Rate Limiting

async function fetchWithRetry(url, options, retries = 5) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;
    const delay = Math.pow(2, i) * 1000 + Math.random() * 1000;
    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error("Max retries exceeded");
}

​

Getting Help

1. Check the container logs for error messages.
2. Review the FAQ for common questions.
3. Open a GitHub issue at github.com/xpaylabs/gateway.
4. For commercial support, contact support@xpaylabs.com.

• Gateway version and deployment method
• Relevant configuration (redact secrets)
• Complete error messages and logs
• Steps to reproduce