
Adding a "Pay now" button looks like one of the smaller items on a software project plan. The provider has documentation, sample code and a test mode, and a developer can take a test payment within a day. Then the system goes live. A customer is charged twice after pressing the button again on a slow connection. A payment succeeds, but the customer's phone dies before the browser returns, so the order still says unpaid. The finance team finds that the amount in the bank is lower than the total of the day's receipts, and nobody can explain the difference.
The button was never the hard part. The real work is keeping your system's records, the payment provider's records and the bank's records in agreement, even when networks fail and people behave unpredictably. This guide follows the journey of a payment, then looks at the design decisions and failures that matter most. It is written for business owners and project leads who are commissioning software, so it explains what to ask for and why, without assuming that you write code.
What actually happens during a payment
A card payment passes through more parties and more stages than it appears to. Other methods, such as bank transfers, UPI, wallets and direct debits, differ in their details, but they share the same broad pattern:
- Your system creates a payment request for a specific order or invoice and a specific amount.
- The customer provides payment details, ideally on a page or component controlled by the payment provider.
- The customer's bank approves or declines, sometimes after an extra verification step such as a one-time code.
- The funds are captured — immediately, or later if you only reserved them first.
- The provider notifies your system of the outcome.
- The provider settles, days later, paying a batch of transactions into your bank account after deducting its fees and any refunds.
Two points in this list cause most of the confusion. A payment is not a single event but a series of states that change over time. And "successful" does not mean "in the bank": the customer's payment and your settlement are separate events, often in different amounts and on different days.
Choosing how to integrate
Your first design decision sets how much of the sensitive process you take on yourself. There are three common models.
| Model | How it works | Best for | Trade-off |
|---|---|---|---|
| Payment links | The system generates a link and sends it by email or message; the customer pays on the provider's page. | Invoices, deposits, field collections, B2B balances. | Least control over the experience; very little to build. |
| Hosted checkout | The customer completes payment at checkout on a page or embedded component controlled by the provider. | Most online orders, bookings and customer portals. | Limited visual control; a good balance of security, effort and conversion. |
| Direct API | Your own screens collect payment details and pass them to the provider. | Rare cases that genuinely need full control. | Greatly increases your security and compliance responsibilities. |
For most businesses, the sensible default is the first or second option. A custom-built payment form rarely improves sales enough to justify the extra risk. Spend the design effort on what happens around the payment, which is where your business rules live.
When comparing providers, check the items that are expensive to discover late: supported countries, currencies and local payment methods; whether your business category is accepted; settlement timing; the quality of settlement reports and their availability through an API; how refunds and disputes work; and how clearly the test environment and webhook behaviour are documented. Confirm these directly with the provider for your own country and business type, because availability and terms vary and change.
Model a payment as a record with states
A frequent early mistake is to add a single paid = yes/no field to the order. It cannot represent a partial payment, a refund, a failed second attempt or a dispute raised six weeks later. A better design keeps a separate payment record, with its own history, linked to the order or invoice.
| State | Meaning | What the business should do |
|---|---|---|
| Created | A request exists; the customer has not finished. | Wait. Expire it after a defined period. |
| Pending | The outcome is not yet known, as with some bank transfers. | Do not ship or release yet unless your risk rules allow it. |
| Authorised | Funds are reserved but not collected. | Capture on dispatch or cancel before the reservation lapses. |
| Succeeded | The funds have been captured. | Fulfil the order and issue the receipt. |
| Failed / expired | No money was taken. | Invite another attempt; keep the failure for support staff. |
| Partly / fully refunded | Some or all of the money was returned. | Adjust the balance, stock and accounting entries. |
| Disputed | The customer has challenged it through their bank. | Alert finance; collect evidence before the deadline. |
One order can now have several payments: a failed attempt, a 30% deposit and a final balance. The order's balance is calculated from those payment records, not typed in by hand. That single decision removes a whole family of arguments between sales and finance.
Store money carefully, too. Amounts should be held in exact form, usually whole minor units such as cents or paise, alongside a currency code. Floating-point numbers introduce rounding errors. Do not assume every currency has two decimal places: the Japanese yen has none and the Kuwaiti dinar has three.
Five failures to design for from day one
A helpful exercise during requirements is to walk through what should happen when things go wrong. These five situations will occur in any system with enough transactions.
1. The customer never returns from the payment page
The bank approved the payment, but the customer's connection dropped. If your system relies on the browser's return, the money is taken and the order stays unpaid. The remedy is to treat the provider's server-to-server notification, called a webhook, as the main source of truth. The return page should only show the latest known status, with a "we're confirming your payment" message if the answer is not yet in.
2. The customer presses the button twice
Slow screens invite repeat clicks and page refreshes. Disable the button after the first press, but do not stop there. Reuse one open payment request for each order attempt, and use the idempotency keys many providers support: a unique reference sent with the request, which tells the provider that a retry is the same operation rather than a new one.
3. The same webhook arrives twice, or in the wrong order
Providers commonly resend a notification if they do not receive a prompt acknowledgement, and notifications are not guaranteed to arrive in sequence. A "refunded" event could arrive before your system has processed "succeeded". Your handler should record each event ID and ignore ones already processed. It should also refuse illogical state changes, and fetch the current status from the provider when something looks out of order. Without this protection, one payment can trigger two invoices, two stock deductions and two confirmation messages.
4. Someone sends a fake notification
A webhook address is simply a public URL, so anyone who discovers it can send a message saying "order 1045 is paid". Always verify the provider's cryptographic signature, compare the amount and currency against what you expected, and keep webhook secrets out of source code. Never accept the amount or the payment status from the customer's browser.
5. Your system is down when the webhook arrives
Even with provider retries, some notifications can be missed during longer outages or after a bad release. Run a scheduled catch-up job that looks for payments left in Created or Pending for too long and asks the provider for their status. This small background task quietly resolves a large share of "customer says they paid" tickets.
Worked example: why the bank never matches the sales report
Reconciliation is the part most often left out of the first project plan, and the part finance teams care about most. Here is an illustrative day's settlement, using round figures in a single currency.
| Item | Amount |
|---|---|
| 40 successful customer payments on Monday | 100,000.00 |
| Provider fees (illustrative 2%) | −2,000.00 |
| 2 refunds processed the same day | −3,000.00 |
| Net amount settled to the bank on Wednesday | 95,000.00 |
Finance sees 100,000 in the sales report and a single 95,000 credit in the bank two days later. Without help from the software, someone spends an afternoon tying the two together in spreadsheets. With good design, the application imports the provider's settlement report and shows the batch, every transaction in it, the fees and the refunds. Each transaction moves from Succeeded to Settled, and the 95,000 matches the bank line.
Anything unmatched goes to an exceptions list: a payment in the provider's report that your system does not know about, a succeeded payment missing from any settlement after the expected time, an amount that differs, or a settlement line with no bank credit. This list is where real problems surface early, while they are still easy to investigate.
Agree the accounting treatment with your accountant before building it. Questions include whether sales are recorded gross with fees as an expense, when income is recognised, how tax applies to fees and refunds, and how transactions should post to your accounting system. The fee on a refunded payment also needs checking, because provider policies differ.
Refunds, disputes and subscriptions
Refunds should start from the original payment record, respect a permission and approval rule, and allow partial amounts. The screen should stop anyone refunding more than the remaining balance. Record who issued each refund, why and when, and decide what else it should trigger: a credit note, a stock return or a cancelled service. A refund made directly in the provider's dashboard should still flow back into your system by webhook, or your records will quietly drift.
Disputes, also called chargebacks, begin with the customer's bank and can arrive long after the sale. Create a task with its response deadline, alert the right person and gather the relevant invoice, delivery proof, signed job sheet and correspondence. Business software has an advantage here, because it already holds the evidence.
Recurring payments add their own set of rules. You will need to decide on retry schedules for failed renewals, reminders before expiry, what access or service continues during a grace period, how mid-cycle plan changes are handled and how customers can update their card or cancel. Rules on customer authorisation also vary by country. Strong customer authentication in Europe and e-mandate rules in India are two examples, so confirm the current requirements with your provider rather than assuming one design works everywhere.
Security and card data
Businesses that accept cards generally fall under the PCI DSS security standard. Your provider or acquiring bank can tell you which validation applies. Using a provider-hosted payment page can significantly reduce your compliance scope, although it does not remove your responsibilities altogether. A few rules apply whichever model you choose:
- Never store the card security code after authorisation, and avoid handling full card numbers at all.
- Check your logs. Sensitive data often leaks through debug logs, error reports and support screenshots, not through the main database.
- Protect the keys. Live API keys belong in protected server configuration, are separate from test keys, and should be changeable if exposed.
- Limit dashboard access. Use individual logins, multi-factor authentication and restricted roles, so that not everyone can issue refunds.
- Keep an audit trail of refunds, manual status changes and changes to payout bank details. The last of these is a classic target for fraud.
The test plan your team should run before launch
A test mode that takes one successful payment proves very little. Ask your development partner to demonstrate these scenarios, and include them in user acceptance testing:
| Scenario | Expected result | Pass? |
|---|---|---|
| Successful payment; browser closed before returning | Order marked paid via webhook | |
| Card declined, then a second attempt succeeds | One paid order; failed attempt visible in history | |
| Double click and page refresh during payment | Only one charge | |
| Same webhook sent twice | One receipt, one stock movement | |
| Webhook with an invalid signature | Rejected and logged; order unchanged | |
| Partial refund, then an attempt to over-refund | Balance adjusted; over-refund blocked | |
| Refund issued in the provider's dashboard | Application updates automatically | |
| Application offline for an hour during payments | Catch-up job resolves all of them | |
| Order cancelled while payment is in progress | Clear outcome; automatic refund or staff alert | |
| A real settlement file imported | Matches the bank; exceptions listed |
Finish with a small live transaction using a real card and a real refund. Sandboxes are helpful, but they do not always behave exactly like production.
Questions to settle before development begins
- Which payment methods and currencies do customers actually use, and in which countries?
- Will customers pay in full, in instalments, by deposit or on a recurring plan?
- At what point is the order released: on authorisation, capture or settlement?
- Who can refund, up to what amount, and with whose approval?
- Who owns the provider account? It should be your company, not a developer or agency.
- How do payment records reach accounting, and who reviews exceptions each day?
- What will staff do if the provider is unavailable for several hours?
Answering these early makes the estimate more realistic and exposes the rules that sample code will never handle. Payments deserve careful design because mistakes affect both your customers' money and your trust with them. Get the states, webhooks and reconciliation right, and the "Pay now" button becomes what it always appeared to be: a small part of a reliable system.
Frequently asked questions
Do we need to store card numbers to accept repeat payments?
Normally no. Payment providers can store the card and give your application a token that represents it. Your system keeps the token and a few display details, such as the card brand and last four digits, while the sensitive data stays with the provider.
Why can't we mark an order as paid when the customer returns from the payment page?
The customer may close the browser before returning, and a return address can be visited or altered without a completed payment. Treat the return as a prompt to check status, and confirm the payment through a signed webhook or a server-to-server status request.
What is the difference between a payment gateway and a merchant account?
A gateway passes the payment securely between your application and the payment networks. A merchant account is the arrangement that lets a business accept and receive card funds. Some providers combine both in one service, while others separate them.
How long does a payment integration take to build?
A simple one-off payment using a hosted page is a relatively small piece of work. Saved cards, subscriptions, partial payments, refunds from your own screens, several currencies and automated reconciliation each add design and testing. Scope depends on the provider and on your rules, so define the scenarios first.
Can one application use more than one payment provider?
Yes, and it can be useful when you operate in several countries or want a fallback. Keep provider-specific code behind a common internal payment interface, record which provider handled each transaction, and reconcile each provider separately.
