Multi-Language Integration Examples

import javax.crypto.Cipher;
import javax.crypto.Mac;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.security.SecureRandom;
import java.util.Arrays;
import java.util.Base64;
import java.util.HexFormat;
import java.util.UUID;

public class BucksBoxPartnerClient {

    private final String baseUrl;
    private final String clientId;
    private final byte[] aesKey; // 32 bytes
    private final String checksumSecret;
    private final HttpClient http = HttpClient.newHttpClient();

    public BucksBoxPartnerClient(String baseUrl, String clientId, String aesKeyRaw, String checksumSecret) {
        this.baseUrl = baseUrl;
        this.clientId = clientId;
        this.checksumSecret = checksumSecret;
        // SaltAESKey: 64-char hex or 44-char base64 -> 32 raw bytes
        this.aesKey = aesKeyRaw.length() == 64
            ? HexFormat.of().parseHex(aesKeyRaw)
            : Base64.getDecoder().decode(aesKeyRaw);
    }

    public String call(String path, String plaintextJsonBody) throws Exception {
        long timestamp = System.currentTimeMillis() / 1000;
        byte[] iv = new byte[12];
        new SecureRandom().nextBytes(iv);
        String aad = clientId + "." + timestamp;

        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        cipher.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(aesKey, "AES"), new GCMParameterSpec(128, iv));
        cipher.updateAAD(aad.getBytes(StandardCharsets.UTF_8));

        byte[] encrypted = cipher.doFinal(plaintextJsonBody.getBytes(StandardCharsets.UTF_8));
        // Java appends the 16-byte GCM tag to the end of the ciphertext output
        int tagLen = 16;
        byte[] ciphertext = Arrays.copyOfRange(encrypted, 0, encrypted.length - tagLen);
        byte[] tag = Arrays.copyOfRange(encrypted, encrypted.length - tagLen, encrypted.length);

        // Build the envelope by hand — must byte-match {"payload":"..."} exactly
        String envelope = "{\"payload\":\"" + Base64.getEncoder().encodeToString(ciphertext) + "\"}";
        String canonical = timestamp + "." + clientId + "." + envelope;
        String checksum = hmacSha256Hex(canonical, checksumSecret);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/process" + path))
            .header("Content-Type", "application/json")
            .header("X-Client-Id", clientId)
            .header("X-Timestamp", String.valueOf(timestamp))
            .header("X-IV", Base64.getEncoder().encodeToString(iv))
            .header("X-Tag", Base64.getEncoder().encodeToString(tag))
            .header("X-Checksum", checksum)
            .header("X-Request-Id", UUID.randomUUID().toString())
            .POST(HttpRequest.BodyPublishers.ofString(envelope))
            .build();

        HttpResponse<String> response = http.send(request, HttpResponse.BodyHandlers.ofString());
        return decryptResponse(response);
    }

    private String decryptResponse(HttpResponse<String> response) throws Exception {
        String bodyText = response.body();
        String payload = extractPayload(bodyText); // swap for Jackson/Gson in real code
        String respIv = response.headers().firstValue("X-IV").orElse(null);
        String respTag = response.headers().firstValue("X-Tag").orElse(null);
        String respTimestamp = response.headers().firstValue("X-Timestamp").orElse(null);

        if (payload == null || respIv == null || respTag == null) {
            return bodyText; // unencrypted error object
        }

        String aad = clientId + "." + respTimestamp;
        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        cipher.init(Cipher.DECRYPT_MODE, new SecretKeySpec(aesKey, "AES"),
            new GCMParameterSpec(128, Base64.getDecoder().decode(respIv)));
        cipher.updateAAD(aad.getBytes(StandardCharsets.UTF_8));

        byte[] ciphertext = Base64.getDecoder().decode(payload);
        byte[] tag = Base64.getDecoder().decode(respTag);
        byte[] combined = new byte[ciphertext.length + tag.length];
        System.arraycopy(ciphertext, 0, combined, 0, ciphertext.length);
        System.arraycopy(tag, 0, combined, ciphertext.length, tag.length);

        return new String(cipher.doFinal(combined), StandardCharsets.UTF_8);
    }

    private static String hmacSha256Hex(String data, String secret) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        return HexFormat.of().formatHex(mac.doFinal(data.getBytes(StandardCharsets.UTF_8)));
    }

    // Minimal {"payload":"..."} extractor to avoid adding a JSON-library dependency to this
    // example — use Jackson's ObjectMapper or Gson in production code.
    private static String extractPayload(String json) {
        int i = json.indexOf("\"payload\"");
        if (i < 0) return null;
        int start = json.indexOf('"', json.indexOf(':', i) + 1) + 1;
        int end = json.indexOf('"', start);
        return json.substring(start, end);
    }

    public static void main(String[] args) throws Exception {
        BucksBoxPartnerClient client = new BucksBoxPartnerClient(
            "https://api.bucksbox.in/gateway",
            System.getenv("BUCKSBOX_CLIENT_ID"),
            System.getenv("BUCKSBOX_AES_KEY"),
            System.getenv("BUCKSBOX_CHECKSUM_SECRET")
        );

        // Example: AEPS balance enquiry
        String body = """
            {"merchantId":"MERCHANT123","AadharNo":"999999999999","TxnAmount":0,
             "Latitude":"19.0760","Longitude":"72.8777","CustomerName":"Ramesh Kumar",
             "PidData":"<PidData XML from the RD service>","BankName":"918152"}""";

        System.out.println(client.call("/aeps/balance", body));
    }
}