Skip to content
Banking & Finance

Secure Banking API Development, Part 1: Design the Controls Before Writing Code

Start the banking API lifecycle with a reviewable design: business authority, data boundaries, transaction outcomes, secure failure and evidence for delivery.

Perspectives · Secure Banking API Development · Part 1

A channel team asks for a payment API. Its first proposal has a request body, a gateway route and a success response. Three decisions are still open: who may debit the account, when a transfer can be called complete, and what happens if the response disappears after posting.

Those are design decisions. Agreeing them before development gives security, operations and testing teams something concrete to verify. This first article sets out that design baseline. Later parts will follow the API through implementation, testing, release, operation and retirement.

Start with the banking action

Write a one-sentence purpose: who requests what, against which record, and with what permitted effect? Separate enquiries, commands and events. Name the business owner, the system that applies the effect and the team that resolves an uncertain outcome. Record whether the consumer is a customer channel, internal workload or partner, since the trust and support arrangements differ.

For a transfer, the middleware can validate and route a request. The authorised banking service decides whether the debit can proceed and establishes the outcome. For a read, a replicated ODS can reduce load when its freshness is acceptable. It remains query-only; it does not post, reverse or repair a transaction.

Define authority at three levels

Authenticate the caller, then authorise the operation, the specific object and the fields involved. A token with a transfer scope does not grant access to every debit account. Check the customer’s entitlement to the account and the authority for this transaction, including any required limits or approvals. OWASP separates object, property and function-level authorisation risks for good reason. [1]

At design review, draw the path across channel, gateway, integration and source systems. Mark where TLS terminates, where identity is re-established and how delegated customer context is validated. For OAuth integrations, specify issuer, audience, scope and expiry validation, and choose an appropriate client authentication and token protection model. RFC 9700 explains audience restriction and sender constraint. [2]

Decide how credentials are issued, rotated and revoked before the first integration. A partner credential should have a defined scope and owner. A design that works only until certificate renewal or failover is incomplete.

Design the data and response contract

Use a versioned interface description such as OpenAPI for HTTP APIs, then add the business rules it cannot establish by schema alone. Define amount precision, currency, identifiers, field ownership, redaction and the meaning of each status. Validate request and response fields explicitly; avoid passing a core system record through simply because it is available. [5]

Decide what each consumer needs to see. Avoid exposing raw internal errors or sensitive customer data. RFC 9457 provides a common structure for HTTP error details; the bank still needs stable error types and safe messages. Document which conditions can be retried, which require a status check and which require a corrected request. [4]

Make a lost response part of the design

In a fictional transfer API, a request is durably accepted and given a reference. An HTTP 202 response can communicate acceptance while processing continues; it does not confirm that the transfer posted. Agree how the client checks status and which record supports the final outcome. [3]

A correlation ID helps trace a call. An idempotency key identifies a permitted repeat under a defined contract. A business reference follows the transfer through processing and reconciliation. The design may relate these identifiers, but each must have a clear scope. Enforce duplicate protection at the point controlling the financial effect, including concurrent retries and alternate routes. Define the retention window and reject incompatible reuse of a key.

If the response is lost after a debit may have posted, recover the original outcome through the authoritative lookup or reconciliation path. A late event or an absent replicated record cannot, on its own, establish failure. Avoid accepting a second financial instruction as an automatic response to uncertainty.

Set limits and decide how the API fails

Specify a journey deadline, dependency timeouts, payload and page limits, concurrency budgets and consumer quotas. Agree which layer owns retries so multiple layers do not amplify load. Define what must stop when a dependency cannot establish authorisation or a financial outcome, and which noncritical reads may degrade safely. Exercise these choices during peak, batch and failover testing.

Record what operations must be able to see: safe correlation, business outcomes, tail latency, queue age and repeated failures. Mask unnecessary personal data and secrets. Tie each alert to an owner and a response, and include certificate expiry and deprecated-route traffic in the operational design.

The design evidence to take into implementation

DecisionEvidence to retainFirst test to plan
Business authorityAction, source of truth, accountable ownerA caller with valid credentials requests an unauthorised account.
Contract and dataVersioned schema, field rules, status and error meaningsA payload is structurally valid but violates a business rule.
Repeat safetyKey scope, expiry and authoritative recovery pathThe service posts the transfer but the response is lost.
Capacity and failureDeadline, quota and dependency behaviourA downstream service slows during peak demand.
LifecycleNamed consumers, compatibility policy and retirement planAn old client uses the prior version during recovery.

The end-to-end series

PartFocus
1 · This articleDesign decisions, trust boundaries and review evidence
2 · PlannedSecure implementation: identity, authorisation, validation and secrets
3 · PlannedTransaction integrity: idempotency, asynchronous flows and reconciliation
4 · PlannedTesting and release: abuse cases, contract checks, load and failover
5 · PlannedOperations and retirement: monitoring, versioning, migration and closure

For the lifecycle context, see When Old APIs Stay Live. Part 2 will take the design baseline into code and gateway policy.

Continue with Learning

The token is valid. Can this account be debited? Review a fictional transfer API before it enters development.

Sources & further reading

  1. OWASP API Security Top 10
  2. RFC 9700 — OAuth 2.0 Security BCP
  3. RFC 9110 — HTTP Semantics
  4. RFC 9457 — Problem Details for HTTP APIs
  5. OpenAPI Specification
Learn the topic

Put this perspective into practice.

Explore the concepts, make a decision and test what changes when the situation changes.

Topics: , , , ,

Leave a Reply

Your email address will not be published. Required fields are marked *

An invitation to contribute

Everyone has a perspective worth hearing.

A lesson from your profession. An experience that changed your mind. A question you think deserves a better conversation.

Share your perspective