Design Order, Payment Attempt, and Gateway References

Use a separate identity for each object

The order identifies what the buyer purchased. The payment attempt identifies one intended payment request against that order. The gateway transaction identifies the provider operation. Store these separately so one order can have a declined attempt, a successful attempt, and a later refund without replacing the earlier history.

Include provider context in internal lookups

Record the provider, account, and environment beside its transaction identifier. Consider whether the provider’s reference is unique only inside an account or environment. Keep the support-visible order number distinct from account secrets, raw card details, or session credentials.

Retain parent and child references

A capture can be tied to an earlier authorization and a refund to a captured transaction. Store the parent reference when a later operation is created. This lets support investigate from the order and finance reconcile in the opposite direction from the processor report.

Exercise reference lookup both ways

• Find the successful attempt among failed and retried attempts on one order.
• Find the order using a transaction reference from a payout report.
• Find the parent transaction and resulting adjustment from a refund record.