Payment System Integration for Web Products: Acquiring and Billing via Webhooks, Idempotency, and PCI DSS

A modern web product—an online store, SaaS platform, marketplace, or corporate portal—is unthinkable without payment acceptance. However, simply attaching a payment gateway is not enough. Three components are critically important: reliable transaction status notifications via webhooks, safe handling of duplicate requests using idempotence, and compliance with the PCI DSS standard that protects cardholder data. Ignoring any of these elements risks double charges, payment failures, or leakage of sensitive information. In this article, we’ll look at how to build a payment integration architecture based on these principles and what technical solutions help implement such scenarios in projects of any complexity built on web development.

The Role of Webhooks in Modern Payment Integrations

The traditional approach—a customer clicks "Pay", the site sends a request to the payment gateway API, receives a synchronous response, and immediately updates the order status. In practice, this scenario often breaks: network timeout, a frozen browser, a connection drop after the funds are deducted. Without a reliable asynchronous mechanism, you risk not recording a successful payment, leading to losses or a negative user experience. This is where webhooks come into play—HTTP callbacks that the payment system sends to your endpoint when the transaction status changes.

How Webhooks Work in Acquiring

Typical flow: after the bank confirms authorization, the gateway asynchronously sends a POST request to a predefined URL of your application. The request body contains the order ID, amount, status, and other parameters. Your server must correctly process this callback, update the order state, and respond with HTTP 200 within a short timeout. If no response is received, the gateway retries with increasing intervals—for example, after 1, 5, 15 minutes.

When building a reliable webhook receiver, several factors should be considered:

• Signature verification. Every incoming request must be authenticated. Most gateways sign the body using HMAC and a secret key. Ignoring verification opens the possibility of fake notifications—an attacker could send a request claiming a successful payment and deceive the business logic.
• Resilience to network failures. The webhook endpoint must be highly available. A server crash during retry leads to "stuck" orders and manual reviews. Therefore, the endpoint is placed behind a load balancer with fast recovery, and business logic is executed asynchronously via a message queue.
• Protection against duplicate processing. Since the gateway may re-deliver the same webhook (network duplicates), it is critical to implement idempotence—more on this later.
• Delivery tracking. Storing logs of all incoming webhooks with their IDs helps investigate incidents and reconcile discrepancies with the acquirer's reports.

Implementations of such callbacks are especially in demand when creating SaaS applications, where each successful transaction must instantly activate access to the service or extend a subscription.

Idempotence in Billing: Why a Retry Should Not Duplicate Charges

In distributed systems, network errors and timeouts are inevitable. The classic scenario: an application sent a request to charge funds but received no response. It's unclear whether the operation was executed on the bank's side. An automatic retry without idempotence guarantees can double-charge the customer—a critical reputational and financial risk. Idempotence means that a repeat request with the same key leads to the same result as the first successful one, with no side effects.

Idempotency Key: How It Works

Payment APIs typically support an idempotency key parameter—a unique identifier passed in the header or request body. The internal logic of the gateway is: upon receiving a request with a new key, the operation is executed normally, and the key and result are saved. If a repeat request with an already used key arrives within a certain window (often 24–72 hours), the gateway returns the saved result without initiating a new charge. Thus, a client that received a network error can safely retry the request with the same key.

From a developer's perspective, two rules are important:

1. Generate the key on the client side (your backend) before sending the request. This is typically a UUID v4, unique for each logical operation. For instance, a key is created for an order payment attempt and tied to that order rather than to individual HTTP calls.
2. Store the key both locally and use it for deduplication at your own level. Even if the gateway correctly handles duplicates, your own service should not resend a request with the same key if the first one already led to a successful result. Otherwise, you risk a validation error from the gateway or, worse, a duplicate charge if the gateway does not support idempotency.

In a billing service for CRM systems, where customers pay invoices automatically, idempotent delivery ensures that the invoice is not paid twice in the event of a network failure. Similarly, in web applications with payment forms, this eliminates the classic double-click error.

Idempotency and Webhooks

The idempotency key is also useful on the webhook receiver side. The payment gateway may deliver the same notification multiple times. The handler should be able to recognize a duplicate by notification ID (typically the id field in the webhook body) and skip reprocessing if the order status has already moved to a final state. This way, we turn a non-idempotent status change operation into an idempotent one: the transition to "paid" occurs only once, and upon receiving the same event again, simply returns a 200 without further action. When custom-designing cloud development systems, the ESK Solutions team initially builds such architecture to eliminate business risks.

Compliance with PCI DSS: Minimum Technical Requirements

Any organization that accepts credit card payments must comply with the Payment Card Industry Data Security Standard (PCI DSS). For a web product, this means a set of measures protecting cardholder data throughout the entire path: from entry to transmission and storage. Full audit compliance requires considerable resources, but modern architectural practices help significantly reduce the scope of responsibility by delegating sensitive operations to the payment gateway.

Minimizing Contact with Card Data

The most reliable way not to violate PCI is to never see card numbers. This can be achieved through several approaches:

• Hosted Payment Page. The payment form is rendered on the gateway's side; card data is entered on its secured page. Your site only redirects the user and receives a transaction token. This approach minimizes the burden on your application but may offer less control over the user interface.
• Iframe or Secure Fields. The gateway provides a JavaScript component that is embedded in your page and independently handles the card input fields. Data does not leave the browser directly to the gateway, and your server receives only a token. This preserves UI customization with a low level of compliance burden on your end.
• Server-side card tokenization. Card details are accepted on your backend but immediately, without storage, sent to the gateway API and replaced with a token. This option requires the highest level of PCI DSS compliance, up to full environment certification, and is unnecessarily complex for most projects.

In custom development, we most often recommend the component approach (Secure Fields), which combines flexible UX and security. Such integration is possible in any web projects regardless of the stack — React, Vue, server-side rendering in PHP or Python.

Infrastructure Aspects of PCI DSS

Even if you do not handle card data directly, the infrastructure serving the payment page and receiving webhooks must meet basic security requirements. This includes protecting the network perimeter, regular software updates, access control, logging, and monitoring. By deploying the solution in a PCI-certified cloud environment (for example, using cloud services with the appropriate certification), you can get a significant portion of the requirements 'out of the box'—isolated networks, encryption at rest, DDoS protection. This is especially relevant for high-load billing systems where both high availability and security auditing are important.

Frequently Asked Questions

What payment methods can be integrated into a web product?

Modern gateways allow you to accept bank cards (Visa, Mastercard, Mir), electronic wallets (YooMoney, QIWI, WebMoney), SberPay, the Faster Payments System (SBP), as well as international options like PayPal or Stripe. The choice of specific methods depends on the geography of your customers and the business model. Integration is often done through aggregators that provide a single API for the entire range, simplifying connection. For subscription services, automatic recurring payments are important.

What is idempotency and why is it needed in payment integration?

Idempotency ensures that a repeated request with the same unique key will not result in a duplicate operation. In the payment context, this means that if a network error occurs during a charge and the application retries the request, the money will be charged only once. Idempotency protects against both double charges and lost transactions, and is a mandatory practice for any financial API.

How to ensure the security of cardholder data in a web application?

The best approach is to never store or process full card numbers, delegating sensitive data to the payment gateway through hosted forms or secure fields. Your server should only work with tokens that identify the card. It is also necessary to use HTTPS, verify the signature of incoming webhooks, and regularly update dependencies to address vulnerabilities. The infrastructure must comply with basic PCI DSS requirements even with a minimal scope.

Can I use ready-made payment modules for popular CMS?

Yes, for platforms such as 1C-Bitrix, WordPress (WooCommerce), OpenCart, there are ready-made plugins from popular payment aggregators. They significantly speed up deployment, but it is important to check their security, keep them updated, and understand exactly how they handle callbacks and store tokens. Custom web applications require individual integration development, which gives full control over architecture and security.