The Problem

Individual taxpayers in Kenya must file a “NIL” return each tax period, even when they have no taxable income. Manually logging into the Kenya Revenue Authority (KRA) portal, generating an OAuth token, and posting the required JSON payload is repetitive and error‑prone, especially for SaaS platforms that need to automate the step for many users.

What This Does

KRA_App_Backend is a Spring Boot service that abstracts the KRA NIL‑return workflow behind a REST API. The core files are:

  • src/main/java/com/starnoh/kraAppBackend/KraAppBackendApplication.java – Spring Boot entry point.
  • src/main/java/com/starnoh/kraAppBackend/controller/FileNillReturnController.java – Exposes /file-nil (POST) to external clients.
  • src/main/java/com/starnoh/kraAppBackend/service/FileNillReturnsService.java – Builds the NIL‑return JSON and delegates to KraAuthService.
  • src/main/java/com/starnoh/kraAppBackend/service/KraAuthService.java – Handles consumer‑key/secret encoding, token request to KRA, in‑memory caching, and expiration checks.
  • src/main/java/com/starnoh/kraAppBackend/config/KraConfig.java – Loads kra.consumer.key and kra.consumer.secret from application.properties.

The service reads the credentials from src/main/resources/application.properties, requests an access token from KRA, caches it, and then forwards the NIL‑return payload. Errors from the external API are wrapped and returned as HTTP 4xx/5xx responses.

How It Is Wired

  1. Application start – KraAppBackendApplication.main() boots Spring, scans com.starnoh.kraAppBackend and registers beans.
  2. HTTP request – A client POSTs JSON to /file-nil. Spring routes it to FileNillReturnController.fileNillReturn(@RequestBody FileReturnsDto dto).
  3. Service call – The controller injects FileNillReturnsService and calls processNillReturn(dto).
  4. Token acquisition – FileNillReturnsService calls kraAuthService.getAccessToken(). * KraAuthService checks an in‑memory accessToken field. If missing or expired, it builds a Base64‑encoded Authorization: Basic … header using KraConfig values, sends a POST via OkHttpClient to the KRA token endpoint, parses the JSON response, stores the token and its expiry.
  5. NIL filing – With a valid token, FileNillReturnsService creates the request body (using org.json), sets Authorization: Bearer <token> on a RestTemplate, and POSTs to the KRA filing endpoint.
  6. Response handling – The external response is returned to the controller, which maps it to the HTTP response sent back to the caller.

The only external side‑effects are network calls to KRA; there is no database or file I/O. The token cache is a simple field, so the blast radius of a change is limited to KraAuthService and any code that depends on its getAccessToken() contract.

How To Use It

# Clone the repo (exact URL required)
git clone https://github.com/moses-y/KRA_App_Backend
cd KRA_App_Backend

# Add KRA credentials (do NOT commit this file)
cat > src/main/resources/application.properties <<EOF
kra.consumer.key=YOUR_CONSUMER_KEY
kra.consumer.secret=YOUR_CONSUMER_SECRET
# optional: server.port=8080
EOF

# Build with the Maven wrapper
./mvnw clean package

# Run the Spring Boot app
./mvnw spring-boot:run
# or java -jar target/kra-app-backend-0.0.1-SNAPSHOT.jar

The service will listen on port 8080 (default). Submit a NIL return with:

curl -X POST http://localhost:8080/file-nil \
  -H "Content-Type: application/json" \
  -d '{"tin":"A123456789","taxPeriod":"2023","amount":0}'

Replace the JSON fields with the taxpayer’s TIN and period as required.

Real‑World Use

A payroll SaaS can embed this service as a micro‑service. When a payroll run finishes with zero taxable income, the SaaS calls the /file-nil endpoint on behalf of the employee, letting the backend handle token renewal and KRA communication without exposing the consumer key to the front‑end.

Code Health & Issues

  • High – Missing LICENSE – No file at repository root defines reuse rights. Without a license the default is “all rights reserved,” preventing legal reuse.
  • Medium – No CI/CD pipeline – No .github/, Jenkinsfile, or similar; builds and tests are not gated automatically.
  • Low – No lockfile – Maven’s pom.xml declares dependencies but there is no pom.xml.lock or similar, which can lead to non‑reproducible builds across environments.
  • Info – Tests present – One test class KraAppBackendApplicationTests.java exists, but coverage is minimal.
  • Info – No Dockerfile – Containerization must be added manually if deployment requires it.

The Bottom Line

The repository delivers a focused Spring Boot wrapper around the KRA NIL‑return API, with clear separation between token management and filing logic. It builds and runs with the Maven wrapper and requires only two credential properties. However, the lack of a license, CI automation, and a lockfile limits safe reuse and continuous delivery. It is suitable for teams comfortable adding their own CI pipeline and licensing, and who need a quick Java‑based integration point to KRA’s NIL‑return service.