Developer API Reference & Guide
Comprehensive specifications, lifecycle rules, payload schemas, and interactive execution tools.
?? Fintech 101: Plain-English Concept Glossary
Understanding core payment terminology before integrating or inspecting APIs.
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.
Settlement is the actual bank payout deposited into the merchant's account. Reconciliation is the automated mathematical audit comparing internal logs with banking statements.
Deterministic lifecycle rules. Transactions can only advance forward (initiated ? processed ? settled) and cannot jump backward.
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.
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 Type | Real-World Trigger | Transaction State | Balance 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.
If a gateway retries the same event, the engine responds with
HTTP 200 OK ("ingestion_status": "already_processed") with zero duplicate entries.
If
settled arrives before payment_processed due to queue latency, the terminal state is preserved and both events are ordered chronologically by timestamp.
?
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).
Ingest Payment Event
Ingests a payment lifecycle event into the idempotent event bus.
| Field | Type | Description |
|---|---|---|
event_id Required | UUID | Idempotency key. |
event_type Required | Enum | payment_initiated, payment_processed, settled, payment_failed |
transaction_id Required | UUID | Transaction UUID. |
merchant_id Required | string | Merchant identifier. |
amount Required | Decimal | Positive decimal (> 0.00). |
{
"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"
}
List Ingested Events
Paginated list of all received payment events with multi-field filters.
| Parameter | Type | Description |
|---|---|---|
page Default: 1 | integer | Page index (>= 1). |
page_size Default: 50 | integer | Items per page (max 100). |
event_type Optional | string | Filter by event type. |
{
"total": 10165,
"page": 1,
"page_size": 2,
"items": [ ... ]
}
List Payment Transactions
Query transactions with status and merchant filters.
| Parameter | Type | Description |
|---|---|---|
status Optional | string | initiated, processed, settled, failed. |
merchant_id Optional | string | Filter by merchant UUID/ID. |
page_size Default: 20 | integer | Items per page (max 100). |
{
"total": 3800,
"page": 1,
"page_size": 2,
"items": [ ... ]
}
Get Transaction Details & Audit Trail
Reconstructs full transaction state along with its complete chronological event history.
| Parameter | Type | Description |
|---|---|---|
id Required | UUID | The unique UUID of the transaction. |
/transactions/edb15f35-809b-4353-9d3c-01fb5a88f537
Reconciliation Financial Summary
Aggregates financial volumes, settled amounts, and merchant performance metrics.
| Metric | Type | Description |
|---|---|---|
total_transactions | integer | Total transaction count. |
total_settled_amount | Decimal | Settled revenue in INR. |
by_merchant | Array | Settlement rate per merchant. |
{
"total_transactions": 3800,
"total_amount": "95176625.69",
"total_settled_amount": "66435431.65",
"by_merchant": [ ... ]
}
Audit Ledger Discrepancies
Automated auditing engine that flags anomalies.
| Type | Description |
|---|---|
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. |
{
"total_discrepancies": 12,
"by_type": {
"processed_not_settled": 12
}
}
System Health Probe
Lightweight machine-readable JSON health check for uptime monitors.
| Field | Type | Value |
|---|---|---|
status | string | "healthy" |
{"status": "healthy", "service": "Setu Payment Service"}
??? Error Codes & Troubleshooting Guide
Human-readable meanings for standard API responses.
| Status Code | Meaning in Plain English | Action 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. |