FINTECH 101 — HOW TRANSACTIONS REALLY WORK

Source: Dev.to

The Core Mental Model

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.

Transaction Statuses (Not Responses)

In fintech we track states, not just HTTP responses.

The Canonical Transaction Lifecycle

What These Statuses Actually Mean

Golden Rule
A transaction can only end in SUCCESS, FAILED, or REVERSED (temporarily).

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

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

Concept vs. Purpose

Example

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

An HTTP 200 only means “we heard you”; it does not mean the transaction succeeded. The status field is the source of truth.

Money Representation

Never use floats or doubles for money.
Computers use binary (base‑2) while humans use decimal (base‑10). Some simple decimals cannot be represented perfectly in binary, leading to rounding errors and ledger mismatches.

The Correct Approach: Minor Units

Store money in the smallest currency unit.

Rule of thumb

• Database: BIGINT (e.g., 1050 for 10.50)
• Code: Integer math (1050 + 20)
• Frontend: Convert only for display (e.g., GH₵10.70)

Callbacks (Webhooks)

What Is a Callback?

A callback occurs when a transaction is still pending due to network delays, banks being offline, or processor timeouts.

Typical Callback Flow

1. You send a request.
2. Processor responds → PENDING.
3. You save the transaction as PENDING.
4. Later, the processor calls your endpoint.
5. You update the transaction → SUCCESS / FAILED.

Callback Failures

• Network issues
• Processor downtime
• Processor bugs

Because callbacks can fail, fintech systems also use status enquiry (pull) to recover the truth.

• Push: Processor tells you (callback).
• Pull: You ask the processor (status enquiry).

Idempotency

The Nightmare Scenario

1. User clicks “Pay”.
2. Network glitches.
3. User clicks again.
4. Two charges happen.

Solution: Idempotency Key

• Reject duplicate references.
• Enforce database uniqueness (UNIQUE(reference)).

Retries

Retries are dangerous when there is:

• No response (timeout)
• Network error

A retry after a SUCCESS can cause duplicate charges, while a retry after a FAILED business outcome may be unnecessary.

Reversals

A reversal is needed when:

• A SUCCESS debit was made but delivery failed.
• No callback was received after the SLA.

Reversal Flow

1. Detect mismatch.
2. Call reversal API.
3. Update transaction → REVERSED.
4. Notify user.

Your records will never perfectly match the processor’s. Any mismatch should be investigated and corrected.

Logging Requirements

Every fintech system must log:

• Request payload
• Response payload
• Status transitions
• Timestamps

Final Mental Model (Keep This Forever)

• Never trust the first response.
• Money systems are eventually consistent.
• Status is truth, not HTTP response codes.
• Accounting always wins.

If you build fintech with this mindset, you won’t just pass tests—you’ll survive production.