Getting Started
The pawaPay Java SDK is a fully typed, reactive wrapper powered by a native core (JNI) for industrial-grade performance and security. It handles the heavy lifting of mobile money integration so you can focus on building your enterprise application.
.environment("sandbox")
KATORYMND_PAWAPAY_SDK_LICENSE_KEY via HMAC-SHA256
signature before unlocking the JNI native bytecode.
Quick Start Code
import com.katorymnd.pawapay.sdk.api.ApiClient;
import com.katorymnd.pawapay.sdk.config.Config;
public class PaymentService {
public static void main(String[] args) {
SdkConfig config = SdkConfig.builder()
.apiToken(System.getenv("PAWAPAY_SANDBOX_API_TOKEN"))
.environment("sandbox")
.apiVersion("v2")
.sslVerify(true)
.licenseKey(System.getenv("KATORYMND_PAWAPAY_SDK_LICENSE_KEY"))
.build();
ApiClient client = new ApiClient(config);
// client.initiateDeposit(...);
}
}
Installation & Core Setup
The pawapay-java-sdk package can be installed via Maven or Gradle. You must also run the specialized setup command to initialize the secure core and generate your local bytecode signature.
<dependency>
<groupId>com.katorymnd</groupId>
<artifactId>pawapay-java-sdk</artifactId>
<version>2.6.6</version>
</dependency>
# Run the secure initial setup after pulling the dependency
java -com.katorymnd.pawapay.sdk.utils.vm.SetupSDK
SDK Dependencies
The following core dependencies are utilized in our stack:
Auto-configuration included for handling incoming payment webhooks and reactive routing.
Pre-compiled encrypted transaction logic (
libpawapay_core) to secure execution and
memory.
Native reactive support for high-performance concurrent pawaPay REST queries.
Recommended Project Structure
After executing the setup JAR, align your project as follows:
├── pom.xml / build.gradle # Dependency management
├── src/
│ └── main/
│ ├── java/com/app/ # Your Spring application logic
│ └── resources/ # JNI bindings & application.yml
├── .env # Contains your Domain & Master License
└── errorlogs.txt # Surgical traceback logs
License Activation & Domain Binding
Activation is a one-time surgical handshake that unlocks production API access and enterprise features. The pawapay-sdk utilizes a Dual-Locking system to ensure license integrity.
Step-by-Step Validation
LICENSE_KEY generated by the Katorymnd master
admin.
.env or application.yml file. Do not use dummy fallbacks.
The environment must strictly match the signature.
mvn clean compile exec:java -Dexec.mainClass="com.katorymnd.pawapay.sdk.utils.vm.SetupSDK"
to
create the .pawapay-imprint file alongside your
server's
randomized instruction sets.
ApiClient, the native validator splits the payload
via JNI, verifies the HMAC signature, and checks the domain before unlocking endpoints.
Licensing Error Codes
Security Lock: The
PAWAPAY_SDK_LICENSE_DOMAIN in your environment
does not match the signed payload inside the license key.
Tampering Detected: The key was modified or generated with an invalid master secret. Core logic execution halted.
Environment Configuration
The pawapay-java-sdk can ingest configuration natively via application.yml, .env (using dotenv-java), or direct Environment Variables.
Required Variables (.env)
PAWAPAY_SANDBOX_API_TOKEN=your_sandbox_api_token_here
PAWAPAY_PRODUCTION_API_TOKEN=your_production_api_token_here
KATORYMND_PAWAPAY_SDK_LICENSE_KEY=your_key_here
PAWAPAY_SDK_LICENSE_DOMAIN=your_domain_here
PAWAPAY_SDK_LICENSE_SECRET=your_key_here
Builder Configuration Elements
Sourced from your system environment via
System.getenv() or Spring's @Value annotation.
Must perfectly match the domain the license was generated for by the Admin generator.
Pass
"sandbox" or
"production" to instruct the SDK on which REST
endpoints to target.
Troubleshooting & Diagnostics
If your application encounters a fatal error, check the surgical errorlogs.txt generated in your project root, or your
configured Logback/SLF4J output. It will capture complete StackTraces.
1. Common System Errors
Cause: The JNI native core (
libpawapay_core.so/.dll) could not be loaded into
the JVM.Fix: Ensure the setup jar was run and the library is in the
java.library.path.
Cause: Missing environment variables during Spring Boot auto-configuration.
Fix: Verify your
application.yml properties map perfectly to the
SDK configuration prefix.
2. API Rejections
These errors occur during the initiateDeposit() phase.
Message: Customer message length should not be greater than 22.
Fix: Keep your statement description concise.
Message: The phone number format is invalid.
Fix: Ensure the MSISDN follows the correct format (e.g., 25678...).
Support & Technical Assistance
If you encounter challenges during the integration, our engineering team is available to assist you. To ensure the fastest resolution, please follow the diagnostic steps below.
For integration logic, private server debugging, or licensing help.
→ Email Engineering📋 Ticket Checklist
When requesting technical support, please include the following data:
pom.xml.• Environment: Sandbox or Production.
• Correlation ID: The
depositId or
transactionId from your logs.• Error Logs: Snippet from your StackTrace.
• Java Version: Output of
java -version.
☕ "Empowering African fintech through surgical Java engineering."