Spring Boot + XPayLabs: Java SDK Crypto Payments

Integrate crypto payments into your Spring Boot application using the official XPayLabs Java SDK (xpay-java-sdk). The SDK provides a comprehensive client for collection orders, payouts, webhook handling, and balance management with HMAC-SHA256 signing handled automatically.

Installation

Add the Maven dependency to your pom.xml:

<dependency>
  <groupId>com.xpaylabs</groupId>
  <artifactId>xpay-java-sdk</artifactId>
  <version>0.1.0</version>
</dependency>

For Gradle:

implementation 'com.xpaylabs:xpay-java-sdk:0.1.0'

Configuration

Configure the SDK with your merchant token and API secret:

import com.xpaylabs.sdk.XPay;
import com.xpaylabs.sdk.XPayConfig;

@Configuration
public class XPayConfigBean {

  @Bean
  public XPay xPayClient() {
    XPayConfig config = XPayConfig.builder()
        .apiKey("your-merchant-token")
        .apiSecret("your-api-secret")
        .baseUrl("http://your-gateway:180")
        .connectTimeout(30000)
        .readTimeout(30000)
        .build();

    return new XPay(config);
  }
}

Property	Required	Description
`apiKey`	Yes	Merchant token
`apiSecret`	Yes	API secret for HMAC signing
`baseUrl`	No	Gateway base URL (default: `https://api.xpaylabs.com`; override for self-hosted deployments)
`connectTimeout`	No	Connection timeout in ms (default: 30000)
`readTimeout`	No	Read timeout in ms (default: 30000)

Core API Methods

Create a Collection Order

import com.xpaylabs.sdk.model.request.CollectionRequest;
import com.xpaylabs.sdk.model.response.ApiResponse;
import com.xpaylabs.sdk.model.response.CollectionData;

@RestController
public class PaymentController {

  private final XPay xpay;

  public PaymentController(XPay xpay) {
    this.xpay = xpay;
  }

  public CollectionData createPayment(String uid, String amount) throws Exception {
    CollectionRequest request = CollectionRequest.builder()
        .amount(50.0)
        .symbol("USDT")
        .chain("TRON")
        .orderId("order-" + System.currentTimeMillis())
        .uid(uid)
        .build();

    ApiResponse<CollectionData> response = xpay.createCollection(request);

    if (response.getCode() != 200) {
      throw new RuntimeException("Collection failed: " + response.getMsg());
    }

    return response.getData();
    // CollectionData fields: address, amount, symbol, chain, uid, orderId, expiredTime
  }
}

Create a Payout

import com.xpaylabs.sdk.model.request.PayoutRequest;
import com.xpaylabs.sdk.model.response.PayoutData;

public PayoutData sendPayout(String uid, String amount, String receiveAddress) throws Exception {
  PayoutRequest request = PayoutRequest.builder()
      .amount(100.0)
      .symbol("USDT")
      .chain("TRON")
      .orderId("payout-" + System.currentTimeMillis())
      .uid(uid)
      .receiveAddress(receiveAddress)
      .build();

  ApiResponse<PayoutData> response = xpay.createPayout(request);
  return response.getData();
}

Query Order Status

import com.xpaylabs.sdk.model.response.OrderDetails;

public OrderDetails getStatus(String orderId) throws Exception {
  ApiResponse<OrderDetails> response = xpay.getOrderStatus(orderId);
  return response.getData();
  // OrderDetails fields: orderId, orderType, status, amount, actualAmount,
  //   transaction (chain, symbol, txid, from, to, amount, confirmedNum, ...)
}

Get Supported Symbols

import com.xpaylabs.sdk.model.response.SupportedSymbol;

public List<SupportedSymbol> getSymbols() throws Exception {
  ApiResponse<List<SupportedSymbol>> response = xpay.getSupportedSymbols();
  return response.getData();
}

// Filtered by chain and symbol
public List<SupportedSymbol> getSymbols(String chain, String symbol) throws Exception {
  ApiResponse<List<SupportedSymbol>> response = xpay.getSupportedSymbols(chain, symbol);
  return response.getData();
}

Get Merchant Balance

import com.xpaylabs.sdk.model.request.MerchantBalanceRequest;
import com.xpaylabs.sdk.model.response.MerchantBalanceData;

public MerchantBalanceData getBalance(String symbol) throws Exception {
  MerchantBalanceRequest request = MerchantBalanceRequest.builder()
      .symbol(symbol)
      .build();

  ApiResponse<MerchantBalanceData> response = xpay.getMerchantBalance(request);
  return response.getData();
  // Fields: symbol, balance, frozenBalance, totalBalance
}

Get Deposit Address for a User

import com.xpaylabs.sdk.model.request.CryptoAddressRequest;
import com.xpaylabs.sdk.model.response.CryptoAddressData;

public CryptoAddressData getDepositAddress(String uid, String chain, String symbol) throws Exception {
  CryptoAddressRequest request = CryptoAddressRequest.builder()
      .chain(chain)
      .symbol(symbol)
      .uid(uid)
      .build();

  ApiResponse<CryptoAddressData> response = xpay.getCryptoAddress(request);
  return response.getData();
  // Fields: chain, symbol, address
}

Handling Webhooks

The SDK provides built-in webhook signature verification and event parsing. Set up a controller to receive webhook callbacks:

import com.xpaylabs.sdk.model.webhook.WebhookEvent;
import com.xpaylabs.sdk.model.webhook.OrderWebhookData;
import com.xpaylabs.sdk.model.webhook.CollectWebhookData;

@RestController
public class WebhookController {

  private final XPay xpay;

  public WebhookController(XPay xpay) {
    this.xpay = xpay;
  }

  @PostMapping("/webhook")
  public ResponseEntity<String> handleWebhook(@RequestBody String body) {
    WebhookEvent event = xpay.parseWebhook(body);

    if (event == null) {
      return ResponseEntity.badRequest().body("Invalid webhook signature");
    }

    switch (event.getNotifyType()) {
      case ORDER_PENDING:
        System.out.println("Order pending: " + ((OrderWebhookData) event.getData()).getOrderId());
        break;

      case ORDER_PENDING_CONFIRMATION:
        System.out.println("Payment detected, awaiting confirmations");
        break;

      case ORDER_SUCCESS:
        OrderWebhookData orderData = (OrderWebhookData) event.getData();
        System.out.println("Order " + orderData.getOrderId() + " completed!");
        // Fulfill the order
        break;

      case ORDER_EXPIRED:
        System.out.println("Order expired");
        break;

      case ORDER_FAILED:
        OrderWebhookData failedData = (OrderWebhookData) event.getData();
        System.out.println("Order failed: " + failedData.getReason());
        break;

      case COLLECT_PENDING:
        System.out.println("Hot-to-cold sweep initiated");
        break;

      case COLLECT_SUCCESS:
        CollectWebhookData collectData = (CollectWebhookData) event.getData();
        System.out.println("Collection completed! Amount: " + collectData.getCollectAmount());
        break;

      case COLLECT_FAILED:
        CollectWebhookData failedCollect = (CollectWebhookData) event.getData();
        System.out.println("Collection failed: " + failedCollect.getReason());
        break;
    }

    return ResponseEntity.ok("Webhook received");
  }
}

Error Handling

The SDK throws XPayApiException for API errors:

import com.xpaylabs.sdk.exception.XPayApiException;

try {
  ApiResponse<PayoutData> response = xpay.createPayout(request);
} catch (XPayApiException e) {
  System.err.println("API Error: " + e.getMessage());
  System.err.println("HTTP Status: " + e.getStatusCode());
  System.err.println("Error Code: " + e.getErrorCode());
} catch (Exception e) {
  System.err.println("Unexpected error: " + e.getMessage());
}

Full Example

See the XPayExample.java class in the SDK repository for a complete example covering all API operations.

The SDK uses HMAC-SHA256 for request signing. The XPay class handles this automatically — you only need to pass the request objects and it manages the sign, timestamp, and nonce fields internally.

​Installation

​Configuration

​Core API Methods

​Create a Collection Order

​Create a Payout

​Query Order Status

​Get Supported Symbols

​Get Merchant Balance

​Get Deposit Address for a User

​Handling Webhooks

​Error Handling

​Full Example

Installation

Configuration

Core API Methods

Create a Collection Order

Create a Payout

Query Order Status

Get Supported Symbols

Get Merchant Balance

Get Deposit Address for a User

Handling Webhooks

Error Handling

Full Example