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.
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
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
Virtual accounts
CreateVirtualAccountRequest.staticAccount(...), which also takes a validated BVN. See Virtual accounts.
Mobile money
Mobile money, XOF and ZAR collections live underpayaza.mobileMoneyCollections(): processCollection(), processOtp(), getTransactionStatus() and fundTestAccount(). See Mobile money collections for the fields per country.
Send money
Verify webhooks
Payaza signs each webhook with HMAC-SHA512 over the raw body and sends it in thex-payaza-signature header. Verify it against the raw body, before you parse it.
Handle errors
Every failure (an API error, a network error or a timeout) throwsPayazaException, 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 samepayaza.<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 writespayaza-java-sdk code for you.
Source and support
GitHub
Source code, changelog and issues.
Discord
Ask the Payaza developer community.