API Gateway Design Patterns for Financial Services

Every fintech platform eventually needs an API gateway. Myles Ndlovu has designed API layers for payment systems where reliability, security, and performance aren’t negotiable — they’re the product.

Why You Need an API Gateway

Without a gateway, every backend service handles its own authentication, rate limiting, logging, and error formatting. This leads to inconsistency, duplication, and security gaps.

An API gateway centralises cross-cutting concerns:

Client → API Gateway → Backend Services
              │
              ├── Authentication
              ├── Rate Limiting
              ├── Request Validation
              ├── Logging & Monitoring
              ├── Request Transformation
              └── Circuit Breaking

Authentication Patterns

API Key + Secret

Simple and widely understood. The client sends an API key in the header, and the gateway validates it.

Best for: Server-to-server integrations where the caller is a trusted partner.

OAuth 2.0

For user-facing APIs, OAuth 2.0 provides delegated access. The gateway validates access tokens and extracts user identity and permissions.

Best for: APIs accessed by third-party applications on behalf of users.

mTLS (Mutual TLS)

Both client and server present certificates. The gateway validates the client’s certificate before allowing the request.

Best for: High-security financial APIs where you need strong caller identity verification.

Layered Authentication

In practice, financial APIs often combine methods:

1. mTLS at the transport layer (is this a known client?)
2. API key at the application layer (which integration is this?)
3. Request signing (has the request been tampered with?)

Request → mTLS Check → API Key Validation → Signature Verification → Backend

Rate Limiting

Rate limiting protects your services from abuse, whether intentional (attacks) or accidental (a partner’s buggy integration that sends 10,000 requests per second).

Token Bucket Algorithm

Each client gets a bucket of tokens. Each request consumes a token. Tokens refill at a fixed rate. When the bucket is empty, requests are rejected.

Client A: 100 tokens, refills 10 per second
  - Can burst up to 100 requests instantly
  - Sustained rate: 10 requests/second

Sliding Window

Track request counts in time windows. More precise than fixed windows (which allow bursts at window boundaries).

Different Limits for Different Endpoints

Not all endpoints are equal. A balance check is cheap; a payment initiation is expensive. Set limits accordingly:

rate_limits:
  /v1/balance:
    requests_per_minute: 300
  /v1/payments:
    requests_per_minute: 60
  /v1/accounts:
    requests_per_minute: 120

Rate Limit Headers

Always return rate limit information in response headers so clients can self-regulate:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1679529600

Request Validation

Validate requests at the gateway before they reach backend services:

• Schema validation: Does the request body match the expected JSON schema?
• Type checking: Are amounts numbers? Are dates valid ISO strings?
• Business rules: Is the amount positive? Is the currency code valid?
• Size limits: Reject oversized payloads before they consume backend resources

Rejecting invalid requests early saves backend processing and provides consistent error responses.

Circuit Breaking

When a backend service is failing, the gateway should stop sending requests to it rather than cascading the failure.

The circuit breaker pattern:

1. Closed (normal): Requests flow through. Track failure rate.
2. Open (failing): Failures exceed threshold. Return errors immediately without calling the backend. Start a timer.
3. Half-open (testing): Timer expires. Allow one request through. If it succeeds, close the circuit. If it fails, reopen.

Failure rate > 50% over 10 requests → Open circuit
Wait 30 seconds → Half-open
Test request succeeds → Close circuit

Request Transformation

The gateway can transform requests between external and internal formats:

• Version mapping: External API v1 maps to internal service contracts
• Field renaming: External account_number maps to internal accountId
• Enrichment: Add internal metadata (request ID, timestamp, gateway region)
• Protocol translation: REST to gRPC, JSON to Protocol Buffers

Observability

Every request through the gateway should generate:

• Access logs: Timestamp, client ID, endpoint, response code, latency
• Metrics: Request rate, error rate, latency percentiles, per-client and per-endpoint
• Traces: Distributed trace ID propagated to backend services

This data is essential for debugging, capacity planning, and SLA reporting.

API Versioning

Financial APIs must be backward-compatible. Partners integrate against your API and expect it to keep working. Versioning strategies:

• URL versioning: /v1/payments, /v2/payments — simple, explicit
• Header versioning: Api-Version: 2 — cleaner URLs, less visible
• Content negotiation: Accept: application/vnd.myapi.v2+json

Whatever you choose, commit to supporting old versions for a defined period and communicate deprecation timelines clearly.

Build or Buy

For early-stage startups: use an existing solution (Kong, AWS API Gateway, Cloudflare). Building a custom gateway is engineering effort that doesn’t differentiate your product.

For mature platforms with specific requirements: a custom gateway gives you full control over authentication, routing, and transformation logic. But only build one when off-the-shelf solutions genuinely can’t meet your needs.

The gateway is the front door to your financial platform. Make it secure, observable, and reliable. Everything downstream depends on it.