DEV Community: Amani Moses

How a Senior Engineer Designs a Reliable Online Payment System Architecture

Amani Moses — Thu, 16 Jul 2026 06:22:09 +0000

When you build a feature for a typical app—like a social feed or a profile page—a software bug is usually just an annoyance. A user might have to refresh their page, or a button might not click.

In a payment system, the stakes are entirely different.

A single bug can withdraw real money from a customer’s bank account twice, lose track of a transaction entirely, or accidentally deposit funds you don’t have. In this world, getting it right is infinitely more important than getting it fast.

This guide is a complete, beginner-friendly blueprint for designing a payment back-end. We will demystify the technical jargon and explain exactly how to build a system where money never goes missing, even when the internet cuts out mid-transaction.

1. The Three Ways to Accept Payments

If you want your app to take payments, you don’t have to build a bank. Instead, you integrate with a Payment Service Provider (PSP)—companies like Stripe, PayPal, or Lemon Squeezy that act as translators between the modern internet and the legacy banking system.

Depending on your business needs, you can choose one of three integration routes:

1. Hosted Checkout (No-Code) | You put a button on your website that redirects users to a pre-built page hosted by Stripe or PayPal. | Extremely fast to set up. You can go live in minutes. | You have zero control over the design. It is very hard to handle complex things like shopping carts or customized subscription plans.

2. Your Own Processor (The DIY Route) | You bypass the middlemen entirely, apply for banking licenses, and connect directly to Visa and Mastercard. | The lowest transaction fees possible. | It takes years of legal work, strict security audits, and millions of dollars. Only giants like Amazon operate at this scale.

3. API Integration (The Sweet Spot) | You use a PSP's hidden infrastructure but build your own custom checkout screen. This is what we are designing. | You get complete control over the user experience without any of the legal or banking headaches. | It requires meticulous back-end design to ensure you don't accidentally double-charge people. |

2. The Secret Journey of a Credit Card

To build a reliable system, you first need to understand what happens behind the scenes when a customer enters their card number and clicks "Pay."

Every transaction is split into two distinct steps to prevent fraud and errors.

Step 1: Authorization (Holding the Money)

When a customer submits their card details, your app securely hands them to the PSP (e.g., Stripe). The PSP asks the customer’s bank:

"Does this card exist, and do they have $50?"

If the bank says yes, they put a temporary hold on that $50. The money hasn't left the customer's account yet, but they can't spend it elsewhere. It is "reserved." This is called an Authorized payment.

Step 2: Capture (Taking the Money)

Once you confirm everything is in order, your backend tells the PSP to actually claim that reserved money. This is called Capturing the payment.

Immediate Capture: For digital items or subscriptions, you authorize and capture the money immediately.
Delayed Capture: For physical items (like ordering on Amazon), the money is only authorized (held) when you order, and only captured (taken) when the item actually ships.

3. The Blueprint: How the System is Structured

To keep the system highly reliable, we divide our backend architecture into two distinct pathways: the Synchronous (Instant) Path and the Asynchronous (Background) Path.

The Synchronous Path (What the User Sees)

This path is optimized for speed. When a user clicks "Pay," we want to give them an instant response without keeping them waiting on slow banking networks.

The Checkout Page: The user types their card info into secure forms provided by your PSP. Your servers never actually touch or see the raw credit card number (which keeps you safe from massive security liabilities).
The Payment API: Your backend receives a "request to pay." Before doing anything, it assigns a unique tracking record to this transaction.
Creating an "Intent": Your backend tells the PSP, "We intend to charge this customer $50." The PSP returns a secret code. Your frontend uses this code to securely complete the payment with the customer's bank.

The Asynchronous Path (The Heavy Lifting in the Background)

Because banks can be slow and network connections can drop, we do the final confirmation of the payment in the background using Webhooks.

A Webhook is simply the PSP calling your backend's phone number to say:

"Hey, just letting you know that $50 charge went through successfully."

The Webhook Receiver: A dedicated listener that waits for the PSP's confirmation. It must do its job in under a second: verify the message is genuinely from the PSP, save the raw message to a database, say "Got it!", and hang up.
The Message Queue: A digital assembly line. The Webhook Receiver drops the payment confirmation onto this conveyor belt so it doesn't get lost if your system temporarily crashes.
Background Workers: Virtual employees that grab messages from the conveyor belt one by one. They update your database to mark the user as "Paid," unlock their premium features, and record the transaction in your company ledger.

4. Bulletproofing Your System: The Core Challenges

The hardest part of building a payment system is handling the messy reality of the internet. Servers crash, users double-click buttons, and networks drop. Here is how we prevent disaster.

Problem A: The Double-Click (Preventing Double Charges)

If a user has a slow connection, they might click the "Submit Payment" button three times. Without protection, your server might send three separate charge requests to the bank.

The Solution: Idempotency Keys

An Idempotency Key is a unique "ticket number" generated by the user's browser the moment they open the checkout screen.

No matter how many times the user clicks submit, or how many times your server retries a failing connection, they always send that exact same ticket number. Your bac-kend checks its database: "Have I seen ticket ID-999 before?"

If no, it processes the payment.
If yes, and it's already paid, it simply hands back the successful receipt without charging the card again.
If yes, but it crashed halfway through, it picks up exactly where it left off instead of starting over.

Problem B: Crashing in the Middle of a Transaction

Imagine your server successfully tells Stripe to charge the customer $50. Stripe does it. But right before Stripe can send back the confirmation, your server loses power. Stripe thinks the payment is done, but your database still says "Pending." The customer was charged, but they didn't get their digital item!

The Solution: Two-Phase Status Validation & Ledgers

To solve this, your database must strictly enforce a Finite State Machine (FSM). This is a rulebook that says a payment can only move from state to state in a logical, step-by-step order (e.g., a payment cannot go straight from Created to Completed without passing through Pending and Authorized).

We also use Double-Entry Bookkeeping (Ledgering). Just like a real accountant, our system never "edits" or "deletes" past transaction records to fix a mistake. If we accidentally recorded a wrong charge, we do not erase it. Instead, we write a completely new, balancing entry (a refund entry) to correct the math. This creates an unalterable paper trail for every single penny.

Problem C: Consistency over Availability

In most web apps, if a database is temporarily out of sync and shows a user an old profile picture for 5 seconds, nobody cares.

In payments, if a database is out of sync and shows a user they have $0 instead of $100, they will panic.

Because of this, payment back-ends prioritize Consistency over Availability. If our databases are struggling to synchronize, we would rather show a clean, polite "Service temporarily unavailable, please try again in a moment" error message than display incorrect account balances or let a transaction slip through unrecorded.

Why Every Developer Needs Workspaces: Architecture, Setup, and True Productivity

Amani Moses — Fri, 22 May 2026 09:55:42 +0000

As developers, context switching is our silent productivity killer. Jumping between a backend service, a database CLI, and documentation disrupts cognitive flow. Expanding that point further, while working on a project, switching between your research and your actual implementation, while still referring to your research and planning, requires a certain level of order.
workspaces (or Virtual Desktops) are a core architectural feature of modern operating systems that act as an extension of a developer's working memory.
Here is a deep dive into how they work under the hood, how to set them up, and why every major OS was forced to adopt them.

1. Under the Hood: How Workspaces Boost Productivity

 When you use workspaces properly, you are essentially partitioning your OS environment to match your mental model of a project. Instead of minimizing and maximizing 15 windows to find your terminal, a single hotkey swaps your entire visual array. Your brain registers the visual shift as a complete transition to a new task.

State Preservation: You can leave a broken build, an uncommitted file, and three StackOverflow tabs open in Workspace 3, switch to Workspace 1 to handle an emergency production hotfix, and return to Workspace 3 with your exact debugging state intact.
The "One Task, One Screen" Rule:
By dedicating one workspace to code, one to testing/terminals, and one to communication (Slack/Email), you build muscle memory. Your fingers know exactly where to go before your brain even processes the request.

2. The Ideal Developer Setup (The 4-Workspace Matrix)

While you can create dozens of workspaces, the sweet spot for software engineering is a **4-Workspace Matrix**. This keeps your workflow predictable and linear.

Workspace	Name / Focus	Typical Applications
Workspace 1	Communications & Docs	Slack, Discord, Email, Project Management (Jira/Linear), Browser for API documentation.
Workspace 2	Core Development	IDE (VS Code, JetBrains), Primary Source Code windows.
Workspace 3	Runtime & Diagnostics	Terminals (Tmux), Docker Desktop, Database Clients (Beekeeper, PgAdmin), Browser Console/Localhost.
Workspace 4	Testing & Production	CI/CD pipelines, Postman/Insomnia, Staging environments, Version Control GUI (GitKraken).

Keyboard Shortcuts: The Ultimate Optimizer

To make this setup effective, you must abandon the mouse for switching.

Ubuntu/GNOME Default: Super + PageUp / PageDown (Or bind to Super + 1, 2, 3, 4 for instant jumping).
macOS Default: Ctrl + Left / Right Arrow (Or Ctrl + 1, 2, 3, 4).
Windows Default: Win + Ctrl + Left / Right Arrow.

3. The Great OS Convergence: How the Industry Caught Up

 Workspaces have a fascinating history. For a long time, they were a major point of divergence between operating systems until the sheer utility of the feature forced a universal standard.

Unix/Linux: The Pioneers

Virtual desktops originated in the Unix world (specifically rooms in the Solbourne Window Manager back in 1990) and became a staple of Linux desktop environments (GNOME, KDE, Xfce) decades ago. Linux treated workspaces as a core primitive of the X11 and Wayland display servers. Because developers heavily favored Linux for its command-line efficiency, workspaces became a secret weapon for high-productivity coding.

macOS: The Spaces Evolution

Recognizing the power of this workflow for power users, Apple introduced "Spaces" in 2007 with Mac OS X 10.5 Leopard. It was later integrated into Mission Control. Apple refined the feature by tying it beautifully to trackpad gestures (three-finger swipe), making workspace adoption seamless for creative professionals and developers who were migrating to MacBook Pros.

Windows: The Late Adopter

For years, Windows users had to rely on buggy third-party tools (like Sysinternals Desktops) to get virtual desktops. Microsoft finally yielded to industry pressure and introduced native Virtual Desktops in 2015 with Windows 10. With Windows 11, they advanced this further by allowing unique wallpapers and custom names per desktop—a direct nod to developers who need clear visual separation between "Work" and "Personal" profiles on a single machine.

4. Advanced Pro-Tips for Power Users

If you want to take your workspace setup to the absolute limit, implement these two configurations:

Pinning Applications: Identify apps that should transcend workspaces. For example, pin your music player (Spotify) or a floating calculator so they appear on all workspaces, while your code stays isolated.
Dynamic vs. Static: Some environments (like Ubuntu GNOME) use dynamic workspaces—creating new ones as you need them. For developers, Static Workspaces (fixed at 4 or 5) are usually superior because they allow you to map specific project components to fixed slot numbers in your muscle memory.

Ready to customize? Drop your current workspace layout in the comments below. Are you a 3-space minimalist or a 9-space chaotic genius?

Moonbug: a cosmic lunar calendar and event catalogue

Amani Moses — Sun, 19 Apr 2026 20:39:31 +0000

How I Built It: The "Boss-Agent" Workflow
My development process was a study in AI orchestration. I operated at a "Boss-Agent" level, managing two distinct AI entities to take Moonbud from a mobile concept to a live deployment entirely from a smartphone.

Architectural Planning (Gemini as Architect): I used Gemini 1.5 Pro to architect the project. We defined the "MoonPlayer" philosophy—aligning digital habits with lunar cycles rather than a 24-hour clock. Gemini provided the logic for cosmic computations, structured the React-based sleep screens, and designed the modularity between the web app and the browser extension.

The Command Center (Firebase Studio Agent): Operating within Firebase Studio on my smartphone, I acted as the "Boss." I injected high-level prompts into the Studio's AI agent to generate functional code components, set up the Firestore NoSQL schema, and configure the complex Firebase CLI environment.

The Feedback Loop & Debugging: I tested the app in real-time on my mobile browser, reporting logs and errors back to the Firebase Studio agent. It acted as my engineering assistant, reporting back with fixes for major hurdles like OAuth 2.0 --no-localhost authentication and React routing conflicts. This iterative loop allowed me to solve technical debt and major errors instantly, leading to a fully functional prototype without ever touching a desktop computer.

🔗 Project Links
Live Demo (Functional Prototype):

9000-firebase-studio-1761554855004.cluster-lu4mup47g5gm4rtyvhzpwbfadi.cloudworkstations.dev

(Developed and hosted via Google Cloud Workstations)

GitHub Repository: { embed https://github.com/Musaamanipeace/moonlayer %}

🏆 Prize Category
Best Use of Google Gemini Highlighting a sophisticated "Boss-Agent" orchestration where Gemini acted as lead architect and project manager. I used Gemini 1.5 Pro's reasoning capabilities to transform dry astronomical data into a personalized user experience and used the Firebase Studio agent to execute complex development tasks on mobile.

🌟 Specific Use of Google Gemini
The Intelligence Layer: I integrated the Gemini API as a scientific curator. It processes live NASA and NOAA data, summarizing it into "Nature Cards" so users stay informed about astronomical and environmental events without information overload.

The Context Engine: Gemini reasons through user-specific data (like birth moon phases) to suggest nature-themed hobbies, travel trends, and "Circadian Deep Work" blocks.

The "Awareness Guard": In the companion browser extension, Gemini filters incoming weather and astronomical notifications, ensuring only peaceful, significant events trigger the custom "Solar Alarms."

🌿 Environmental Impact
Moonbug bridges the gap between high-tech living and the natural world. By replacing "doom-scrolling" with "lunar-scrolling," the app fosters a mindset of environmental stewardship and astronomical awe. It encourages users to synchronize their digital lives with Earth’s natural rhythms, reducing digital fatigue and increasing planetary connection.

🛠 Tech Stack
AI: Gemini 1.5 Pro API (Orchestration & Data Curation)

Backend: Firebase (Firestore, Hosting, CLI)

Frontend: React, Vite, Tailwind CSS

IDE: Firebase Studio (Cloud Workstations)

Target: Cross-platform Web + Chrome Extension