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

# Java SDK

> Call the Payaza API from your Java or Spring Boot server: collect payments, send transfers, manage accounts and verify webhooks.

`payaza-java-sdk` is the official server-side SDK for the Payaza API. Every request and response is a typed Java record, it uses the JDK's built-in `java.net.http.HttpClient`, and Jackson is its only runtime dependency.

> [!WARNING]
>
> This is a **server-side** SDK. Never ship it in an Android or desktop client, because it needs your API key. For mobile checkout, use the [Flutter](https://docs.payaza.africa/api-reference/libraries/flutter.md), [iOS](https://docs.payaza.africa/api-reference/libraries/iosswift.md) or [React Native](https://docs.payaza.africa/api-reference/libraries/reactnative.md) SDKs.

## Requirements

* Java 17 or later
* A Payaza business account with API keys. See [Authentication](https://docs.payaza.africa/guides/authentication.md).

## Installation

```xml Maven theme={null}
<dependency>
  <groupId>africa.payaza</groupId>
  <artifactId>payaza-java-sdk</artifactId>
  <version>1.0.0</version>
</dependency>
```

```groovy Gradle (Groovy) theme={null}
implementation 'africa.payaza:payaza-java-sdk:1.0.0'
```

```kotlin Gradle (Kotlin) theme={null}
implementation("africa.payaza:payaza-java-sdk:1.0.0")
```

## Get your API key

**1. Open the dashboard**

Log in at [business.payaza.africa](https://business.payaza.africa) and go to **Settings > Developers**.

**2. Generate keys**

Click **Generate Keys**. Turn on **Test Mode** for a sandbox key. Live keys are available after KYB approval.

**3. Store it as an environment variable**

```bash theme={null}
export PAYAZA_PUBLIC_KEY=your_test_public_key
export PAYAZA_WEBHOOK_SECRET=your_webhook_secret
```

## Initialize the client

```java theme={null}
import africa.payaza.sdk.Payaza;
import africa.payaza.sdk.PayazaClientOptions;
import africa.payaza.sdk.PayazaEnvironment;

Payaza payaza = new Payaza(PayazaClientOptions.builder()
    .publicKey(System.getenv("PAYAZA_PUBLIC_KEY"))
    .environment(PayazaEnvironment.TEST) // TEST while you build, LIVE when you go live
    .build());

var accounts = payaza.account().view().data();
```

Create one `Payaza` instance and reuse it. In Spring Boot, expose it as a bean:

```java theme={null}
@Configuration
public class PayazaConfig {

  @Bean
  public Payaza payaza(@Value("${payaza.public-key}") String publicKey) {
    return new Payaza(PayazaClientOptions.builder()
        .publicKey(publicKey)
        .environment(PayazaEnvironment.TEST)
        .build());
  }
}
```

### Client options

| Builder method | Type | Default | Description |
| - | - | - | - |
| `publicKey` | `String` | Required | Your raw Payaza public key, exactly as copied from the dashboard. Do not base64-encode it yourself. |
| `environment` | `PayazaEnvironment` | `TEST` | `TEST` or `LIVE`. Must match the mode of your key. Sent as the `X-TenantID` header. |
| `productId` | `String` | `"app"` | Sent as `X-ProductID` on the mobile money endpoints that need it. |
| `baseUrl` | `String` | `https://api.payaza.africa/live` | Override the API host, for example to point at a mock server in tests. |
| `timeout` | `Duration` | 30 seconds | Per-request timeout. |

> [!NOTE]
>
> The SDK base64-encodes your key and sends it as `Authorization: Payaza <encoded-key>`, and it keeps the fixed `/live` path in the base URL. The `environment` option, not the URL, decides whether you are in test or live mode.

## Collect payments

### Charge a card

```java theme={null}
import africa.payaza.sdk.resources.CardsResource;

String reference = ("ORD" + System.currentTimeMillis()).substring(0, 15); // unique, 15 characters or fewer

var result = payaza.cards().charge(new CardsResource.CardChargeRequest(
    new CardsResource.CardChargeRequest.ServicePayload(
        "Ada", "Obi", "ada@example.com", "+2348012345678",
        5000,
        reference,
        "NGN",
        "Order #1042",
        new CardsResource.CardDetails("5111111111111118", "01", "39", "100", null), // sandbox test card
        "https://yourapp.com/payments/callback")));

if (result.do3dsAuth()) {
  // The issuer wants 3-D Secure. Render result.threeDsHtml() in the customer's browser.
} else if (result.paymentCompleted()) {
  // Charged. Confirm with a webhook or getTransactionStatus before you fulfil.
}
```

Use the cards on the [test cards](https://docs.payaza.africa/guides/testcards.md) page while in test mode.

> [!WARNING]
>
> **A timeout is not a failure.** If a charge times out or your server loses the reply, the customer may already have been debited. Check the status with the same reference before you retry, and never retry with a new reference:
>
> ```java theme={null}
> var status = payaza.cards().getTransactionStatus(reference);
> System.out.println(status.data().transactionStatus());
> ```

### Virtual accounts

```java theme={null}
import africa.payaza.sdk.resources.VirtualAccountsResource;

var account = payaza.virtualAccounts().create(
    VirtualAccountsResource.CreateVirtualAccountRequest.dynamic(
        "Order 1042",      // account name
        "140",             // bank code
        "ord1042va",       // unique account reference
        "Ada", "Obi", "ada@example.com",
        "5000"));          // amount

System.out.println(account.data().accountNumber()); // show this to your customer

// Test mode only: simulate the customer's bank transfer
payaza.virtualAccounts().fundTestAccount(new VirtualAccountsResource.FundTestVirtualAccountRequest(
    account.data().accountName(),
    account.data().accountNumber(),
    "ord1042va",
    "5000",
    "NGN",
    "0123456789",
    "Ada Obi",
    "Test Bank"));
```

For reusable accounts, use `CreateVirtualAccountRequest.staticAccount(...)`, which also takes a validated BVN. See [Virtual accounts](https://docs.payaza.africa/guides/virtual-accounts.md).

### Mobile money

Mobile money, XOF and ZAR collections live under `payaza.mobileMoneyCollections()`: `processCollection()`, `processOtp()`, `getTransactionStatus()` and `fundTestAccount()`. See [Mobile money collections](https://docs.payaza.africa/guides/momo-collections.md) for the fields per country.

## Send money

```java theme={null}
import africa.payaza.sdk.resources.AccountResource;
import africa.payaza.sdk.resources.TransfersResource;
import java.util.List;

// 1. Resolve the beneficiary's name first
var enquiry = payaza.account().nameEnquiry(
    AccountResource.AccountNameEnquiryRequest.of("NGN", "000013", "9207067319"));
String accountName = enquiry.responseContent().accountName();

// 2. Send the transfer
payaza.transfers().initiate(new TransfersResource.InitiateTransferRequest(
    TransfersResource.TransactionType.NUBAN, // NGN. Use MOBILE_MONEY or a local rail for other currencies.
    new TransfersResource.InitiateTransferRequest.ServicePayload(
        100,                                             // payout amount
        Integer.parseInt(System.getenv("PAYAZA_TRANSACTION_PIN")),
        "1010000009",                                    // account reference, from account().view()
        "NGN",
        null,                                            // country, only for XOF payouts
        List.of(new TransfersResource.PayoutBeneficiary(
            100,                                         // credit amount
            "9207067319",
            accountName,
            "000013",
            "Invoice 482",                               // narration, 25 characters or fewer
            "TRF20261116001",                            // unique, at least 10 characters
            new TransfersResource.TransferSender(
                "Your Business", "08012345678", "12 Allen Avenue, Ikeja", null, null),
            null, null, null)))));

// 3. Check how it landed
var status = payaza.transfers().getStatus("TRF20261116001");
```

The sum of every credit amount must equal the payout amount, and each transaction reference must be unique. See [Transfers](https://docs.payaza.africa/guides/transfers.md) for every payout rail.

## Verify webhooks

Payaza signs each webhook with HMAC-SHA512 over the raw body and sends it in the `x-payaza-signature` header. Verify it against the **raw** body, before you parse it.

```java theme={null}
import africa.payaza.sdk.Webhooks;

@RestController
public class PayazaWebhookController {

  @PostMapping("/webhooks/payaza")
  public ResponseEntity<Void> handle(
      @RequestBody String rawBody,
      @RequestHeader("x-payaza-signature") String signature) {

    if (!Webhooks.verifySignature(rawBody, signature, System.getenv("PAYAZA_WEBHOOK_SECRET"))) {
      return ResponseEntity.status(401).build();
    }

    // Payaza can send the same event more than once. Use the transaction reference
    // as an idempotency key so you only fulfil once.
    return ResponseEntity.ok().build();
  }
}
```

Set your test and live webhook URLs under **Settings > Developers > Webhooks**. See [Webhooks](https://docs.payaza.africa/guides/webhooks.md).

## Handle errors

Every failure (an API error, a network error or a timeout) throws `PayazaException`, an unchecked exception.

```java theme={null}
import africa.payaza.sdk.PayazaException;

try {
  payaza.transfers().initiate(request);
} catch (PayazaException e) {
  System.err.println(e.getMessage());      // message from the API or the SDK
  System.err.println(e.getStatus());       // HTTP status, when the API answered
  System.err.println(e.getResponseBody()); // full response body, for logs
  throw e;
}
```

`getStatus()` is `null` for network errors and timeouts. Treat those as **unknown**, not failed, and check the transaction status before retrying. See [Errors](https://docs.payaza.africa/guides/errors.md) for common causes.

## Resources

Every resource follows the same `payaza.<resource>().<method>()` shape. Request and response types are records nested in each resource class, for example `TransfersResource.InitiateTransferRequest`.

| Resource | Methods |
| - | - |
| `account()` | `view`, `getTransactionStatus`, `getBankCodes`, `nameEnquiry` |
| `transfers()` | `initiate`, `getStatus` |
| `cards()` | `charge`, `getTransactionStatus`, `getRefundStatus` |
| `virtualAccounts()` | `create`, `getStatus`, `getTransactionStatus`, `fundTestAccount` |
| `mobileMoneyCollections()` | `processCollection`, `processOtp`, `getTransactionStatus`, `fundTestAccount` |
| `authCaptureVoid()` | `authorize`, `capture`, `voidTransaction`, `get`, `list` |
| `refunds()` | `initiate`, `history` |
| `chargebacks()` | `list`, `acceptOrReject`, `history` |
| `subAccounts()` | `create`, `get` |
| `eurAccounts()` | `requestUser`, `requestCorporate`, `listRequests`, `getRequest`, `acceptableIds`, `list` |
| `branches()` | `list` |
| `splitSettlements()` | `create`, `list`, `update`, `delete` |
| `subscriptionPlans()` | `create`, `list`, `get`, `update` |
| `subscriptions()` | `create`, `get`, `list`, `chargeNow`, `createCustomCharge`, `cancel`, `pause`, `resume`, `changePlan`, `upcomingCharges`, `chargeHistory`, `eventHistory`, `listInvoices`, `getInvoice` |

Unknown fields in Payaza's responses are ignored, so new fields added to the API do not break your build. For the fields of each endpoint, see the [API reference](https://docs.payaza.africa/api-reference/introduction).

## Build faster with AI

Connect the [Payaza MCP server](https://docs.payaza.africa/ai/mcp.md) to Claude, Cursor or VS Code so your assistant can read these docs while it writes `payaza-java-sdk` code for you.

## Source and support

> [card] [GitHub](https://github.com/78-Financials/payaza-java-sdk)
>
> Source code, changelog and issues.

> [card] [Discord](https://discord.gg/hayas4mVx)
>
> Ask the Payaza developer community.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.