Skip to main content
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.
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, iOS or React Native SDKs.

Requirements

  • Java 17 or later
  • A Payaza business account with API keys. See Authentication.

Installation

Get your API key

1

Open the dashboard

Log in at 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

Initialize the client

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

Client options

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

Use the cards on the test cards page while in test mode.
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:

Virtual accounts

For reusable accounts, use CreateVirtualAccountRequest.staticAccount(...), which also takes a validated BVN. See Virtual accounts.

Mobile money

Mobile money, XOF and ZAR collections live under payaza.mobileMoneyCollections(): processCollection(), processOtp(), getTransactionStatus() and fundTestAccount(). See Mobile money collections for the fields per country.

Send money

The sum of every credit amount must equal the payout amount, and each transaction reference must be unique. See Transfers 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.
Set your test and live webhook URLs under Settings > Developers > Webhooks. See Webhooks.

Handle errors

Every failure (an API error, a network error or a timeout) throws PayazaException, an unchecked exception.
getStatus() is null for network errors and timeouts. Treat those as unknown, not failed, and check the transaction status before retrying. See Errors 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. 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.

Build faster with AI

Connect the Payaza MCP server 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

GitHub

Source code, changelog and issues.

Discord

Ask the Payaza developer community.