kinsleykajiva/ecocash-with-java

A type-safe, fluent Java SDK for the Zimbabwe Ecocash Open API. Supports payment initiation, transaction status polling, and refunds for both sandbox and live environments. # Ecocash Java SDK A type-safe, fluent Java client for the Ecocash Open API. Supports payment initiation, transaction status polling, and refunds against both sandbox and live environments. > Requires **Java 17+** and `org.json:json:20240303`. --- ## Table of Contents - Installation - Quick Start - Building a Client - Initiating a Payment - Polling for Transaction Status - Default (Interval) - Backoff Strategy - Simple Strategy - Single Lookup (No Polling) - Refunding a Payment - Error Handling - Going Live - Class Reference - Package Structure --- ## Installation Add the dependency to your build file. **Maven** ```xml io.github.kinsleykajiva ecocash 0.1.3 ``` **Gradle** ```groovy implementation 'io.github.kinsleykajiva:ecocash:0.1.3' ``` ### Building from Source The project uses a Maven multi-module structure. You can build and install the SDK to your local repository: ```bash mvn clean install ``` --- ## Quick Start ```java try (EcocashClient client = EcocashClient.builder() .apiKey("your-api-key") .merchantCode("your-merchant-code") .build()) { // 1. Initiate a payment — sends a prompt to the customer's handset InitPaymentResponse payment = client.initPayment("26377800000", 20.05, "bread"); // 2. Poll until SUCCESS or timeout LookupTransactionResponse result = client.pollTransaction(payment); if (result.isPaymentSuccess()) { System.out.println("Confirmed: " + result.getEcocashReference()); } } ``` --- ## Building a Client Use the fluent builder. Only `apiKey` and `merchantCode` are required. ```java EcocashClient client = EcocashClient.builder() .apiKey("your-api-key") .merchantCode("your-merchant-code") .build(); ``` `EcocashClient` implements `AutoCloseable`, so the recommended pattern is try-with-resources: ```java try (EcocashClient client = EcocashClient.builder() .apiKey("your-api-key") .merchantCode("your-merchant-code") .build()) { // use client } ``` ### Builder Options | Method | Default | Description | |---|---|---| | …