Kwaku Essah

Posted on Dec 18

FINTECH 101 — HOW TRANSACTIONS REALLY WORK

#fintech #systemdesign #backenddevelopment #software

You click Pay and see Success in under a second.
But behind that green checkmark is a system that may take minutes, or hours to actually settle money.

In fintech, nothing is truly instant.
What looks instant is well-engineered state management.
This article explains how real payment systems work, and why naïve implementations fail.

The Core Mental Model
Every fintech payment system regardless of country, bank, or processor is built on four pillars:

1. Transaction statuses
2. Callbacks / Webhooks
3. Reconciliation & Status Enquiry
4. Retries, reversals & idempotency

If you misunderstand even one of these, you will eventually lose money.

Let’s break it down

1. TRANSACTION STATUSES (Not Responses)

Many developers think:
“The processor responded, so the transaction is done.”

That is wrong.
Processors lie.
Networks fail.
Banks respond late.

So in Fintech we track STATES, not just responses.

The Canonical Transaction Lifecycle
INITIATED → request created internally
PROCESSING → sent to processor
PENDING → processor accepted but not final
SUCCESS → money confirmed delivered
FAILED → money not delivered
REVERSED → money taken then returned
TIMEOUT → no response within SLA

What These Status Actually means

Status	Meaning
INITIATED	Your system created the transaction
PENDING	Processor or network is still working
SUCCESS	Value delivered (airtime, data, money)
FAILED	Value was NOT delivered
REVERSED	Money was taken but refunded

Golden Rule

A transaction can only end in SUCCESS or FAILED (or REVERSED)
Everything else is temporary.

2. Response Codes ≠ Business Status

This distinction is critical.

In fintech systems, a request can be technically successful while the financial action itself does not complete. Cases like insufficient funds, pending bank confirmation, or failed compliance checks are normal business outcomes, not system errors.

Using HTTP response codes to show technical success and business status to show transaction outcome prevents confusion, avoids unsafe retries, and makes payment flows easier to reason about.

Concept	Purpose
Response Code	Technical result
Status	Business state

Example

HTTP Response	Meaning
200 OK	Request was processed successfully at a technical level

Example:
HTTP 200 OK

 {
 "code": "99",
"status": "PENDING"
"message": "Transaction is being processed"
 }

HTTP 200 only means “we heard you”.
It does not mean the transaction succeeded.
Status is the source of truth.

3.MONEY & DATA TYPES (The Silent Fintech Killer)

There is one rule you must never break in fintech.

NEVER use Floats or Doubles for money.

The Problem Computers use binary (base-2). Humans use decimal (base-10). Some simple decimals cannot be represented perfectly in binary.

Why this destroys you:

You charge 100.00
Calculate a 1% fee → 1.000000001
DB rounds it
Ledger mismatch occurs
At scale, your accounting breaks

The Correct Approach: Minor Units

Always store money in the smallest currency unit.
Wrong Right
10.50 (float) 1050 (integer)

Rule of thumb:

Database: BIGINT (1050)
Code: Integer math (1050 + 20)
Frontend: Convert only for display ( GH₵10.70)

4. CALLBACKS / WEBHOOKS (ASYNC TRUTH)

What is a callback?
A callback (webhook) is when the processor says:
“Remember that transaction?
I have the FINAL answer”

This happens when:

Transaction are pending
Networks delay
Banks go offline
Switch timeout

Typical callback flow

You send request
Processor responds → PENDING
You save transaction as PENDING
Later…
Processor calls YOUR endpoint
You update transaction → SUCCESS / FAILED

5. STATUS ENQUIRY (When Callbacks Fail)

Callbacks fail often:

Network issue
Downtime
Processor bug

So fintech systems also use status enquiry.

Callbacks: PUSH (they tell you)
Status enquiry: PULL (you ask them) This is how you recover truth.

6. IDEMPOTENCY(Prevent Double Charges)

The nightmare scenario...

User clicks “Pay”
Network glitches
User clicks again
Two charges happen

Solution: Idempotency Key
Each transaction must have a unique reference.

Rules:

Reject duplicate references
Enforce DB uniqueness

UNIQUE(reference)
Same request → same result → no double charge

7. RETRIES

Retries are dangerous.
Retry ONLY when:

No response
Timeout
Network error

Never retry on:

SUCCESS
Business failure (insufficient funds, wrong PIN)

Retries without rules create duplicate debits.

8. REVERSALS

A reversal means:
Money was debited, but value was not delivered.
This is the most serious failure mode.

When to reverse

SUCCESS debit
FAILED delivery
No callback after SLA

Reversal flow

Detect mismatch
Call reversal API
Update transaction → REVERSED
Notify user

9. RECONCILIATION

Your records will never perfectly match the processor’s.
So you reconcile:

Reference Amount Status
TX123 50 SUCCESS
TX124 100 FAILED

Any mismatch:

Investigate
Reverse or correct

This is financial integrity.

10. LOGGING & AUDIT TRAILS

Every fintech system must log:

Request payload
Response payload
Status transitions
Timestamps
Example:
INITIATED → PROCESSING → PENDING → SUCCESS → FAILED → REVERSED
Log
Logs save you in disputes, audits, and lawsuits.

Final Mental Model (Keep This Forever)

Never trust the first response
Money systems are eventually consistent
Status is truth, not response codes
Accounting always wins If you build fintech with this mindset, you won’t just pass tests you’ll survive production.