Purpose
Explain how PayPress creates, updates, enriches, and timestamp-protects local orders.
Overview
Orders are created from accepted Stripe webhook events and enriched as related events arrive.
The first relevant event creates the local order. Later events can merge newer identifiers, document links, receipt information, refund data, shipping details, customer details, and form snapshots into the same order.
How It Works
PayPress normalizes webhook data into a shared order row and passes it through the repository upsert path. The same order persistence path is used for one-time payments, subscription invoice orders, donations, and fundraising donations.
The repository first tries to find an existing order by business key and Stripe identifiers. If an order exists, PayPress updates that row and preserves existing values when the incoming event does not contain newer data. If no order exists, PayPress performs a fresh insert. If an insert races another webhook and hits a duplicate key, PayPress retrieves the existing row and performs duplicate recovery.
Timestamp hardening applies to all three outcomes:
- Fresh insert.
- Existing order update.
- Duplicate recovery update.
Important Components
- Accepted Stripe events.
- Order key.
- Stripe object ID.
- Duplicate prevention.
- Checkout context lookup.
- Timestamp hardening.
- Existing-row timestamp repair.
- Receipt/invoice enrichment.
- Order Details rendering.
Data Flow
Stripe event -> ownership accepted -> order data normalized -> existing order lookup -> insert or update -> duplicate recovery if needed -> fields merged -> timestamps validated/repaired -> admin/success/export views.
Timestamp Failure and Recovery Flow
The v1.3.12 to v1.3.13 investigation found that some rows could contain created_at = '0000-00-00 00:00:00', causing blank Created dates and incorrect table sorting. This was confirmed in the database and was not a display issue.
Current behavior:
- Fresh inserts write a validated UTC
created_atand immediately read back the persisted value. - If the persisted insert timestamp is invalid, PayPress repairs it and logs the repair.
- Existing updates check the stored
created_atbefore updating the row. - If the stored
created_atis invalid, PayPress repairs it using validupdated_ator current UTC time. - Duplicate recovery uses the same existing-row repair path.
- Valid
created_atvalues are never overwritten.
Diagnostic labels distinguish insert, update, and duplicate recovery outcomes so future investigations do not confuse recoverable webhook races with fresh insert failures.
Security Considerations
Order creation requires valid webhook signature and ownership. Checkout context data is used only for the local order and is not trusted without the Stripe event.
Known Limitations
Some document links may arrive after the initial order. The success page may need to wait or refresh if webhook enrichment is still in progress.
Timestamp repair prevents invalid order dates from persisting, but diagnostics are not a permanent audit log and may be removed by webhook log retention cleanup.