Skip to content

Digital Wallet System

This article describes building a Digital Wallet System, from system design to releasing a working application.

Status: work in progress | State: an early draft | Last updated: 12 Mar 2024

This article consists of two parts: system design and technical implementation details.

Table of Contents

—

System Design

Non-technical Requirements

Business requirements

  • Simple user registration and authentication process.
  • Account and wallet management.
  • Ability to top-up and wallet-to-wallet transfers.
  • Support multiple currencies and conversion rates.

Regulatory and compliance requirements

  • Audit trails for transactions and administrative actions.

Operational requirements

  • Service monitoring and alerting.
  • Support for business intelligence and reporting.
  • Easy to update and maintain without significant downtime.

Scalability and reliability requirements

  • Ability to handle growing traffic.
  • High availability and disaster recovery plans.

Technical Requirments

API Gateway

  • A single entry point for all client requests that route to appropriate microservices.

Microservices

  • Small, autonomous services.
  • Use of Domain-Driven-Design (DDD) to define bounded contexts for each microservice.
  • Database per service pattern.

Data Management

  • Distributed transaction handling.
  • Observability, monitoring, and logging.

Containerization

  • Containerization of services using Docker.
  • Container orchestration with Docker Compose.

Technical Implementation Details

This section explains the technical implementation details of the Digital Wallet System using Java and Spring Boot.

In the first iteration, instead of creating multiple Spring Boot projects, we will focus on one with all logical components inside.

Components

The initial version consists of minimal required components:

  • Account Management.
  • Wallet Management.
  • Transaction Processing.

Account Management for Digital Wallet System

Responsible for creating user accounts and their wallets.

Operations:

  • CRUD for account.
  • CRUD for account wallets.

CRUD: Create, Read, Update, Delete.

Wallet Management for Digital Wallet System

The Wallet Management sub-system provides support for various wallet operations. It is responsible for starting an operation and informing about the result.

Operations:

  • Top-up or add funds to a wallet.
  • Wallet-to-wallet transfer.
  • Wallet-to-merchant transfer.

Transaction Processing for Digital Wallet System

Responsible for processing operations on accounts, wallets, and funds.

Operations:

  • Transaction authorization and processing.
  • Transaction reconciliation.
  • Dispute and chargeback handling.

Communication

Digital Wallet System provides sync and async communications APIs for account management, wallet management, and payment processing.

The digital wallet system can call a webhook URL with payment reference data as a payload to notify about a payment result.

Create an accountREST API
Create a walletREST API
Payment requests (top-up, transfer, etc.)Async processing (*)
Payment notificationsWebhook calls
Internal communicationMessaging (**)
Communication patterns

* The system exposes REST APIs for handling payment requests (top-up, transfer, etc.). These APIs accept the requests and submit them for internal processing, and then a relevant component processes them asynchronously. We will address this topic in more detail.

** Communication between components happens via internal messaging channels. A simplified example looks like this:

  1. Client submits a top-up request via the API.
  2. Web controller accepts the request, “registers” it internally, and immediately returns an acknowledgment with a reference number.
    • In this context, the word immediately means that the web controller does not wait for the actual operation to start or complete. The web controller is only concerned that the operation was successfully submitted internally, and a reference identifier was generated for tracking.
  3. Registering it internally triggers an event, and a relevant component reacts to that event and starts processing.
  4. When processing is completed, a relevant component emits another event, and the system notifies clients using the reference identifier generated at the operation’s start.

Public APIs

Top-up API

POST /topup

PAYLOAD:
{
  "to_wallet": 1,
  "amount": 1234,
  "currency": "EUR"
}

Wallet-to-wallet Transfer API

POST /transfer

PAYLOAD:
{
  "from_wallet": 1,
  "to_wallet": 2,
  "amount": 1234
}

Wallet-to-merchant Transfer API

POST /purchase

PAYLOAD:
{
  "from_wallet": 1,
  "to_merchant": 101,
  "amount": 1234
}

Article TODO List

Some known TODOs for this article:

  • Add business requirements for transaction processing.
Tags: