Secure Banking API Development, Part 3: Preserve Transaction Integrity When Responses Disappear
Preserve the authorised financial effect across retries, asynchronous processing, callbacks and uncertain outcomes, with durable identity and evidence-led recovery.
Perspectives · Secure Banking API Development · Part 3
A customer submits a ₹25,000 transfer. The payment service forwards it to the core, the debit posts, and the network connection fails before the service receives the response. The customer sees a timeout and taps “Try again.”
The identity was verified. The customer was authorised to debit the account. The approved payment terms were intact. Yet the bank now faces another security and integrity question: can the system recover the outcome without making a second payment?
Part 1 established the design contract. Part 2 implemented identity, authorisation, validation and approval controls. Part 3 follows the instruction through retries, asynchronous processing and reconciliation. The objective is to preserve the intended financial effect even when individual components cannot immediately agree on its status.
Define what each state proves
Begin with the business operation, not its HTTP response. A service can receive a request without durably recording it, accept an instruction without posting it, and post a debit before the beneficiary outcome is known. A single “success” flag hides these distinctions.
| Illustrative state | Evidence behind it | What it does not establish |
|---|---|---|
| Accepted | The service has durably recorded a valid instruction for processing. | That money has moved. |
| Processing | The instruction has entered the execution workflow. | That a later failure or uncertain result is impossible. |
| Debit posted | The authoritative posting system confirms the debit. | Beneficiary credit or final settlement on every rail. |
| Outcome pending | The institution is still resolving a downstream result. | Permission to create a replacement payment. |
| Completed | The evidence required by the bank’s contract for this operation is present. | A universal definition shared by all products and rails. |
| Rejected or reversed | A confirmed rejection, or an authorised corrective entry with its own reference. | That a timeout alone caused or proved either outcome. |
These labels are illustrative. Define allowed transitions, the authoritative evidence and the customer wording for your service. HTTP 202 Accepted acknowledges acceptance for processing; it does not guarantee completion. A status resource should expose the agreed business state and an authorised way to follow progress. [1]
Make a retry identify the original business instruction
A trace ID connects logs. An idempotency key lets a service recognise another attempt at the same operation. A business instruction ID persists across the workflow. A downstream posting reference identifies the financial entry. They can be mapped together, but they are not interchangeable.
Define the idempotency contract explicitly: the key format, scope, retention, supported operations, response behaviour and conflict handling. Scope it to the authenticated client or tenant and the operation, then bind it to the material instruction fields. The same key and same instruction must recover the original operation or its recorded outcome. Reusing the key with a changed account, beneficiary, amount or currency must produce a conflict under the contract.
Perform authentication and relevant authorisation checks on repeats and status reads too. An idempotency record is not permission to retrieve another caller’s result. Choose retention to cover delayed retries, processing, replay and recovery windows. Expiring a short-lived cache entry must not erase the durable business uniqueness needed to protect against another posting.
An Idempotency-Key header is useful only where the server implements and documents the behaviour. Do not assume an arbitrary POST becomes safe to retry because the header was sent. RFC 9110 limits automatic retries for non-idempotent methods unless their actual semantics or non-application are known. Stripe’s documentation provides one concrete implementation example, rather than a universal banking contract. [1] [2]
Close the race at the service that creates the effect
Two copies of a request can arrive together at different service instances. “Look up the key, then insert if absent” is unsafe if both checks see nothing. Use an atomic claim backed by an appropriate uniqueness constraint or equivalent durable mechanism. Record the instruction identity and request fingerprint with its state. A concurrent repeat should resolve to the same operation, or receive a documented in-progress response.
The harder boundary is the core or payment provider. A local idempotency record cannot atomically commit a separate core posting. In the opening example, use the original downstream instruction reference to query or reconcile the outcome. If the core supports duplicate detection by a stable external reference, use that contract and test it. If it does not provide a safe lookup or repeat mechanism, an uncertain request may need a hold and controlled investigation.
A worker lease expiring does not prove the earlier worker stopped or the downstream posting failed. Recovery needs state checks and, where appropriate, fencing or downstream duplicate protection. Giving a new worker permission to blindly resubmit can create the duplicate the gateway prevented.
Keep durable state and event publication connected
Asynchronous APIs improve decoupling, but introduce a familiar gap: the service commits an instruction and crashes before publishing its event. Reversing the order can publish an instruction that never committed.
A transactional outbox can record the business-state change and its outgoing event in the same local database transaction. A publisher then delivers committed events and retries delivery. AWS describes this pattern and the need for consumers to handle duplicate messages. The local atomic boundary does not extend to every downstream database or payment rail. [3]
At the consumer, make event deduplication and the protected local state change atomic where possible. When the consumer calls an external posting API, preserve the same business identity and apply that API’s recovery contract. A broker’s delivery guarantee does not, by itself, prove a single debit across the full banking journey.
Treat callbacks as authenticated, repeatable evidence
A partner callback can arrive twice, out of order or after a status query has already found the result. Authenticate the source using the agreed mechanism, validate integrity and replay protections, and correlate the event to the expected instruction. Check identifiers, amount, currency and destination against trusted records rather than allowing a callback to rewrite payment terms.
Persist the event durably before acknowledging receipt under the contract. Make acknowledgement fast enough for the partner’s timeout; perform longer work through a durable workflow. Repeated events should not trigger repeated credits, fulfilment or refunds. Use valid state transitions or source versions to prevent a late “processing” event from overwriting a confirmed completion. Where evidence conflicts, reconcile rather than trusting arrival order.
Make reconciliation part of recovery
Match the API instruction, core entry and relevant rail or provider outcome using their mapped references. Track missing debits, missing confirmations, duplicate references and amount mismatches. Each break needs an owner, age, next action and escalation route. For real-time services, exception handling should begin within the operational window the bank has defined, rather than waiting automatically for the next day.
An ODS is a query-only replicated data store. It can support reads and analysis, but a missing replicated record does not prove a posting failed. It must not post, reverse or replay a transaction. Recover the financial outcome through the authoritative systems and approved operational processes.
A reversal or compensation is a new controlled financial action. Link it to the original instruction, enforce its authority and duplicate controls, and retain the accounting evidence. It is not a technical rollback of a payment that may already have reached another institution.
Release evidence should include the uncomfortable cases
- Two identical requests reach different instances at the same time.
- The downstream debit commits, but the response is lost.
- The service commits locally, then crashes before event publication.
- A callback is duplicated, arrives late or conflicts with the current state.
- Failover occurs while an instruction remains uncertain.
- An old request returns after the short-lived idempotency record expires.
For each case, verify the financial entries and recovered outcome, not just the HTTP response. The bank should be able to explain why the instruction was applied once, rejected, or held for resolution—and identify the records supporting that conclusion.
Part 4 will turn these expectations into a broader testing and release approach, including abuse cases, contract compatibility, capacity and failover. Transaction integrity gives those tests a business target: the authorised instruction, its financial effect and the evidence must remain connected.
Continue with Learning
The response is missing. Should the bank send the transfer again? Practise recovery after a debit posts but its response disappears.
Sources & further reading
- RFC 9110 — HTTP Semantics, especially idempotent methods and 202 Accepted.
- Stripe — Idempotent requests (implementation example; behaviours are provider-specific).
- AWS Prescriptive Guidance — Transactional outbox pattern.
Put this perspective into practice.
Explore the concepts, make a decision and test what changes when the situation changes.
Topics: API Architecture, Banking Architecture, Inside the Banking Backbone, Operational Resilience, Perspective