Moving provider status checks into background reconciliation while keeping transaction reads fast and current.
A transaction marked processing creates two competing needs. Customers want a fast transaction list, while the platform needs to check whether the external provider has reached a final state.
Calling the provider synchronously every time the customer opens the transaction screen couples product latency to an external network. A slow or unavailable provider can make the entire history page feel broken.
A better pattern is stale-while-revalidate for payment status.
The transaction endpoint returns the current local state immediately. If a processing transaction has not been checked recently, it schedules a background status task using a deterministic key such as:
status-check:{provider}:{provider_reference}:{check_window}
The worker queries the provider, records the observation, and applies a guarded state transition. The next app refresh or websocket update reflects the new state.
Define eligibility for polling
Do not check every transaction on every read. A status scheduler should consider the local state, provider, last check time, age, retry count, and next eligible check time.
Use shorter intervals for newly processing transactions and progressively back off. Stop polling terminal records. Move unusually old transactions into an exception queue rather than querying forever.
Separate query success from payment success
A provider can return HTTP 200 because the status query succeeded while the payment remains pending. Normalize the financial status from the correct payload field. Unknown values remain unknown; they must not become successful because the transport worked.
Store both the raw sanitized observation and normalized status. This gives operations evidence when mappings need correction.
Guard transitions and effects
Workers, webhooks, and staff actions may all update the same transaction. Lock the local record and use an explicit transition table. A late pending observation cannot move a completed transaction backward.
When the new state requires a credit, debit, release, or refund, protect that effect with a unique ledger reference. Status idempotency and financial idempotency are related but separate guarantees.
Provide operational controls
Staff needs actions to check one transaction, bulk-check eligible pending transactions, and request provider webhook replay when supported. These commands should queue work rather than keep the browser waiting.
Display last checked time, next check time, attempt count, latest provider state, and any operational error. Bulk actions should report queued, skipped, and ineligible counts.
Notify only on meaningful transitions
A repeated processing result should not notify the customer. Trigger messages after a committed transition into a meaningful state and deduplicate them by transition event identity.
Background status recovery makes the application responsive without abandoning eventual accuracy. The local transaction remains the fast read model; external status becomes asynchronously refreshed evidence.
Implementation checklist
Persist last_checked_at, next_check_at, attempt count, latest provider status, and the provider reference used for lookup. Make the queue task unique for a transaction and time window. Apply exponential backoff with a maximum age and move exhausted cases into a visible exception state.
Instrument provider latency, status changes per check, checks that return no result, terminal recovery rate, and the age of the oldest processing transaction. These metrics distinguish a slow provider from a broken worker or an incorrect status mapping.
Top comments (0)