Describe the whole payment life cycle first
The word “paid” can mean different things depending on the product and provider. A request may be created, authorized, confirmed, processing, settled, refunded or disputed. These are not simply colors in the interface: they affect service delivery, accounting, support and communication with the customer. Before design begins, define which state permits each business action and which system confirms that state.
The flow map covers the customer, internal application, payment provider, perhaps a bank and the dispute process. It records identifiers, timestamps, currencies, amounts, reasons for changes and ownership of repair. At every boundary ask what happens if the other party does not answer. A system that behaves well only when success is immediate has not completed its payment design, even if every screen appears finished.
An unknown outcome is not a rejection
After a timeout the application may not know whether the provider completed an operation. Retrying without context can create a duplicate payment; marking the action failed can prompt a customer to pay again unnecessarily. Use a stable business-operation identifier, a state awaiting verification and a path to learn the true result. Customer-facing copy should reflect how certain the system actually is.
An idempotent request can make technical retries safer. Its precise behavior depends on the API, retention period for the key and request parameters. Stripe documentation, for example, describes idempotency keys and differences between API versions. This behavior cannot simply be assumed for every provider. Before implementation, verify how the partner recognizes repeats, what it returns after an error and how concurrent requests behave.
Events and webhooks as changes in state
An asynchronous event may confirm an outcome after the customer has returned from a provider page. A webhook therefore often becomes an important input to the payment process. Verify its origin, process it safely more than once and separate acceptance of a message from completion of subsequent work. Providers may not deliver events in the order an application would prefer. State should not be derived only from the most recently received message without considering its meaning.
Stripe's official guidance describes signed webhooks and the need to use the original request body when checking a signature. Another provider may use a different mechanism. A good design records the event identifier, the reason an invalid message was rejected and a safe path for repeated processing. Heavy work can happen after a fast acknowledgment if its durable completion can be observed. An HTTP 200 by itself does not prove that the accounting state agrees.
Reconciliation and repair
Internal records and a provider can temporarily disagree. Delayed events, manual intervention, a lost message, refund or change on another side may be the cause. The integration needs regular reconciliation using stable identifiers, amount, currency and expected status. The result should be more than a dashboard number: it should produce an actionable case with an owner and evidence. A manual correction must preserve the original history.
It is unsafe to overwrite one system from another without rules establishing authority for each value. A source may be authoritative for authorization, a different one for settlement and another for the customer's invoice. Define those rules in design and test them with examples including partial refunds. A first operating release should contain a way to detect and close discrepancies rather than an assumption that none will occur.
Data protection and responsibility scope
Payment details are sensitive, and their flow should be minimized. An application storing card details is different from one redirecting a customer to a hosted payment service. Actual responsibility, however, follows the whole architecture and contracts rather than one screen. The PCI Security Standards Council describes PCI DSS as a baseline for protecting payment account data for entities that store, process or transmit relevant data or may affect that environment.
Qualified parties must assess concrete obligations for the product and provider. An engineering choice may reduce the amount of sensitive data handled, but does not prove compliance by itself. API and webhook secrets belong outside code, with limited access and a rotation plan. Logs, analytics and error messages should not collect personal or payment details without need. Permissions for refunds or configuration changes should be separate from ordinary read-only status access.
Tests that protect the real flow
A successful payment in a test environment is only the start. Scenarios should include timeout after submission, repeated click, duplicate webhook, events arriving out of order, rejection, cancellation, refund, unknown outcome and outage of the application's database. Check the customer message, internal state, accounting link and repair path for each. Tests use simulated data; production secrets and real payment details do not belong in development examples.
Alongside automated tests, run an operating exercise: stop event processing, let messages queue and watch whether they catch up safely after recovery. Measure unresolved payments, age of the oldest event, reconciliation differences and time to resolve exceptions. An alarm needs a person and a procedure. If a system reports a problem but no one knows how to repair it, the operational risk remains.
First delivery and integration boundary
A first complete path accepts the intention to pay, creates an operation with its own identifier, sends it to a provider, receives confirmation, handles a repeated event safely and shows the customer a truthful state. It also includes a way to investigate one unknown outcome manually. This validates the central contract and state model. Additional providers, payment methods or complex refunds should follow an actual need rather than enter the first version by default.
Before estimating, know the provider, availability of its test environment, target markets, currencies, product type, required methods and owner of the accounting record. Establish who can approve a refund and who speaks to a customer when the outcome is unclear. If these answers are missing, begin with technical and process discovery. Its output should be a state map, data contracts, test cases, reconciliation design and operating plan before implementation is specified in detail.
Questions before release
A payment path has to make sense to people outside engineering. When a customer reports a problem, support needs to find the operation and identify what is known, what is under verification and what happens next. Operations need to locate a lost event or discrepancy and repair it safely. Product owners need to understand risk and approve automation boundaries. Without those three views, a technically functioning endpoint is not enough.
- Which state authorizes delivery of a service or product?
- Does every operation have stable internal and provider identifiers?
- Can the system distinguish rejection from an unknown result?
- What happens after a repeated request or duplicate event?
- How is webhook origin verified and its secret protected?
- When and how are internal and external records reconciled?
- Who may issue a refund and who approves an exception?
- Has the team exercised recovery with events awaiting processing?