Backend – Spring Boot microservice
Vouchers
Goal
Build a flexible and secure voucher engine able to handle different voucher types (gift, employee, supporter, etc.) with a full lifecycle (creation, sharing, partial and full consumption, blocking).
Result / Impact
An extensible voucher platform used by Crédit Mutuel du Sénégal that supports multiple voucher types, integrates cleanly in the banking ecosystem and provides advanced security and documentation for partner applications.
Key technologies
Spring Boot, Spring Security, JWT, Spring Data JPA, MySQL, MapStruct, Lombok, iText, Spring Actuator, ReDoc, Swagger UI, Logback/Logstash.
Project description
Vouchers is a voucher management application built with Spring Boot. It manages the full lifecycle of vouchers: creation, configuration, sharing and consumption for different use cases such as gifts, employee benefits, marketing campaigns or supporters.
The architecture is based on a Strategy pattern to handle multiple voucher types, rich business rules (MCC, expiration date, blocking, sharing…) and an advanced security layer: user authentication with JWT + server sessions, application authentication via HMAC with anti-replay, rate limiting and full audit of incoming requests.
The solution is designed to integrate easily into an existing banking system, with full API documentation (OpenAPI, Swagger UI, ReDoc) and dedicated runtime profiles for development, pre-production and production.
Client
Crédit Mutuel du Sénégal
Role
Designed the architecture, implemented backend services, secured the API, implemented bootstrap mode, integrated documentation and configured logging and runtime profiles.
Technologies
Spring Boot, Spring Security, Spring Data JPA, JWT, Spring Mail, Spring Actuator, MySQL, MapStruct, Lombok, Maven, iText, Logback, Logstash, OpenAPI/Swagger UI, ReDoc.
Results / Impact
- Extensible architecture that allows new voucher types to be added without impacting existing ones (Strategy pattern).
- Strong security posture combining JWT + server sessions + HMAC-based App Auth + anti-replay + rate limiting.
- Improved integration experience for client teams thanks to rich documentation (ReDoc, Swagger UI, OpenAPI, Spring REST Docs).
- Easier monitoring and maintenance thanks to Actuator, Logback and Logstash.
Features & responsibilities
Voucher management
- Creation and configuration of different voucher types.
- Full lifecycle management: creation, partial consumption and full consumption.
- Blocking vouchers in case of fraud or error.
- Sharing vouchers between users.
- Filtering vouchers by status.
Configuration management
- Configuration of voucher types.
- Management of MCC codes (merchant category codes).
- Options for vouchers with or without credit (dedicated business rules).
Supported voucher types
- Gift
- Employee
- Fayalma
- Supporter
Architecture and extensibility
- Strategy pattern to switch between voucher types.
- Strategy service based on a (type → implementation).
- Controller delegates to strategies (new types can be added without impacting existing ones).
Voucher creation (details)
- Amount configuration.
- Configurable expiration date.
- Type (gift, employee, supporter, etc.).
- Sharing options (shareable or not).
- Restrictions by merchant category (MCC).
Voucher consumption (details)
- Voucher validation before consumption.
- Restriction checks: merchant category, expiration date, status, etc.
- Processing of partial or full consumption.
- Voucher status update.
Voucher sharing (details)
- Sharing between users for vouchers configured as shareable.
- Generation of a unique end-to-end identifier.
- Ownership and voucher status validation before sharing.
User security (JWT + server sessions)
- User authentication via JWT (Bearer).
- Server-side sessions with constraints and revocation.
- Secure refresh token rotation with reuse detection.
- Optional binding to client subnet (IP) and User-Agent family (context).
- Idle and absolute session timeouts.
-
Controlled update of
lastSeen(at most once per minute). -
Endpoints:
/auth/login,/auth/refresh,/auth/logout. -
X-Forwarded-Forhandling behind a proxy. -
Concurrent sessions limit, configurable per role
(e.g.
ROLE_USER,ROLE_ADMIN). - Dedicated configuration properties (JWT, timeouts, refresh TTL, IP/UA constraints).
Application security (App Auth HMAC + Anti-replay) for client apps
-
Required headers:
X-Client-Id,X-Client-Secret,X-Nonce(unique),X-Timestamp,X-Signature. -
HMAC-SHA256 signature over
METHOD|PATH|TIMESTAMP|NONCE|BODY. - Anti-replay: time window, one-time nonce, control of the raw body.
- Standardized error handling (400 / 401 / 403 / 429).
- Rate limiting (429 when the quota is reached).
Client application management
- Enable/disable application-level authentication.
- IP allowlist per application (CIDR).
- Secret rotation (up to 2 valid secrets, grace period).
-
Audit log:
clientId, IP, endpoint, rate-limit status, access decision.
Bootstrap mode (one-time setup)
- Environment/system variables to enable and secure bootstrap mode.
- Dedicated endpoints: status, super admin creation, app creation, bootstrap deactivation.
- Optional ability to bypass anti-replay according to configuration.
Embedded API documentation
- ReDoc (standalone page
redoc.html). - Swagger UI (
/swagger-ui). - OpenAPI specifications available as JSON and YAML.
- Spring REST Docs (HTML documentation pages).
