> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usezentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Java SDK

> Official Zentra library for Java applications

The Zentra Java SDK provides convenient access to the Zentra API from Java applications.

The checked-in Java wrapper currently exposes transfers, payments, virtual accounts, logs, and webhook verification. For cards, tenant-enabled identity, or broader compatibility helpers, prefer another checked-in SDK or direct HTTP until the Java wrapper catches up.

<CodeGroup>
  ```xml Maven theme={null}
  <dependency>
      <groupId>io.zentra</groupId>
      <artifactId>zentra-java</artifactId>
      <version>1.0.0</version>
  </dependency>
  ```

  ```groovy Gradle theme={null}
  implementation 'io.zentra:zentra-java:1.0.0'
  ```
</CodeGroup>

## Configuration

Initialize the client with your API key and base URL:

```java theme={null}
import io.zentra.ZentraClient;
import java.time.Duration;

ZentraClient client = new ZentraClient(
    System.getenv("ZENTRA_SECRET_KEY"),
    "https://api.usezentra.com",
    Duration.ofSeconds(30)
);
```

## Resources

The checked-in Java package currently exposes:

* `client.payments`: Reviewed public charges, refunds, and saved payment tokens
* `client.transfers`: Bank transfers
* `client.virtualAccounts`: Virtual bank accounts
* `client.logs`: API request logs
* `client.webhooks`: Webhook signature verification

## Examples

### Create a Transfer

```java theme={null}
import java.util.Map;

try {
    var transfer = client.transfers.create(Map.of(
        "amount", 500000L,
        "recipient_bank_code", "058",
        "recipient_account_number", "0123456789",
        "recipient_account_name", "Vendor Settlement Account",
        "narration", "Vendor payout",
        "reference", "TRF_12345",
        "currency", "NGN"
    ));
    System.out.println("Queued: " + transfer.getReference());
} catch (ZentraException e) {
    System.err.println("Error: " + e.getMessage());
}
```

### Create Charge

```java theme={null}
import java.util.Map;

Map<String, Object> charge = client.payments().charge(
    Map.of(
        "amount_minor", 500000L, // ₦5,000.00
        "currency", "NGN",
        "email", "user@example.com",
        "reference", "ORD_12345",
        "capture_mode", "customer_action_required"
    ),
    "idem_charge_123"
);

Map<String, Object> verified = client.payments().verify((String) charge.get("reference"));
System.out.println("Status: " + verified.get("status"));
```

### Verify Webhook Signature

```java theme={null}
boolean valid = client.webhooks.verifySignature(payload, signature, webhookSecret);
if (!valid) {
    throw new IllegalArgumentException("Invalid webhook signature");
}
```

## Error Handling

The SDK throws typed exceptions for API errors:

```java theme={null}
import io.zentra.exception.ApiException;
import io.zentra.exception.AuthenticationException;
import io.zentra.exception.ZentraException;

try {
    client.payments().verify("INVALID_REF");
} catch (AuthenticationException e) {
    System.err.println("Check your API key");
} catch (ApiException e) {
    System.err.println("API error: " + e.getMessage());
} catch (ZentraException e) {
    System.err.println("Unexpected SDK error: " + e.getMessage());
}
```

## Source Code

<CardGroup cols={2}>
  <Card title="GitHub Repo" icon="github" href="https://github.com/zentra/zentra-java">
    View source code
  </Card>

  <Card title="Maven Central" icon="java" href="https://search.maven.org/artifact/io.zentra/zentra-java">
    Download package
  </Card>
</CardGroup>