Payment Architecture Evolution: From Client-Side Risks to Reliable Webhooks

Now imagine you are being asked to implement a payment gateway in the product. You start thinking: how do I implement it, and what architecture should I use?

Before moving to the architecture, let's understand the components you need to implement:

1. A mechanism to calculate the amount and generate order details
2. A mechanism to accept payment from the user
3. A mechanism to update the payment status and take further action based on the business requirement

Architecture 1

Architecture 1 — Payment Architecture

In this architecture:

• We are calculating the amount on the client side
• We are relying on the client to tell the server about the payment status

Risks

1. The amount can be manipulated easily using DevTools
2. Credentials are exposed on the client side — sensitive credentials
3. Fake API calls can update payment status on the server

Architecture 2

We moved the amount calculation and order generation to the server side.

Architecture 2 — Payment Architecture

This solved risk one and two — amount manipulation and credentials exposed on the client side — but we still have risk three.

The issue with risk three is when the user paid successfully and closed the browser immediately.

It results in scenarios where payment succeeds but the user never gets registered, which increases customer support tickets and can damage the business reputation.

Architecture 3

In this architecture, we introduce the webhook provided by the payment gateway to get the status of payments — success, failed, or dropped — directly from the provider's server, removing the dependency on the client for this purpose and solving Risk 3.

Architecture 3 — Payment Architecture

A few things to keep in mind:

• Payment status values differ from provider to provider
• We need to verify the source of the webhook using the webhook signature before moving forward, so only legitimate requests can update the database

So, we need to ask our server for the payment status after the payment is completed on the client side.

We can use methods such as short polling, long polling, server-sent events, or WebSockets.

What you choose depends on the business requirements and needs.

Assumption: In this system, we are relying on the payment gateway server to send updates for all payments, and on our server remaining up always.

Architecture 4

Architecture 4 — Payment Architecture

To solve the assumption of Architecture 3, we add another component: a reconciliation job. It runs at a regular interval to check payment status for pending records over a specific period of time, and updates our DB if the status does not match.

The interval at which the reconciliation job runs, and the period of time for which DB records are checked, are decided based on business requirements.

It calls the payment gateway API to verify or match the payment status.

So, we choose the architecture based on our project and business requirements — not Architecture 4 always.

How the Architecture Evolved at Internware during my tenure there as a backend engineer

When I joined Internware, they were following Architecture 1. First, we moved to Architecture 2 by moving the amount calculation logic and order generation to the server side.

Gradually, we updated it to Architecture 3 because we were getting so many queries that the user paid for the event but was not registered on our platform.

This suited our requirements properly, and we did not need to move to Architecture 4 without facing that problem. At our scale, it was not required.

Stay tuned for coming blogs — follow me on X and LinkedIn, or read my other blogs.