Reconciling Payments When Webhooks Never Arrive

Handling payments asynchronously often involves checking the status of transactions through webhooks. While webhooks are speedy, they cannot ensure every event reaches the application. Possible hiccups include network glitches, rejected calls due to signature or configuration issues, or lost communications during outages. Also, a payment might be finalized while the local transaction still waits for confirmation, leaving it stuck indefinitely without a backup confirmation method.

To address this, reliable payment systems need both passive webhook monitoring and active reconciliation.

Reconciliation kicks off when a transaction is initiated. A local record is created, capturing critical information such as the internal business reference, the payment provider, the provider's transaction ID, the current state, timestamps for requests and responses, and a sanitized summary of the provider's response. It's vital to note which provider processed the transaction, as querying the current default provider may yield outdated information if the platform switches payment processors.

Instead of blocking the user interface while checking transaction statuses, the API can return the current local state and schedule a background refresh for eligible transactions. This prevents a flood of identical provider calls from occurring each time a user refreshes their payment status screen.

Webhook processing and active reconciliation must use the same definition of success. Both methods should translate external outcomes into the same internal language and interact with the same guarded transition service. For example, a successful receipt could trigger completion of the local transaction, while a failed status could initiate a failure or refund process.

Other outcomes might include ongoing processing, indicating the need for further attempts with delays, or flagging an unavailable provider for later retries.

These outcomes prevent the system from misinterpreting a payment's status and ensure it can handle various scenarios appropriately. Whether a provider repeatedly returns 'pending' or sends an 'unknown' status, the worker should continue trying within certain limits, rather than automatically concluding failure.

To ensure safe repetition of reconciliation, the system should lock the transaction once a terminal result is achieved. This locks the transaction and safeguards its financial impact with an idempotency key, preventing the same financial transaction from being executed twice. This safe-to-repeat approach means reconciliation can be triggered manually by operations staff if needed.

While customers see a stable transaction state, operations personnel may need more detailed information about a problematic transaction. They can access local and provider references, provider identifiers, the latest normalized and external statuses, timestamps for prior checks, the last recorded provider error, and an option to request another status refresh. However, provider-specific errors should remain internal, as customers should only see a comprehensible transaction state, not raw infrastructure messages.

The key principle is that webhooks provide a fast way to learn about a payment's status, while reconciliation ensures that eventual confirmation is complete and reliable. By combining both approaches, the payment lifecycle becomes convergent, regardless of whether the platform learns about a payment's result through a callback, background poll, or staff intervention. This unified process makes managing unreliability in external systems more manageable.