?? Fintech 101: Plain-English Concept Glossary

Understanding core payment terminology before integrating or inspecting APIs.

? Idempotency

Like an elevator button: pressing it multiple times does not summon multiple elevators. In payments, retrying a webhook with the same event_id guarantees zero duplicate ledger charges.

?? Reconciliation vs. Settlement

Settlement is the actual bank payout deposited into the merchant's account. Reconciliation is the automated mathematical audit comparing internal logs with banking statements.

?? State Machine

Deterministic lifecycle rules. Transactions can only advance forward (initiated ? processed ? settled) and cannot jump backward.

?? Discrepancy

An anomaly where bank reports failure but settlement file shows credit, or money was deducted but not settled within the cutoff window.

??? System Architecture in Plain English

How events flow through the service from checkout to merchant payout.

1. Merchant / Client App: Emits lifecycle webhooks as customers complete checkout.
2. FastAPI Ingestion Bus: Validates payload schemas, enforces idempotency keys, and updates the state machine.
3. PostgreSQL Financial Ledger: Serves as the single source of truth for chronological transaction history.
4. Automated Reconciliation Engine: Audits transactions across all merchants, identifying settlement rates and ledger discrepancies.

?? The Event & State Machine Matrix

The 4 deterministic event types, their real-world triggers, and balance impact.

Event TypeReal-World TriggerTransaction StateBalance Impact
payment_initiated Customer starts checkout on app/web. initiated ?0.00 (Intent created).
payment_processed Bank/gateway confirms capture. processed Funds held in gateway escrow.
settled T+1 or T+2 merchant payout batch. settled Funds credited to merchant account.
payment_failed OTP timeout, decline, or bank error. failed ?0.00 (No money moved).

?? Failure Modes & Edge Case Safeguards

How the engine autonomously handles out-of-order delivery, network replays, and anomalies.

1. Network Replays & Duplicate Ingestion:
If a gateway retries the same event, the engine responds with HTTP 200 OK ("ingestion_status": "already_processed") with zero duplicate entries.
2. Out-of-Order Webhook Delivery:
If settled arrives before payment_processed due to queue latency, the terminal state is preserved and both events are ordered chronologically by timestamp.
3. The 3 Core Discrepancies:
? settled_after_failure: Critical anomaly where merchant was paid despite decline.
? processed_not_settled: Captured funds not settled within cutoff window.
? stale_initiated: Abandoned user checkout session (> 24h).
POST /events

Ingest Payment Event

Ingests a payment lifecycle event into the idempotent event bus.

FieldTypeDescription
event_id
Required
UUIDIdempotency key.
event_type
Required
Enumpayment_initiated, payment_processed, settled, payment_failed
transaction_id
Required
UUIDTransaction UUID.
merchant_id
Required
stringMerchant identifier.
amount
Required
DecimalPositive decimal (> 0.00).
POST /events
{
  "event_id": "b4c064d0-966c-4050-8110-32e5869452b8",
  "event_type": "settled",
  "transaction_id": "edb15f35-809b-4353-9d3c-01fb5a88f537",
  "merchant_id": "merchant_4",
  "amount": "45420.50",
  "currency": "INR",
  "timestamp": "2026-04-08T15:56:25Z"
}
GET /events

List Ingested Events

Paginated list of all received payment events with multi-field filters.

ParameterTypeDescription
page
Default: 1
integerPage index (>= 1).
page_size
Default: 50
integerItems per page (max 100).
event_type
Optional
stringFilter by event type.
GET /events?page=1&page_size=2
{
  "total": 10165,
  "page": 1,
  "page_size": 2,
  "items": [ ... ]
}
GET /transactions

List Payment Transactions

Query transactions with status and merchant filters.

ParameterTypeDescription
status
Optional
stringinitiated, processed, settled, failed.
merchant_id
Optional
stringFilter by merchant UUID/ID.
page_size
Default: 20
integerItems per page (max 100).
GET /transactions?page_size=2
{
  "total": 3800,
  "page": 1,
  "page_size": 2,
  "items": [ ... ]
}
GET /transactions/{id}

Get Transaction Details & Audit Trail

Reconstructs full transaction state along with its complete chronological event history.

ParameterTypeDescription
id
Required
UUIDThe unique UUID of the transaction.
Sample UUID Lookup
/transactions/edb15f35-809b-4353-9d3c-01fb5a88f537
GET /reconciliation/summary

Reconciliation Financial Summary

Aggregates financial volumes, settled amounts, and merchant performance metrics.

MetricTypeDescription
total_transactions
integerTotal transaction count.
total_settled_amount
DecimalSettled revenue in INR.
by_merchant
ArraySettlement rate per merchant.
GET /reconciliation/summary
{
  "total_transactions": 3800,
  "total_amount": "95176625.69",
  "total_settled_amount": "66435431.65",
  "by_merchant": [ ... ]
}
GET /reconciliation/discrepancies

Audit Ledger Discrepancies

Automated auditing engine that flags anomalies.

TypeDescription
settled_after_failure
Funds settled despite gateway failure.
processed_not_settled
Payment captured but not settled.
stale_initiated
Stuck in initiated state with no update.
GET /reconciliation/discrepancies
{
  "total_discrepancies": 12,
  "by_type": {
    "processed_not_settled": 12
  }
}
GET /health

System Health Probe

Lightweight machine-readable JSON health check for uptime monitors.

FieldTypeValue
status
string"healthy"
GET /health
{"status": "healthy", "service": "Setu Payment Service"}

??? Error Codes & Troubleshooting Guide

Human-readable meanings for standard API responses.

Status CodeMeaning in Plain EnglishAction Required
200 OK (already_processed) This event was already ingested safely in the past. Zero action required ? idempotency protected your ledger.
422 Unprocessable Validation error (e.g. missing amount, invalid UUID, negative value). Check request payload fields against schema.
404 Not Found Requested transaction UUID does not exist in database. Verify transaction ID from earlier checkout responses.