Payment Service is the Digital Bank Java platform foundation for future payment rail workflows. This repository contains a deployable Spring Boot service, an authenticated internal payment instruction lifecycle API, and durable publication of governed payment instruction state events; payment rail business logic and public gateway routes remain intentionally out of scope.
- Java 21 Spring Boot service named
payment-service. - Spring Cloud Config Client integration for externalized runtime configuration.
- Actuator health, liveness, and readiness probes.
- Explicit internal OpenAPI metadata at
/v3/api-docs. - Non-root container image and hardened Helm deployment.
- Default SIT service port
8085. - Internal payment instruction lifecycle endpoints at
/internal/v1/payment-instructions. - PostgreSQL-backed transactional outbox and bounded at-least-once Kafka publication for
payment.instruction.state.v1.
This service will later own payment workflow coordination and payment rail integration boundaries. It does not currently own customer data, account balances, ledger postings, transfer saga orchestration, or provider credentials. Its Kafka producer publishes only payment instruction state facts; the governed AsyncAPI contract is maintained in the organization .github repository.
Payment rail integrations must remain behind outbound ports and adapters when that work is approved and tracked. Do not add provider credentials or payment data to this repository.
The application exposes an internal HTTP adapter over the transport-neutral payment instruction lifecycle boundary. A payment instruction is accepted as PENDING and can move once to either COMPLETED or FAILED; repeating the same create request returns the original instruction as an idempotent replay, repeating the same terminal outcome is idempotent, and changing a terminal outcome is rejected.
The application boundary also normalizes the idempotency key, amount, currency, and description before comparing retries. An equivalent retry returns the original instruction identity, while reuse of the same idempotency key with a different business request is rejected. Correlation IDs are retained for tracing and are deliberately excluded from the idempotency comparison, so a retried request may have a new trace context.
Payment instructions are stored in PostgreSQL through a Flyway-managed schema. Idempotency keys are unique in the database, so equivalent retries converge across replicas and restarts; the canonical request fields are compared before a replay is returned, and a changed payload returns 409 Conflict. Creation and real terminal transitions insert one durable outbox record in the same database transaction. The publisher sends the stored payload and governed headers with a bounded leased retry loop, preserving event identity across retries. Payment-provider adapters and transaction saga orchestration remain out of scope.
All payment instruction endpoints require a bearer JWT with the payment.internal scope. Missing or invalid authentication returns 401 Unauthorized; an authenticated caller without that scope returns 403 Forbidden. Both responses use application/problem+json. Health, service metadata, and the generated OpenAPI document remain public.
POST /internal/v1/payment-instructionscreates a payment instruction and returns201 CreatedwithLocation: /internal/v1/payment-instructions/{instructionId}.- Repeating an equivalent create request returns
200 OKwithIdempotent-Replay: true. GET /internal/v1/payment-instructions/{instructionId}retrieves the stable payment instruction representation, or returns404 Not Foundwhen the instruction does not exist.POST /internal/v1/payment-instructions/{instructionId}/completioncompletes a payment instruction.POST /internal/v1/payment-instructions/{instructionId}/failurefails a payment instruction with a required JSON body containingreason.
Error responses use application/problem+json for boundary validation failures, including malformed instruction ids, unknown instruction ids, conflicting create-time idempotency keys, invalid lifecycle transitions, and security failures. The generated internal contract is available at /v3/api-docs.
Config Server supplies the effective runtime configuration. The service repository contains only the Config Client bootstrap:
| Variable | Purpose | Default |
|---|---|---|
CONFIG_SERVER_URL |
Config Server base URL | http://localhost:8888 |
SPRING_PROFILES_ACTIVE |
Runtime environment profile | Spring default profile |
SERVER_PORT |
HTTP listen port | 8085 |
spring.datasource.url |
PostgreSQL JDBC URL | Required from Config Server or Helm deployment values |
spring.datasource.username |
PostgreSQL username | Required from Config Server or the referenced Kubernetes Secret |
spring.datasource.password |
PostgreSQL password | Required from Config Server or the referenced Kubernetes Secret |
spring.security.oauth2.resourceserver.jwt.issuer-uri |
OIDC issuer URI | Optional when using the SIT HMAC contract |
spring.security.oauth2.resourceserver.jwt.jwk-set-uri |
JWT JWK set URI | Optional when issuer discovery is available |
auth.jwt.secret |
Base64 HMAC secret shared with Auth Service in SIT | none |
auth.jwt.issuer |
HMAC token issuer used in SIT | none |
PAYMENT_EVENTS_TOPIC |
Kafka topic for payment instruction state events | payment.instruction.state.v1 |
PAYMENT_EVENTS_BATCH_SIZE |
Maximum events claimed per publisher poll | 25 |
PAYMENT_EVENTS_MAX_ATTEMPTS |
Maximum broker failure attempts before durable publication failure | 5 |
PAYMENT_EVENTS_RETRY_BACKOFF |
Delay before retrying a failed publication | PT5S |
PAYMENT_EVENTS_LEASE |
Claim lease for an in-flight publication batch | PT30S |
PAYMENT_EVENTS_SEND_TIMEOUT |
Maximum wait for one Kafka send | PT5S |
PAYMENT_EVENTS_POLL_DELAY_MS |
Publisher poll delay in milliseconds | 1000 |
The application fallback port is 8085, and the Helm chart sets SERVER_PORT from service.port so the process, probes, and Service remain aligned even before a service-specific Config Repo entry is added. The SIT chart injects the payment_service JDBC URL and reads PostgreSQL credentials from the existing postgres Secret (POSTGRES_USER and POSTGRES_PASSWORD). Credentials remain outside Git.
When spring.security.oauth2.resourceserver.jwt.issuer-uri is configured, Payment Service uses OIDC discovery or the explicit JWK set. In local SIT, it instead uses auth.jwt.secret and auth.jwt.issuer to validate the shared Auth Service HMAC token. HMAC mode requires a base64 secret decoding to at least 32 bytes; JWK material alone is not treated as sufficient trust configuration.
The formal environments are sit, uat, and prod. sit runs on local Docker Desktop Kubernetes; uat and prod are future AWS environments. local is not an active environment or Spring profile. Workstation debugging uses the sit profile with temporary overrides against forwarded SIT dependencies.
- Java 21.
- Network access to Maven Central for the initial dependency download.
- Docker Desktop for image builds.
- Helm 4 and Docker Desktop Kubernetes for local SIT deployment.
- A healthy Config Server for normal application startup.
The Maven Wrapper is included, so a global Maven installation is not required.
java -version
./mvnw --version
docker version
helm version --short
kubectl config current-contextRun the unit-test phase:
./mvnw --batch-mode --no-transfer-progress testRun integration tests and package verification:
./mvnw --batch-mode --no-transfer-progress verify -DskipUnitTests=trueSocket-level integration tests disable Config Client, start PostgreSQL with Testcontainers, and validate health, OpenAPI metadata, authenticated payment instruction HTTP behavior, duplicate/replay/conflict handling, and concurrent retries using a random application port. Focused controller tests use in-process MockMvc to cover request binding and Problem Details mapping.
Build the image:
docker build -t digital-bank-java/payment-service:0.0.2 .Run it against a reachable Config Server:
docker run --rm \
--name digital-bank-payment-service \
--publish 8085:8085 \
--env CONFIG_SERVER_URL=http://host.docker.internal:8888 \
--env SPRING_PROFILES_ACTIVE=sit \
digital-bank-java/payment-service:0.0.2The image runs as numeric non-root user and group 10001:10001 and uses /tmp for writable temporary files.
The Helm chart deploys into the digital-bank-sit namespace and expects Config Server to be available at http://config-server:8888.
helm lint helm --strict --values helm/values-sit.yaml
helm template payment-service helm \
--namespace digital-bank-sit \
--values helm/values-sit.yaml \
--set image.tag="0.0.2" \
| kubectl apply --dry-run=client -f -
helm upgrade --install payment-service helm \
--namespace digital-bank-sit \
--create-namespace \
--values helm/values-sit.yaml \
--wait \
--timeout 5mCheck the rollout and service health:
kubectl rollout status deployment/payment-service \
--namespace digital-bank-sit --timeout=180s
kubectl port-forward service/payment-service 18085:8085 \
--namespace digital-bank-sitIn another terminal:
curl --fail http://localhost:18085/actuator/health
curl --fail http://localhost:18085/v3/api-docs
curl --fail -X POST http://localhost:18085/internal/v1/payment-instructions \
-H "Authorization: Bearer $PAYMENT_INTERNAL_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"idempotencyKey":"payment-001","correlationId":"trace-001","amount":25.00,"currency":"USD","description":"Utility bill payment"}'Normal platform access should later flow through the API Gateway. The current HTTP surface is internal-only; payment-provider integrations and external routing are still out of scope for this repository.
The GitHub Actions workflow runs Maven verification and Helm validation. A container job then builds the image, verifies the non-root user, starts disposable PostgreSQL and Config Server fixtures, and smoke-tests health. Third-party actions are pinned to immutable commit SHAs.
Use the organization workstation debugging procedure. Confirm SIT dependencies first, temporarily scale down the Kubernetes payment deployment, use the sit profile, and provide temporary Config Server overrides through environment variables. Restore the deployment after debugging.
Use a dedicated branch and pull request; do not commit directly to main. Before opening a PR:
git status
./mvnw verify
git diff --checkAll changes require review by the CODEOWNERS maintainer. Never commit credentials, tokens, customer information, payment data, or production endpoints.
The service emits one-line ECS JSON console events and propagates the bounded
X-Correlation-ID boundary defined in the organization structured logging and redaction contract. Request bodies, credentials, tokens, payment data, and customer data are not logged.