DEV Community: Priyanka

Things Nobody Tells You About Building Payment APIs

Priyanka — Tue, 10 Feb 2026 06:53:17 +0000

Building a payment API looks deceptively simple.

Accept a request, validate it, call a provider, return a response.

That mental model works right up until your system reaches real traffic, real money, and real failures. At that point, payment APIs stop behaving like APIs and start behaving like distributed financial systems.

This article covers the things teams often discover only after they’ve shipped to production.

Payments Are Asynchronous by Nature
One of the first surprises is that payments rarely complete in a single request-response cycle.
Even when an API returns 200 OK, the payment might still be:
Pending settlement
Awaiting provider confirmation
Subject to later failure or reversal

This means:
The API response is not the final truth
Webhooks become mandatory
State management becomes critical

Design APIs assuming that every payment is eventually asynchronous, even if it doesn’t start that way.

Webhooks Will Betray You (If You’re Not Careful)

Webhooks are not:
Guaranteed
Ordered
Unique

You will see:
Duplicate events
Out-of-order delivery
Delayed callbacks
Missing events

If your system assumes “one webhook = one state change,” it will break.

Every webhook handler must be:
Idempotent
State-aware
Safe to replay

Idempotency Is Not Optional
In payment systems:
Clients retry
Networks fail
Load balancers time out

Without idempotency:
Users get double-charged
Balances drift
Trust evaporates

Idempotency should exist at:
API level
Database level
Provider integration level

If you can’t safely replay a request, your system is fragile.
Error Handling Is Business Logic
Most APIs treat errors as exceptions.
Payment APIs cannot.

Errors carry meaning:
Insufficient funds
Provider timeout
Compliance rejection
Rate limit exceeded

Each error type may require:
A retry
A reversal
A manual review
A user notification
Error handling in payments is not defensive coding, it is core business logic.

Transactions Have More States Than You Think
A payment is rarely just “success” or “failed.”

Common states include:
Created
Authorized
Pending
Completed
Partially settled
Reversed
Failed
Expired

Trying to collapse these into a boolean status leads to:
Complex edge cases
Impossible reconciliation
Broken user experiences
Explicit state machines save time and bugs.

Money Should Never Be Eventually Consistent
Many distributed systems embrace eventual consistency.
Money systems should not.
A delayed balance update can mean:
Overspending
Compliance breaches
Reconciliation nightmares

Strong consistency in wallet and balance operations is worth the cost even if it limits throughput.

Reconciliation Is Inevitable
Even with perfect code:
Providers disagree
Networks fail
Humans intervene

If reconciliation is an afterthought, it becomes a crisis.
Well-designed payment systems treat reconciliation as:
A first-class feature
A daily process
An auditable workflow

The goal isn’t zero mismatches, it's fast detection and resolution.
Your API Is Only Half the System
The API is what developers see.
The real system includes:
Background workers
Retry mechanisms
Webhook processors
Reconciliation jobs
Audit logs
Ignoring these pieces early leads to fragile systems later.

Lessons Learned
After working with payment APIs in production, a few truths stand out:
Payments are workflows, not requests
Idempotency is survival
Webhooks are unreliable by default
States beat booleans
Reconciliation is unavoidable

The sooner teams accept this, the smoother their systems scale.

Closing Thoughts
Payment APIs live in a world where technology, finance, and regulation constantly collide. Many of the hardest problems don’t appear in local development or early demos—they surface only under real traffic, real money, and real failure scenarios.
Designing for idempotency, explicit state transitions, strong consistency, and reconciliation from day one dramatically reduces long-term risk. These concerns may feel heavy early on, but they’re far easier to address upfront than to retrofit later.
I currently work on payment and fintech infrastructure at Artha FinTech, where we focus on building scalable, compliance-ready platforms for wallets, payments, and digital banking use cases.

If you’re interested in the types of infrastructure challenges discussed here, you can find more context at: https://arthatech.net

Designing a Scalable Wallet System for Modern Fintech Applications

Priyanka — Tue, 27 Jan 2026 07:12:04 +0000

Building a wallet system sounds simple at first: track balances, support credits and debits, expose a few APIs.

In practice, wallets quickly become one of the most complex parts of a fintech system.

Once you introduce multiple currencies, transaction states, reversals, audits, concurrency, and regulatory constraints, a wallet is no longer just a balance table it’s a financial ledger with strict correctness guarantees.

This article shares practical lessons and architectural decisions involved in designing scalable wallet systems for modern fintech applications.

Why Wallets Are Harder Than They Look
A wallet is often the source of truth for user funds. Any inconsistency can lead to:
-Incorrect balances
-Failed settlements
-Compliance issues
-Loss of user trust

Unlike many application features, wallets cannot be “eventually correct.” They must be correct immediately, every time.

Common hidden challenges include:
Concurrent transactions
Partial failures
Idempotency
Auditing and reconciliation
Regulatory traceability

Core Principles of a Scalable Wallet System
Before touching architecture or code, it helps to align on a few non-negotiable principles.

1. Wallets Are Ledgers, Not Just Balances
A single balance column is never enough.
Every wallet should be backed by:
Immutable transaction records
Clear debit/credit semantics
Deterministic balance calculation
Balances are often derived values, not the primary source of truth.
2. Every State Transition Must Be Explicit
Transactions are rarely atomic in real systems.
Typical transaction states include:
Created
Pending
Completed
Failed
Reversed
Explicit states make retries, reconciliation, and audits far easier.
3. Idempotency Is Mandatory
In distributed systems:
APIs will be retried
Webhooks will be duplicated
Networks will fail
Every wallet mutation must be idempotent.
A transaction reference should never be applied more than once.

High-Level Architecture
A scalable wallet system usually consists of these layers:
API Layer
↓
Wallet Service
↓
Transaction Ledger
↓
Balance Projection

Each layer has a single responsibility.

Wallet Data Model (Simplified)
A common and reliable approach separates wallets from transactions.

Wallet Table
-WalletId
-CustomerId
-Currency
-Status
-CreatedAt

Transaction Ledger Table
TransactionId
WalletId
Amount
Direction (Credit / Debit)
Status
ReferenceId
CreatedAt

Balance Table
WalletId
AvailableBalance
LockedBalance
UpdatedAt
The ledger is immutable.
Balances are projections derived from it.

Handling Concurrency Safely
Concurrency is one of the hardest problems in wallet systems.
Common approaches:
Database-level locking
Optimistic concurrency (row versioning)
Serialized wallet updates per wallet ID
A practical rule:
Never allow two balance-modifying operations on the same wallet to execute concurrently.
This can be enforced using:
Database transactions
Distributed locks
Queue-based processing

Available vs Locked Balances
Most real-world systems need at least two balances:
Available Balance – funds the user can spend
Locked Balance – funds reserved for pending operations
Example:
User initiates a withdrawal
Amount moves from Available → Locked
On success: Locked → Deducted
On failure: Locked → Available
This pattern prevents overspending and race conditions.

API Design Considerations
Wallet APIs should be:
Explicit
Predictable
Defensive
Example endpoints:
POST /wallets/{id}/credit
POST /wallets/{id}/debit
POST /wallets/{id}/reserve
POST /wallets/{id}/release
Each request must include:
Unique transaction reference
Amount
Source context (payment, exchange, card, etc.)
Avoid “magic” behavior—clarity beats cleverness.

Auditability & Compliance Hooks
Fintech wallets live in regulated environments.
Design for audits from day one:
Store pre-balance and post-balance snapshots
Persist transaction metadata
Keep immutable logs
Support traceability across systems
A good rule:
If an auditor asks “why did this balance change?”, you should be able to answer with a single query.

Reconciliation Is Not Optional
Even with perfect code, mismatches happen:
External provider delays
Partial failures
Human overrides
Build reconciliation workflows:
Compare internal ledger vs external statements
Flag mismatches
Support manual adjustments with full audit trails
Reconciliation should be a feature, not a fire drill.

Lessons Learned:
After working on wallet-heavy systems, a few patterns stand out:
Simple schemas break under scale
Explicit states reduce bugs dramatically
Ledger-first design saves you later
Idempotency prevents financial disasters
Reconciliation logic should be first-class
Most importantly:
A wallet system is financial infrastructure, not application logic.

Practical Takeaways:
If you’re designing a wallet system:
Treat balances as projections, not truth
Make transactions immutable
Enforce idempotency everywhere
Serialize wallet updates
Design for audits and reconciliation early
These decisions may feel heavy at first but they pay off massively in production.

Closing Thoughts:

Wallet systems sit at the core of modern fintech platforms. Whether you’re building payments, cards, exchanges, or embedded finance flows, the reliability of your wallet layer determines how far the system can scale.

Getting the fundamentals right ledger-first design, explicit transaction states, idempotency, and auditability removes an entire class of problems later in production.

I currently work on fintech infrastructure and wallet systems at ArthaTech, where we focus on building scalable, compliance-ready financial platforms used across payments and digital banking use cases.

If you’re curious about the type of infrastructure challenges we work on, you can find more context here:
https://arthatech.net/