From Payment Gateway Confusion to a Cleaner Order Flow

At first, I thought payment gateway integration was mostly about creating a payment button, sending a request to the provider, and redirecting the customer to a checkout page. After working through the flow, I realized the hard part was not the button. The hard part was designing the order and payment lifecycle clearly.

The first lesson was to separate orders from payments. An order represents the purchase intent: who bought, what items were purchased, how much the total was, and what business status the order is in. A payment represents a transaction attempt: which provider was used, what reference was sent, what checkout URL was returned, when the payment expires, and what status the provider reported.

This separation makes the application easier to reason about. A single order may usually have one active payment, but the design can still support retries, expired attempts, or future provider changes. If all payment fields are stored directly on the order, the model becomes harder to maintain as soon as the flow grows.

I also learned that order items should snapshot product information at purchase time. Product prices can change later, but an old order must still display the price and product name used when the order was created. This small detail matters for trust, reporting, and auditability.

The biggest shift was understanding that redirects are not the source of truth. A customer can close the browser after payment, the network can fail, or the callback page may never be opened. The reliable source should be the provider webhook or a status check against the provider.

In the end, a good payment integration is not simply one that opens the checkout page. It is one that can answer what happened after the checkout page was opened: whether the payment was paid, expired, failed, or still pending, and why the order status changed.