PayCow
Java SDK

Installation

Extract the archive and install the package into your local Maven repository.

cd paycow-java-sdk
mvn clean install

Add the installed artifact to your application.

<dependency>
  <groupId>net.paycow</groupId>
  <artifactId>paycow-java-sdk</artifactId>
  <version>1.0.0</version>
</dependency>

Store the API key and secret in server-side environment variables or your secrets manager.

Create a payment

createPayment sends the exact request fields accepted by POST /api/payment/create. Payment amounts use BigDecimal.

import java.math.BigDecimal;
import net.paycow.sdk.CreatePaymentRequest;
import net.paycow.sdk.PayCowClient;
import net.paycow.sdk.PaymentSession;

PayCowClient paycow = new PayCowClient(
    System.getenv("PAYCOW_API_KEY"),
    System.getenv("PAYCOW_API_SECRET")
);

CreatePaymentRequest request = CreatePaymentRequest.builder()
    .userId("player-2048")
    .amount(new BigDecimal("50.00"))
    .network("TRC20")
    .addressSerialNo("WAL-1002")
    .idempotencyKey("topup-2048-001")
    .build();

PaymentSession payment = paycow.createPayment(request);

System.out.println(payment.sessionId());
System.out.println(payment.paymentUrl());
System.out.println(payment.payableAmount());
System.out.println(payment.depositAddress());

Retrieve payment status

The authenticated status method maps the backend response to PaymentStatus.

import net.paycow.sdk.PaymentStatus;

PaymentStatus payment = paycow.getPaymentStatus("66ce30d74c0c51a48f2d2903");

if (payment.isPaid()) {
    creditBalanceOnce(payment.userId(), payment.paymentReference());
}

if (payment.isConfirming()) {
    System.out.println(payment.confirmations());
}

PaymentStatus exposes the session ID, merchant reference, customer ID, requested and payable amounts, received amount, network, destination address, status, confirmations, transaction hash, and timestamps returned by the API.

Verify webhooks

Pass the unchanged request body and the two PayCow delivery headers to WebhookVerifier.

import com.fasterxml.jackson.databind.JsonNode;
import net.paycow.sdk.WebhookVerifier;

String rawBody = requestBody;
String timestamp = request.getHeader("PayCow-Timestamp");
String signature = request.getHeader("PayCow-Signature");

JsonNode event = WebhookVerifier.verify(
    rawBody,
    timestamp,
    signature,
    System.getenv("PAYCOW_WEBHOOK_SECRET")
);

if (event.get("type").asText().equals("payment.paid")) {
    JsonNode data = event.get("data");
    creditBalanceOnce(
        data.get("userId").asText(),
        data.get("paymentReference").asText()
    );
}

The verifier accepts the backend signature format v1=<64 hexadecimal characters>, computes HMAC-SHA256 over timestamp.rawBody, performs a constant-time comparison, and applies the 300-second freshness window.

Error handling

Non-successful API responses raise PayCowException. The exception keeps the HTTP status and raw response body for controlled logging and diagnostics.

import net.paycow.sdk.PayCowException;

try {
    PaymentStatus payment = paycow.getPaymentStatus(sessionId);
} catch (PayCowException error) {
    System.err.println(error.getStatusCode());
    System.err.println(error.getResponseBody());
    throw error;
}

API contract