Fast. Simple. No meetings. No delays.
Home / Blog / USA / Adding Stripe or PayPal to a Web Application: What to Plan For

Adding Stripe or PayPal to a Web Application: What to Plan For

The architecture of a safe payment flow: hosted checkout vs custom, webhooks as the source of truth, refunds and reconciliation.

Cover graphic for the article: Adding Stripe or PayPal to a Web Application: What to Plan For

A safe Stripe PayPal integration for a web application uses the provider's hosted checkout or embedded fields so card data never touches your server, treats webhooks as the source of truth for payment status, tracks orders through a clear state machine, and plans refunds and reconciliation from day one. Test everything in the sandbox before going live.

Stripe PayPal integration web application: hosted checkout or custom form

The first decision shapes everything else: do customers pay on a page the provider hosts, or on a form you build? The choices roughly fall into three groups.

ApproachHow it worksTrade-offs
Hosted checkoutYou redirect the customer to a payment page run by the providerLeast code and the smallest security burden; less control over look and flow
Embedded fieldsThe provider's scripts render the card inputs inside your pageMore brand control; card data still goes straight to the provider, not through your server
Fully custom formYou collect and transmit card details yourselfHighest compliance burden and risk; rarely justified for small and mid-sized businesses

For most businesses, hosted checkout or provider-hosted embedded fields is the sensible default. PayPal's buttons and Stripe's hosted or embedded components both follow this pattern. Choose a custom form only with a specific, well-understood reason.

Never handle raw card data

Card numbers, security codes and similar details should never pass through your servers, logs, databases, emails or support tickets. When they do, your PCI scope expands considerably and so does your exposure if something goes wrong. With hosted or embedded fields, the browser sends card details directly to the provider, and your application receives a token or a payment identifier instead.

Store only what you need: the provider's customer and payment identifiers, the amount, the currency, the status and perhaps the last four digits and card brand for display. Make sure your logging does not capture request bodies on payment endpoints. Whether and how PCI requirements apply to you depends on your integration method and volume, so check the provider's current official documentation and the PCI Security Standards Council's own guidance, or ask a qualified adviser. General security hygiene still applies; see our web application security checklist.

Webhooks as the source of truth

Customers close tabs, lose connections and click back. If you mark an order paid because the customer landed on a success page, you will eventually ship unpaid orders or leave paid ones stuck. The reliable pattern is:

  1. Create the order in your database in a pending state, and create the payment session with the provider, passing your order identifier as metadata.
  2. Send the customer to pay. The success page only tells them you are checking, and shows the current status.
  3. Receive the provider's webhook, verify its signature using the signing secret, and only then update the order.
  4. Respond with a success status quickly, and do heavy work, such as sending emails or generating invoices, in a background job.
  5. Make handlers idempotent. Providers retry webhooks and can deliver events more than once or out of order, so handling the same event twice must be harmless. Store processed event identifiers.

Also consider a scheduled job that checks old pending orders against the provider's API, as a safety net for missed webhooks.

Order state machine

Model payment status explicitly rather than with a handful of booleans. A simple order lifecycle might include these states: pending, paid, fulfilled, cancelled, refunded, partially_refunded and disputed. Then define which transitions are allowed, for example that a cancelled order cannot become fulfilled, and enforce them in one place.

  • Record every transition with a timestamp and the event that caused it, giving you an audit trail.
  • Store amounts as integers in the smallest currency unit, with an explicit currency code, to avoid floating-point errors.
  • Match amounts: compare the amount and currency in the webhook to what your order expects before marking it paid.
  • Decide what happens on failure, expiry and abandonment, and release reserved stock accordingly.

Our deeper PHP-level walkthrough is in the payment gateway integration in PHP guide, and the subscription billing article covers recurring payments, which add renewals and failed-payment handling.

Refunds, disputes and reconciliation

Payments do not end at the first charge. Plan for:

  • Refunds. Decide who can issue them, whether through your admin or the provider dashboard, and make sure your system learns about them through webhooks so records stay aligned. Support partial refunds.
  • Disputes and chargebacks. Know how you will be notified, what evidence you need to keep, such as order records, delivery confirmation and customer communication, and who responds within the provider's deadlines.
  • Reconciliation. Regularly compare your orders against the provider's payout and transaction reports. Differences point to missed webhooks, fee handling issues or fraud.
  • Accounting exports. Your finance person will want reports that match payouts, fees and refunds. Tax calculation and reporting questions belong with a qualified adviser; for the software side, see our article on sales tax and online store software requirements.

Testing in sandbox

Both Stripe and PayPal provide test modes or sandbox environments with test credentials and test card numbers. Use them thoroughly, and keep test and live keys strictly separate in configuration. A solid test plan covers:

  1. The successful payment path from cart to confirmation email.
  2. Declined cards, authentication challenges and abandoned checkouts.
  3. Duplicate and delayed webhooks, and webhooks arriving out of order, using the provider's tooling or a local forwarding tool to replay events.
  4. Full and partial refunds, and a simulated dispute.
  5. Amount, currency and rounding edge cases, discounts and shipping.
  6. Invalid webhook signatures, which your code must reject.

Automated tests for your order state machine and webhook handler pay for themselves quickly.

Go-live checklist

  • Live API keys and webhook secrets are stored as environment secrets, not in the repository, and test keys are removed from production.
  • The live webhook endpoint is registered, reachable over HTTPS and verifying signatures.
  • A small real transaction has been made and refunded to confirm the whole path.
  • Error tracking and alerts cover the payment endpoints and background jobs.
  • Receipt emails, terms, refund policy and contact details are visible to customers.
  • Logs contain no card data or secrets.
  • Someone owns reconciliation and dispute handling, with a calendar reminder.
  • You have reviewed the provider's current requirements and your obligations with the official documentation or an adviser.

Putting it together

Sketch your order states and the events that move between them before writing code, and choose hosted or embedded checkout unless you have a clear reason not to. If you would like help planning or building a payment flow, see our software development services for US businesses or send a short description through the contact page.

Frequently asked questions

Do I need PCI compliance?

If you accept card payments, PCI requirements generally apply in some form, but how much depends on your integration method and volume. Hosted checkout and provider-hosted fields reduce your scope considerably. Check your payment provider's current documentation and the PCI Security Standards Council's guidance, or ask a qualified adviser.

Why are webhooks important?

Customers can close the browser or lose connection before returning to your site, so the success page cannot be trusted. Webhooks are the provider's server-to-server notices of what actually happened. Verify their signatures, handle duplicates safely, and update order status only from these events.

How do I test payments?

Use the provider's sandbox or test mode with its test cards and credentials, kept separate from live keys. Test successful, declined and abandoned payments, duplicate or out-of-order webhooks, refunds, disputes and invalid signatures. Finish with one small real transaction after go-live.

Should I offer both Stripe and PayPal?

Offering both can suit customers who prefer a familiar wallet, but each adds integration, testing and reconciliation work. Start with one if you want a simple launch. If you add a second, keep your order state machine independent of any single provider, so both feed the same states.

Related articles

🚀 Start Now