Webpay integration: where payments break in a mobile app
Payments in a mobile app break not at the charge stage, but at the junction between the app, the payment form, and the backend.
The classic scenario: the user paid, returned from the payment form — but the order in the app is still "awaiting payment." The reason is that the return from the form and the payment confirmation from the gateway arrive via different paths and at different times, and the app learns about the success earlier than the backend receives the confirmation. If this moment is not handled, a desync occurs between the order and payment statuses.
The second common class of failures is stuck transactions. The user closed the form, lost network connectivity, minimized the app — and the payment remained in an intermediate state without a final status.
Without periodic reconciliation with the gateway, such operations pile up, support receives requests like "the money was charged, the order wasn't created," and accounting gets discrepancies. A separate pain point is retries: the user taps "pay" again, and a duplicate appears.
The third layer is the return from the payment form itself. On some devices and OS versions, the app is unloaded from memory during payment, and the return leads not to the right screen but to the home screen. The user assumes the payment didn't go through and leaves — even though the payment was successful.
All three failures are treated at the architecture level: idempotency keys on payments, status confirmation only from the gateway rather than from the app, background reconciliation of stuck operations, and correct handling of the return.
Below we break down how this is closed in Webpay integration — from the status schema to handling interruptions.
What changes after a correct payment gateway integration
A correct payment gateway integration changes not the "beauty" of the payment screen, but the behavior of the entire funnel.
The share of successful payments grows because the application correctly handles the user's return from the bank window, re-requests the status instead of blindly trusting the response, and does not lose the payment when the connection drops mid-scenario.
Order confirmation comes from the gateway, not from the client, so the order does not "hang" in an undefined state.
Separately, a whole class of failures goes away — the kind usually blamed on "fussy users": double charges when the button is pressed again, payments without confirmation when the window is closed, lost notifications when switching between the app and the bank.
Each such case means not only a refund, but also a support request, manual reconciliation, and lost trust. When the payment state is determined by the status from the gateway rather than by the fact that a button was pressed, these failures simply stop occurring.
Payment conversion is a consequence of predictability. The user sees a clear result: the payment went through — the order is confirmed; the payment did not go through — it can be retried without the risk of paying twice. The less uncertainty at this step, the higher the share of those who make it to the end.
We examine the payment scenario in full — from choosing a method to confirming the order — and close exactly those spots where successful payments are lost. Describe your task, and we will come back with an estimate and a work plan.
Connection Methods: Payment Form, SDK, Direct Call
There are three fundamentally different paths: a ready-made payment form, a mobile SDK, and a direct call to the payment interface.
The choice is determined by how deeply payment is embedded in the application's flow and who is responsible for the interface — the payment provider or your team.
| Option | When it fits | Limitations |
|---|---|---|
| Payment form | Quick launch, standard payment for a product or subscription | The interface and logic are handled by the provider, customization is minimal |
| Mobile SDK | In-app payment, a native screen and saved cards are needed | Requires updating the app when changes occur on the provider's side |
| Direct call | Your own payment interface, non-standard scenarios, marketplace | All status, retry, and error logic is on your side |
Payment form
This is the most predictable option: the app opens a ready-made payment screen, and the provider takes on all status parsing, retries, and errors.
It fits when payment is a separate step rather than part of a complex flow, and when launching quickly matters more than controlling every detail of the interface. There is one limitation: you accept someone else's screen logic as is.
Mobile SDK
The SDK provides a native payment interface inside the app and access to saved cards — conversion on repeat purchases is noticeably higher than when redirecting to an external form.
The price is being tied to the SDK version: when changes occur on the provider's side, you have to update the app, not them. For recurring payments and subscriptions, this is usually justified.
Direct call
A direct call to the payment interface gives full control over the payment screen and allows embedding it into any non-standard scenario — partial payment, split between recipients, custom retry logic.
In exchange, your team is responsible for handling statuses, request idempotency, and parsing declines. This path is chosen when ready-made options do not cover the business logic.
In practice, the options are often combined: the form for one-time purchases, the SDK for subscriptions, the direct call for specific scenarios. Describe how payment works in your application, and we will get back to you with an estimate and a plan for each path.
Implementation stages: from current payment audit to handover
Implementing a payment gateway is not "connecting a payment button," but building a chain from the cart to order confirmation so that no scenario loses money or leaves a customer with a stuck payment.
We work in a fixed sequence: each stage ends with an artifact that can be verified, not a promise that "everything is ready."
- Audit of current payment. We analyze how money flows now: which payment methods are enabled, where the transaction is created, who and when receives confirmation from the bank, how declines and refunds are handled. The output is a map of current scenarios with bottlenecks: duplicate orders, lost payments during connection drops, manual reconciliations.
- Integration scheme. We design the payment flow: the moment the transaction is created, redirect or embedded form, points of return to the app, handling of asynchronous notifications from the gateway. We define what happens when the app is closed midway through payment and how the order is reconciled with the actual transaction status.
- Setup and connection. We configure environments, keys and signatures, connect the app to the gateway, and run test payments in the sandbox. We separately check refunds and retries — this is where amounts and statuses most often diverge.
- Scenario verification. We run the full set: successful payment, bank decline, insufficient funds, timeout, repeat payment for the same order, refund. Each scenario — with the expected interface behavior and a record in the system, so support sees the history instead of guessing.
- Documentation. We describe the flow scheme, the list of transaction statuses, the incident triage procedure, and the points to look at when there is a discrepancy. The document stays with your team — a new developer gets up to speed without secondhand explanations.
- Solution handover. We hand over the configured integration, access credentials and instructions, and together walk through one real payment from start to finish. After handover, your team can change pricing and payment methods without affecting the transaction logic.
Describe how payment is set up now — we will come back with an estimate and a plan for these stages.
What the client receives: configuration, diagrams, regulations
We hand over not "access to a dashboard," but a working system: gateway configuration, payment flow diagrams, access rules, and incident response regulations. Below is what exactly stays with your team after launch.
- Gateway configuration — merchant parameters, binding terminals to payment scenarios, retry and timeout settings, separation of test and production environments.
- Payment flow diagrams — how a single-stage and two-stage payment works, where holding is performed, at what point an order is considered paid, and how refunds are processed.
- Access policies — roles for developers, support, and finance, restrictions on refunds and manual operations, key rotation procedures.
- Order state handling — a mapping table of gateway statuses and statuses in your system, including intermediate and disputed cases.
- Incident troubleshooting regulations — a step-by-step procedure for a failed payment, a stuck transaction, and a discrepancy in amounts, with responsible parties and response times specified.
- Team documentation — instructions for integrating new scenarios, a payment acceptance checklist, and a description of typical errors with their causes.
- Verification scripts — a set of test scenarios that your team uses to verify payments itself after any changes to the application.
Each artifact is tied to a specific action: settings — to change behavior without code edits, diagrams — so a new developer understands the flow within a day, regulations — so an incident is handled step by step rather than from memory. Describe your task — we will come back with an estimate and a work plan.
Case study: how we reduced the share of failed payments in an app
The client — a delivery service with an iOS and Android app — came with a specific pain point: the share of failed payments held steady at 18-20%, and the peak of declines fell during the evening hours when the load is at its highest.
The user tapped "Pay," got a timeout or an error, no money was charged, and the order was not placed. Some customers went to support, while others simply closed the app and never came back.
What it was like before integration
Payment went through a single gateway with synchronous confirmation: the app waited for a response from the payment service and only then displayed the order status.
During network slowdowns, the request hung until timeout, and a retry created a second payment — which had to be sorted out manually. Order confirmation time reached 40-60 seconds, and support requests about payments accounted for about a third of all tickets.
What we changed
Our engineers connected Webpay as the primary payment gateway and moved confirmation to an asynchronous scheme: the app immediately shows an intermediate status, and the final result arrives via a notification from the payment service.
We added request idempotency — a retry does not create a duplicate payment but returns the status of the original transaction. We set up automatic rollback when a bank declines and clear error messages right in the payment interface.
Result of the integration
The share of failed payments dropped from 18-20% to 4-6% within the first month after launch. Order confirmation time was reduced to 3-5 seconds in most scenarios.
Support requests about payments fell by nearly threefold — the bulk of issues are resolved automatically, without an operator. Separately, we note: bank declines are no longer lost but are correctly processed with a clear status for the user.
How does a payment form differ from a direct gateway call?
A payment form is a ready-made interface that the gateway provides to the application: the card entry screen, 3-D Secure, decline handling, and retries are already implemented on the provider's side.
The application opens the form and receives back the result of the operation — status, transaction ID, decline reason.
A direct gateway call is the opposite approach: our code assembles the request itself, renders the payment screen itself, and handles the response and all intermediate states itself.
The difference is not in "what is faster to integrate," but in who is responsible for the interface behavior and failure handling at every step.
Interface control is the main dividing line. The form lives inside its own container: the layout, texts, field order, and error behavior are set by the provider, and you can tailor them to the application's design only within the limits it allows.
A direct call gives us the entire screen: our own fields, our own validation, our own logic for hints and retries.
This is more expensive to develop — you need to carefully handle card input, expiration date, error codes, and loading states — but this is exactly where full control emerges over what the user sees and feels at the most critical moment.
Failure resilience is structured differently in the two approaches. The form takes on typical failures: timeouts, declined cards, re-authentication — the application simply reacts to the final status.
With a direct call, these scenarios fall on us: we need to correctly distinguish between "the operation failed" and "the response never arrived," avoid losing a payment when the connection drops, and avoid charging the customer twice on a resend.
This is where idempotent requests and clear status reconciliation on the server side, not just on the client, help.
The practical choice is usually this: the form — when it is more important to get payments into production quickly and not spend resources on rare scenarios; a direct call — when payment is built into a key product scenario and the interface must be your own.
A hybrid is often used: the form for the basic flow, a direct call for recurring payments and subscriptions, where custom screens and custom retry logic matter. We analyze payment scenarios in the application and propose an option for the task, not by default.
Technical concerns before connecting the Webpay integration
Before starting the integration, the technical team usually accumulates a list of questions that need to be resolved before the first line of code: how keys are stored, what happens to a payment when the network is lost, who is responsible for refunds. Below is an analysis of typical concerns that customers come with.
Where should payment gateway keys and secrets be stored?
Secret keys and tokens do not end up in the mobile client or in the repository. The request signature is generated on the server side, and the app communicates only with its own backend.
On the server side, the keys are stored in a secure vault and injected at runtime — this way, a leak of the app build does not grant access to accepting payments.
What happens if the customer's connection drops during payment?
The payment is initiated on the server, and the app only tracks its status. If the connection drops, the customer returns to the waiting screen, and the operation state is pulled from the backend on the next request. The customer does not pay twice: a retry is idempotent by order ID.
How are retries structured for a failed charge?
Retries are performed with a limit on the number of attempts and with an increasing delay so as not to overload the gateway during mass failures. Each attempt is logged with the failure reason, and the final status is recorded in the order. The customer sees a clear result rather than a frozen screen.
How do refunds and cancellations work?
A refund is initiated on the server by the ID of the original payment and proceeds as a separate operation with its own status. A partial refund is possible if the merchant's pricing plan supports it.
All movements on the order remain in the log — during investigation, it is clear exactly where the operation stopped.
Do I need to rewrite the app for the integration?
No. The payment flow is moved into a separate module, and the rest of the code is not affected. This makes it possible to update the payment logic independently of app releases and roll it back without rebuilding.
Describe your payment scenario — we will get back to you with an estimate and an integration plan.
Let's discuss your task and come back with a plan
To come back with an accurate estimate rather than a range "from and to," we need to understand your current payment setup: which provider you use now, exactly where in the app the charge occurs, how refunds and retries are handled.
The scope of work depends on this — sometimes it's enough to connect a payment module to your existing acquiring, and sometimes the entire checkout flow needs to be reworked.
Describe the task in your own words — that's enough for us to build a picture and prepare an integration plan with stages, timelines, and areas of responsibility.
If payments currently go through a web form or a third-party service, just say so: we'll assess what can be carried over as is and what will have to be rebuilt for the mobile scenario.
Here's what you get after we review the task:
- an estimate for Webpay integration work — broken down by each stage, with no hidden items;
- an integration plan: preparation, connection, test environment, production rollout;
- a review of your current payment setup and the points where it loses conversion;
- a list of modifications on the app side and on the service side;
- a scheme for handling refunds, cancellations, and retries;
- post-launch support terms: what's included, how requests are submitted, response time;
- timeline risks and ways to mitigate them before work starts.
We don't take on a task "just to take a look" and we don't promise to do it within a single conversation.
Instead, we review your setup, ask clarifying questions on contentious points, and come back with an estimate and a plan — after that, you decide whether we start or not.
Tell us how your payments are set up today and what you want to end up with. That's enough for us to come back with specifics.