Step 6: Detailed Component Design

Now we’ll explore key components in detail.

6.1 API EndPoints

• POST /v1/charges – create a charge
• GET /v1/charges/{id} – retrieve charge status
• POST /v1/charges/{id}/refund – create a refund (or /v1/refunds separate)
• GET /v1/balance – get current merchant balance
• GET /v1/transactions?filter... – list transactions (possibly paginated, etc.)
• etc. (Also endpoints to save cards, manage customers, etc.)

These all funnel through the gateway to appropriate internal handlers.

6.2 Payment Service (Core Orchestration)

This service is the brain of the operation. We can consider it as a payment orchestration layer that coordinates between the database, external services, and internal auxiliary services.

Internal Structure: We could design the Payment Service itself in a modular way or even as multiple microservices. For instance, some organizations would split the responsibilities: an Orchestrator service, a Connector service for external calls, etc. For clarity, we’ll discuss it as one service with distinct sub-components/tasks:

• Request Handler: This is the part that receives the API call (once passed through the gateway). If using a web framework, this is the controller that handles /charges. It calls other components or modules to perform the steps like idempotency check, etc. It can use a thread pool or async event loop to handle many concurrent requests.
• Idempotency Handler: When a request with an idempotency key comes in, the service will check a fast storage (could be an in-memory cache or a Redis cluster, or our DB) to see if the key exists. We might choose to use Redis for quick global lookup of idempotency keys (with entries expiring after, say, 24 hours or 7 days to limit storage). Alternatively, a DB table with a unique index on (merchant_id, idem_key) could serve the same purpose – insertion will fail if duplicate (so we know it’s a retry) and we can then fetch the result.
• Business Logic: The service implements rules like “is the currency supported?”, “does the amount exceed the merchant’s processing limit?”, “is this merchant active?”, etc., to validate before processing. Then it proceeds through the steps: contact fraud service, vault, etc. If any step returns an error or disallows, it handles that by failing the transaction with appropriate status.
• External Communication: The Payment Service will call out to the external payment network via an integration module. Likely we’ll implement this with robust HTTP client or SDK provided by the acquirer. We must handle timeout cases and error responses carefully (with retries or marking uncertain states). Possibly use a library or a separate thread for external calls so as not to block the main thread.
• Database Operations: Using a Data Access Layer, the Payment Service will create/update records. For example, when a charge request comes in, we might immediately create a transaction record in DB with status “pending” (to reserve an ID and have a record in case of failure mid-way). Then after external auth, update it to “succeeded” or “failed”. This helps if something goes wrong after external call – we still have a record of the attempt. All DB operations should be done in a transaction to ensure consistency.
• Concurrent Handling: The Payment Service must be thread-safe and handle possibly the same customer or merchant doing multiple transactions in parallel. Generally, each request is independent, but something like updating a merchant’s balance concurrently could cause race conditions. In a relational DB, we can rely on row-level locking – e.g., updating a balance with balance = balance + X safely within a transaction. Or we use a separate ledger that just inserts entries (which avoids contention entirely). We will want to avoid coarse-grained locking in the service; better to let the DB handle it or design the data model to minimize conflicts.

Data Model & Storage Choice: For core transactional data, a relational database is a solid choice due to its ACID guarantees. Financial transactions require atomicity and durability. A SQL database (like Postgres or MySQL) can enforce constraints (like unique idempotency keys, referential integrity between a charge and a refund record, etc.) and can do multi-row transactions easily.

Synchronous vs Asynchronous Processing: The Payment Service does most steps synchronously to provide a result in the API response. We choose sync for the primary flow because merchants (and customers) expect an immediate answer to a payment attempt. However, behind the scenes we use asynchronous processing for things that need not block the customer’s request: emailing receipts, notifying external systems, etc., are done async via events after the main flow commits.

Card Vault Service: Let’s detail this component since it’s critical for security:

• It has its own secure database (often an HSM – Hardware Security Module – or an encrypted store) where card data is stored. Data is encrypted with strong keys; even DBAs can’t read it directly. The service when storing a card will generate a random token (maybe a UUID or Stripe uses a format “card_abcdef12345” for example) and associate it with the encrypted data. Only the vault service can decrypt.
• When retrieving, the Payment Service provides the token and some auth (the vault will ensure the requesting service is allowed and perhaps that this token belongs to that merchant or is globally unique anyway). The vault returns the card info (PAN: Primary Account Number, expiry, maybe cardholder name if stored).
• This service should be minimal: store and retrieve. It might also support deleting a card (if a customer wants their data removed).

External Payment Integration Service:

• If we design this as a separate microservice (say call it “Acquirer Connector”), it would abstract the details of talking to different payment networks. It might have methods like authorizeCard(cardData, amount, merchantAccount). Under the hood, it formats the request according to the acquirer’s API spec, handles sending it over, and parses the response. If we connect to multiple providers, this service could have a routing logic: e.g., if card is Amex, maybe use a different processing path. Or if region is EU, use our EU acquirer vs US acquirer. That logic can be encapsulated here, keeping Payment Service simpler.
• However, adding an extra network hop (Payment Service -> Connector Service -> external) might add a bit of latency. It’s a trade-off: modularity vs latency. If in the same data center, an RPC call is maybe 1-2ms, which is negligible compared to the external call. So it’s fine.
• This service should also implement retry logic for external calls carefully. If a call times out, should it retry? It must be careful not to double-charge. Typically, you’d only retry if you are sure the first attempt didn’t go through. Often better approach is to query the status (if the API offers that) rather than blindly resubmit. Some acquirers have an operation like “inquire by transaction idempotency” to see if a transaction was processed. If not, then you can retry. If no such API, perhaps rely on our idempotency and unique transaction IDs such that the acquirer would reject a true duplicate anyway. We might implement limited retries for transient network errors. Also use a circuit breaker: if the acquirer’s endpoint is down, after a few failures, stop sending more for a short time, to allow fallback or at least not waste time.
• If an external integration needs to be asynchronous (some gateways might do callback later), then this service would handle that complexity (storing a pending state and awaiting a callback or pulling a queue).