Skip to content
GateFuzGateFuz FAQ & Docs

Webhook Resiliency & Transaction Edge Cases

A mission-critical payment engine must behave deterministically when customers close browsers prematurely, networks time out, or payment providers retry webhooks multiple times.

GateFuz provides full built-in coverage for difficult transaction edge cases:

1. Payment Succeeds (Mark Order Paid Once)

Section titled “1. Payment Succeeds (Mark Order Paid Once)”
  • Behavior: Idempotently records the transaction and marks the order as paid once.
  • Mechanism: TransactionManager::record() uses deduplication logic against gateway_tx_id and order_id. If already completed, subsequent redundant calls return safely without re-triggering fulfillment side effects.

2. Payment is Pending

Section titled “2. Payment is Pending”
  • Behavior: Keeps the order pending or on hold as appropriate.
  • Mechanism: Asynchronous authorizations (Stripe payment_intent.processing, PayPal PAYMENT.CAPTURE.PENDING, Mollie open/pending, Bank Transfer) persist with status pending. Downstream order fulfillment does not fire until cleared.

3. Customer Cancels

Section titled “3. Customer Cancels”
  • Behavior: Safe return to checkout with a clear error; order is never falsely marked paid.
  • Mechanism: Explicit provider cancellation webhooks (payment_intent.canceled) transition records to cancelled.

4. Provider Times Out

Section titled “4. Provider Times Out”
  • Behavior: Verifies the existing transaction state before attempting a blind charge retry.
  • Mechanism: Upon network/HTTP timeout during API calls (wp_remote_post), GateFuz performs a state check to verify if the payment was already captured by the gateway before returning an error.

5. Duplicate Webhooks (Replay Protection)

Section titled “5. Duplicate Webhooks (Replay Protection)”
  • Behavior: Acknowledges duplicate webhooks safely with HTTP 200 without repeating side effects.
  • Mechanism: If a webhook event arrives for a transaction already marked completed, GateFuz acknowledges the provider safely and exits immediately.

6. Payment Succeeds After Browser Closes

Section titled “6. Payment Succeeds After Browser Closes”
  • Behavior: Asynchronously fulfills orders via verified server-side webhooks.
  • Mechanism: Even if a user disconnects or closes their tab before redirect, the server REST endpoint (/wp-json/gatefuz/v1/webhook/*) receives the provider notification, verifies the signature, and triggers gatefuz_payment_completed.

7. Refund Succeeds

Section titled “7. Refund Succeeds”
  • Behavior: Records the refund and synchronizes the ledger status.
  • Mechanism: When Stripe (charge.refunded), PayPal (PAYMENT.CAPTURE.REFUNDED), Razorpay (refund.processed), or Paystack fires a refund event, TransactionManager::markAsRefunded() updates the ledger status to refunded and fires gatefuz_payment_refunded.

8. Invalid Webhook (Tampering Defense)

Section titled “8. Invalid Webhook (Tampering Defense)”
  • Behavior: Rejects payload and logs a sanitized security incident.
  • Mechanism: WebhookController verifies signatures using provider keys (HMAC-SHA256, SHA512, PayPal verification API). Failed signatures are rejected with HTTP 403.

9. Amount or Currency Mismatch

Section titled “9. Amount or Currency Mismatch”
  • Behavior: Does not mark order paid; flags transaction for investigation.
  • Mechanism: In addition to checkout form HMAC tokens, incoming webhooks compare the received amount and currency with the recorded order. If altered, the transaction is marked failed with flag amount_or_currency_mismatch.