Troubleshoot XPayLabs Gateway and Integration Issues

Diagnose and resolve common issues with XPayLabs — including signature errors, connection problems, scanner issues, and webhook failures.

This guide helps you diagnose and resolve common problems with your XPayLabs gateway deployment and API integration.

---

API Issues

401 — Sign Verification Failed

The HMAC-SHA256 signature does not match what the gateway computed.

Checklist:

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

400 — Validation Errors

Message	Likely Cause
"The amount cannot be left blank."	amount is null, undefined, or not a valid number
"The symbol cannot be left blank."	symbol is missing or an empty string
"The chain cannot be left blank."	chain is missing or not a valid chain value
"ReceiveAddress error"	The payout address format does not match the specified chain
"The uid cannot be left blank."	Your merchant account is V2 and requires uid
"The orderId cannot be left blank."	Your merchant account is V3 and requires orderId

---

Blockchain Scanner Issues

Payments Not Detected

If the scanner is not detecting incoming payments:

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.

Scanner is 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

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 logs <core-container-name> to see webhook delivery attempts.
4. Check your endpoint logs: Ensure your server is listening on the correct path and returning HTTP 200.

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

Docker Containers Not Starting

# Check container status
docker compose ps

# View logs for a specific service
docker compose logs core
docker compose logs scanner-tron

Common causes:

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

Gateway Not Responding

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

---

Rate Limiting

If you receive 429 Too Many Requests:

Endpoint	Default Limit
POST /order/createCollection	100 req / 10s per IP
POST /order/createPayout	100 req / 10s per IP
GET /order/pay	2 req / 1s per orderId
GET /order/getOrderStatus	2 req / 1s per orderId

Implement exponential backoff in your integration:

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

If you cannot resolve your issue:

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 [e-mail].

When reporting an issue, include:

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