iPay integration: where the payment flow breaks
The payment flow breaks not at the connection stage, but at the junction between the payment system and the order logic.
The customer paid, the money left, but the order in the database remained in the "awaiting payment" status — because the notification from the payment system didn't arrive, got lost in the queue, or arrived before the transaction was recorded. Then a chain begins: a repeated payment attempt, manual reconciliations, support requests.
The most common failure is desynchronization of payment statuses. Payment system webhooks arrive asynchronously, can be duplicated on retries on the sender's side, and get lost during network failures.
If the handler is not idempotent, the same payment is processed twice — this is a double charge, which the customer sees on their statement and demands back.
The reverse situation is no better: the order is paid, but the system doesn't know about it, the goods aren't shipped, and the payment eventually goes into a refund due to timeout.
A separate category is stuck refunds. A refund is initiated but not brought to a final status: the bank declined, the payment system didn't confirm, the status remained intermediate.
Without regular reconciliation with the transaction ledger, such payments accumulate and surface later in accounting.
All these failures are closed at the architecture level: idempotent webhook processing with a key based on the payment identifier, mandatory status reconciliation on a schedule as insurance against lost notifications, explicit states for refunds, and retries with a limit.
We break down how this is structured and what we build in at the integration stage so that the flow doesn't break in production.
What a correct payment gateway integration delivers
A correctly integrated payment gateway is not a "Pay" button, but a managed loop where every stage of a transaction is predictable and observable. Let's break down what measurable effects such an integration delivers and why they matter for business.
Share of successful payments. When the gateway correctly handles bank responses, retries on timeouts, and cancellation statuses, the share of successful payments grows: the customer does not leave because of an unclear error, and the payment is carried through to completion. This is a direct effect on revenue without attracting new traffic.
Time to funds crediting. Properly configured webhooks and confirmations reduce the time to crediting: money is reflected in the account at the moment of confirmation, not after manual verification. Accounting sees the current balance, not data with a delay.
Payment reconciliation. Automatic reconciliation matches gateway transactions with orders and the statement, eliminating manual investigation of discrepancies. Every payment has a clear status, and mismatches surface immediately, not at the end of the month.
Refund automation. Refunds and partial cancellations follow a predefined scenario: the system itself initiates the refund, records it in accounting, and notifies the customer. This removes the load from support and eliminates manual entry errors.
Failure class. Correct integration separates technical failures from customer declines: it is clear where the problem is on the bank's side and where it is in the payment scenario. This allows causes to be resolved quickly and prevents losing payments for no reason.
In sum, these effects deliver a predictable payment flow: fewer manual operations, fewer losses at every stage, a transparent picture of the money. Let's discuss your task — we will come back with an estimate and an integration plan.
iPay integration methods: comparing the options
The choice of integration method determines who is responsible for the payment flow: an external service, a ready-made module on the site's side, or your server-side code.
This affects the scope of work, the speed of launch, and how flexibly you can later change the logic — discounts, partial payments, recurring charges. Below are four real options that are chosen between in practice.
| Option | When it fits | Limitations |
|---|---|---|
| Ready-made payment module | A typical store on a popular platform, a standard "cart → payment" flow | The logic is hardcoded into the module: non-standard discounts, partial payments, and custom statuses will have to be worked around |
| Payment page | You need a fast launch, minimal development effort, and payment is handled on the service's side | The design and some steps are not under your control, and there is less data about the payer's behavior |
| Server-side API | Your own payment interface, subscriptions, holding, complex order logic | The full cycle is on your side: handling callbacks, idempotency, error parsing |
| Hybrid scheme | Some payments via the page, some via the API for specific scenarios | Two payment streams need to be consolidated into a single reporting and reconciliation process |
What matters on each path
A ready-made module and a payment page enable launch within days, but beyond that you run into someone else's logic.
The server-side API removes these constraints, but requires careful handling of confirmations: every notification is verified with a signature, repeated requests are processed idempotently, and the order status changes only after reconciliation with the payment service.
The hybrid scheme is a compromise for projects where typical orders go through the page, while subscriptions or pre-orders require the API.
We choose the option for your payment scenario, not the other way around: first we analyze the logic of orders, refunds, and statuses, then we fix the integration method.
Stages of iPay integration implementation on the website
Implementation of a payment module begins not with code, but with analyzing how money and statuses already flow through your service.
During the payment scenario audit, we examine the cart, checkout, user account, warehouse, and accounting: where an order is created, where it changes status, who learns about payment and when.
The output is a map of bottlenecks: duplicate orders when the form is resubmitted, orders without payment, stuck statuses.
Next, we design the payment flow scheme: who initiates the operation, where confirmation arrives, what happens when the bank declines, times out, or the payment page is closed.
We separately establish idempotency — a repeated request must not create a second order or charge the money twice.
- Payment scenario audit. We analyze the current payment steps, system roles, failure points, and accounting requirements for reconciliation.
- Payment flow scheme. We agree on a diagram: initiation, confirmation, refunds, cancellations, retries, notifications to the customer and manager.
- Setup and connection. We deploy the payment module, link it to the catalog and orders, and configure transaction logging.
- Exception handling. We define behavior for declines, timeouts, and amount discrepancies: the order is not lost, the status does not get "stuck," and the customer receives a clear message.
- Test runs. We run successful and unsuccessful payments, refunds, retries, and checkout load — verifying statuses in the application and in the payment system reports.
- Reconciliation and reporting. We configure transaction export so that accounting can match payments with orders without manual work.
- Handover to operation. We provide access credentials, support instructions, and the procedure for handling incidents, and we establish a change management policy.
After handover to operation, the payment module works as part of the service: payments go through, statuses match up, and support knows what to do when a failure occurs on the bank's side. Describe your task — we will get back to you with an estimate and a work plan.
Artifacts and documentation after integration
After the work is handed over, you are left not with a "folder of files" but with a working set that a new developer or contractor can use to maintain the payment module without us.
We document not only what was done, but also why exactly that approach was chosen — this eliminates half the questions during future enhancements.
- Integration diagram — payment flows from the cart to order confirmation, payment gateway invocation points, asynchronous notification handling, and signature verification procedure. The diagram shows exactly where the boundary lies between your application and the payment service.
- Module configuration — the list of environment parameters, separation of test and production environments, the list of access keys and their rotation rules. We separately note which values change when the domain changes or a new payment method is added.
- Reconciliation procedure — the procedure for matching transactions in the payment system's dashboard with orders in your database, the frequency, the list of discrepancies and actions for each type. This is what closes the question of "why the report shows one amount and the system shows another."
- Refund instructions — full and partial refunds, refunds initiated by the customer and by the store, crediting timelines, what to do if the payment service declines. With step-by-step actions in the admin panel.
- Incident troubleshooting — typical failures: payment went through but the order wasn't confirmed; double charge; stuck status. For each — how to diagnose via logs and what to do to avoid losing the customer.
- Payment module documentation — extension points, dependencies, update and rollback procedures, access rights requirements for employees.
- Acceptance checklist — a set of scenarios that are run before each release: successful payment, decline, refund, retry.
We hand over the set in your repository and as readable documents — not in chat messages and not in an engineer's personal notes. If the team already has its own documentation templates, we adapt the artifacts to them so as not to create a second standard.
Describe your task — we'll come back with an estimate and a plan, including the composition of the documents to be handed over.
Case study: how the share of successful payments grew after rework
The client — a subscription service with monthly charges — came with a problem: the share of successful payments held at 71%, and every fourth transaction required manual review.
Support spent 3-4 hours a day reconciling payments, accounting couldn't close the day without manual adjustments, and some customers left after the very first failed payment attempt.
What it was like before the rework
The integration with iPay worked in basic mode: a one-time payment without card saving, status confirmation only when the user returned to the site.
If the customer closed the page before the redirect, the payment hung in an undefined state — it was found manually during reconciliation.
Recurring subscription charges were triggered by a single request without failure handling, so a temporary bank decline immediately turned into a lost customer.
What was changed
Payment was moved to a scenario with card saving and tokenization — recurring subscription charges go through without customer involvement.
Payment status is now confirmed asynchronously via notifications from the payment gateway, rather than by returning to the site: the transaction state is recorded regardless of whether the user closed the page or not.
Automatic retries were added for soft declines with an increasing interval, and a separate branch for hard declines, where the customer is immediately offered to update the card.
A reconciliation panel was built separately: discrepancies between our database and iPay reports are highlighted automatically, and manual review remains only for disputed cases.
Metrics before and after
| Indicator | Before | After |
|---|---|---|
| Share of successful payments | 71% | 94% |
| Crediting time | up to 40 minutes | 1-2 minutes |
| Share of manual reviews | 26% | 3% |
| Recurring subscription charges | manual trigger | automatic |
Crediting time was reduced thanks to asynchronous confirmation — the status arrives almost immediately after the operation, rather than after reconciliation at the end of the day.
The share of manual reviews dropped severalfold: support switched from sorting out stuck payments to working with customers, and accounting closes the day without adjustments.
How is a hosted payment page different from a server-side API?
A hosted payment page is a hosted scenario: the user is redirected to the provider's domain, where they enter card details, complete 3-D Secure, and return to the site via a preconfigured return URL.
A server-side API works differently: we build the payment form ourselves, card data goes directly to the payment gateway over a secure channel, and on our side only the token and the transaction result remain. The difference lies in who controls each step of the scenario — the provider or our team.
A hosted payment page wins where speed of launch and minimal responsibility for sensitive data matter: compliance with payment standards for card storage falls entirely on the provider, and all we have to do is correctly handle the return and the webhook about the payment status.
The price is less control: the design is limited to a template, some scenarios (partial payment, repeat charges, custom receipts) have to be worked around, and any failure on the provider's side looks to the customer like "the site is down."
A server-side API gives full control over the payment scenario: custom fields, validation before submission, saved cards, recurring charges, a unified design with the rest of the site.
But with control comes responsibility — for error handling, retries on timeout, request idempotency, and protection against double charges when the connection drops.
This is also where the main support burden lands: the more steps we build ourselves, the more points of failure and user questions there are.
In practice, the choice is rarely binary. For a quick launch and simple one-off payments, a hosted page solves the task in a matter of days. For subscriptions, marketplaces, and complex refund logic, a server-side API pays off because it removes manual operations from support.
We analyze your payment scenario and tell you straight where a hosted solution is sufficient and where it will start creating manual work.
Technical concerns before starting work
Before starting the iPay integration, the customer usually asks four questions: where to test the scenarios, what happens if the connection drops, how the keys are stored, and whether it is possible to switch without stopping sales. Below are short answers, each of which we address at the design stage, not after launch.
Can payments be tested without touching real cards?
Yes. We set up a separate test environment with the iPay sandbox: we run a successful payment, a bank decline, a refund, a partial refund, and a timeout.
Test keys live separately from production keys, and the environments do not overlap — the risk of an accidental charge is eliminated.
What happens if a payment is interrupted midway?
We make processing idempotent: a repeated request with the same identifier does not create a second charge. Retries follow an increasing delay, and the order status is verified against iPay with a separate request — the customer sees the correct state even on an unstable network.
How are keys and access protected?
We store secret keys in a secure vault, not in code or configuration files in the repository. Only the payment service has access to them, with network restrictions. Request signatures are verified on our side, so a payment notification cannot be forged from the outside.
Is it really possible to switch to iPay without downtime?
Yes, we build the migration through parallel operation: the new environment accepts payments, while the old one remains available for unfinished orders. Traffic switching is controlled, with the ability to roll back with a single command. Sales do not stop either during testing or at the moment of switching.
If any point needs a breakdown for your specific scenario — describe the task, and we will come back with an estimate and a work plan.
Let's discuss your iPay integration task
To make the estimate accurate rather than an "average market" figure, we need input on your setup. Describe the task — we'll come back with an implementation plan and timelines by stage.
What we clarify before starting iPay integration:
- Which payment methods are needed: cards, one-time payments, recurring subscription charges, refunds and partial refunds.
- Where the order currently happens: your own cart, CRM, billing or accounting system — and how it passes payment statuses.
- How the customer account is set up: whether you need payment history, card binding, one-click repeat payment.
- Which notifications should go to the customer and your team: emails, messenger messages, statuses in the admin panel.
- Security and access requirements: which employees can see payments, whether an action log is needed.
- Whether there is a test environment and how quickly iPay account access can be obtained.
As a result, you receive a work estimate broken down by stage, an implementation plan with the connection order and checkpoints, as well as a payment processing scheme: from order placement to confirmation and refund. Separately, we record what we do on your side and what we cover ourselves.
If some of the input isn't gathered yet, that doesn't block the start. We'll review the current order logic, propose a working option and clarify the details along the way.
Describe the task in any convenient form: a link to the site, a description of the payment process and your preferences on timelines.
