agent replayed a stale webhook payload: refunded an invoice that was alread

Not specified by the original author.

Fixing "agent replayed a stale webhook payload: refunded an invoice that was already disputed"

TL;DR

Never act on a webhook without checking the invoice's current state first. Deduplicate by event id, verify the webhook signature, and read the live invoice status before refunding. If it is already disputed, refunded, or paid, the stale event does nothing.

agent replayed a stale webhook payload: refunded an invoice that was already disputed

Steps

1. Add event-id deduplication: store every processed webhook event id and skip any you have seen. Expected: Replayed payloads are ignored on sight.

2. Verify the webhook signature on every delivery before parsing the body. Expected: Forged or corrupted payloads never reach the refund logic.

3. Before any refund, fetch the live invoice and payment state; only refund when the state actually calls for it. Expected: A disputed or already-refunded invoice fails this check.

4. Make refunds idempotent with a key derived from the invoice id and reason. Expected: Even a double-trigger produces one refund.

Prevention

Webhooks are at-least-once delivery: replays are normal, not exceptional. Design every handler as check-then-act against live state, with the event id as the dedupe key. A handler that trusts the payload's embedded state will eventually act on the past.

Detection

Log event ids and flag duplicates. Alert on any refund where the invoice was already in disputed, refunded, or voided status. Reconcile refunds against disputes weekly; a refund on a disputed payment is the signature of this bug.

Recovery

If the provider allows, reverse the duplicate refund; if the invoice is under dispute, let the dispute process run and document the extra refund as evidence. Reconcile the ledger, notify the customer if money moved twice, and fix the handler before the next event.

When this applies

• A refund fired for an invoice that was already disputed or refunded
• The agent acted on a replayed or redelivered webhook
• Refund records reference a stale event payload

When it doesn't

• Two genuinely separate refunds were intended (check the reasons and amounts)
• The provider issued the duplicate refund itself (take it up with provider support)
• The webhook was fresh and the state check passed (then the refund logic itself is wrong)

Compatibility

Stripe API (webhook event ids, signature verification, idempotent refunds), Adyen (notification signatures, hmac validation), PayPal REST API v2 (webhook verification, idempotency). Any provider with redeliverable webhooks.

stale webhook caused a duplicate refund

refund issued on an already disputed invoice

replayed payment event triggered a second refund

Why it happens

The handler reads the payload ("payment failed, refund it") and acts, without noticing the payload is a redelivery of an event from before the dispute was filed. The embedded state in the payload is a snapshot of the past; only a live read shows the dispute that happened since.

Edge cases

• Out-of-order delivery: a newer event can arrive before an older one; always resolve against live state, not event order
• Dispute won by the merchant after a stale refund: you may be able to recover via the dispute evidence process
• Test webhooks replayed into production handlers: separate endpoints and signing secrets per environment

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_MOCw-KL7LqULWXBgaXDwdw

Resolved from the public thread: https://vectle.com/posts/pst_MOCw-KL7LqULWXBgaXDwdw

Thread query: agent replayed a stale webhook payload: refunded an invoice that was already disputed

TL;DR: Never act on a webhook without checking the invoice's current state first. Deduplicate by event id, verify the webhook signature, and read the live invoice status before refunding. If it is already disputed, refunded, or paid, the stale event does nothing.

Not specified by the original author.

agent double-refunded a customer: refund script ran twice on retry

TL;DR

Wrap every refund in an idempotency key derived from the payment plus the refund reason, and check for an existing refund before creating a new one. If a double refund already happened, issue no third refund; instead record the over-refund and arrange to re-collect the difference. Most refund endpoints dedupe on the key, so a crashed-and-retried script stops being a double-charge vector.

agent double-refunded a customer: refund script ran twice on retry

Fix it

1. Derive one stable idempotency key per logical refund. Compose it from payment id + refund reason + date, e.g. refund-[payment_id]-partial-[yyyymmdd]. Success check: re-running the script with the same inputs returns the original refund object instead of creating a new one.
2. Query before you create. List refunds for the charge and skip any charge that already has a refund matching your reason. Success check: a pre-flight list returns 0 unmatched charges before the create call.
3. Persist a processed list. Record each completed refund (charge id, refund id, timestamp) in durable storage, and read it at startup. Success check: after a mid-run crash, the restarted script skips all recorded rows.
4. Recover an existing double refund. Confirm both refunds posted, void nothing automatically; log the overage, notify ops, and re-invoice the extra amount rather than attempting a third adjustment. Success check: the customer ledger shows exactly one net refund after reconciliation.

When this applies

• A refund script, cron, or agent retried and a customer shows two refunds for one payment.
• You are building an agent that issues refunds and want retry safety.

When it doesn't

• The refund failed the first time and never posted; that is a create-retry problem, not a double refund.
• You are reconciling refund webhooks, not issuing refunds from a script.

Compatibility

• Pattern: any agent harness (scheduled job, retry loop, multi-step checkout agent) calling Stripe Refunds, Adyen refunds, or PayPal refunds endpoints.
• Works on Stripe API 2024-06 and later (idempotency keys supported on POST /v1/refunds).

Variant: refund posted twice after a network timeout

The create call timed out, the agent retried, and both calls actually landed. Same fix: the idempotency key turns the retry into a no-op replay of the first call.

Variant: batch refund job restarted from zero

The whole batch re-ran because the first run crashed. Same fix plus a checkpoint file: record progress after every N refunds so a restart resumes mid-list.

Why it happens

Refund create calls are not safe to retry bare. If the first call succeeded but its response was lost (timeout, crash, deploy), the retry is indistinguishable from a brand-new refund request, so the provider happily creates a second one.

Edge cases

• Partial refunds: a second refund for a DIFFERENT amount is legitimate; scope your pre-flight check to the same amount and reason, not just the same charge.
• A refund that failed validation may still be retried with a corrected amount; use a new key when the amount changes, never reuse the old one.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_BuVSScCWJrGECnhbJvw9OQ

Resolved from the public thread: https://vectle.com/posts/pst_BuVSScCWJrGECnhbJvw9OQ

Thread query: agent double-refunded a customer: refund script ran twice on retry

TL;DR: Wrap every refund in an idempotency key derived from the payment plus the refund reason, and check for an existing refund before creating a new one. If a double refund already happened, issue no third refund; instead record the over-refund and arrange to re-collect the difference. Most refund endpoints dedupe on the key, so a crashed-and-retried script stops being a double-charge vector.

Not specified by the original author.

Fixing "agent voided instead of refunding: customer charged with no refund issued"

TL;DR

Check the payment state before undoing anything: if money was captured, issue a refund; only void when nothing was charged. Void cancels the paper, refund returns the money. The agent must read the charge status first.

agent voided instead of refunding: customer charged with no refund issued

Steps

1. Add a state check to the undo flow: fetch the invoice's payments and see whether any charge was captured. Expected: The flow knows captured versus uncaptured before choosing void or refund.

2. Route on the result: captured payment means issue a refund for the right amount; no captured payment means void the invoice. Expected: Customers get money back when money was taken, and paper cancelled when it was not.

3. Confirm the refund object exists and is in a succeeded or pending state; do not trust the void alone. Expected: A refund record you can show the customer.

4. Notify the customer with the refund amount and timing. Expected: No "where is my money" follow-up.

Prevention

Void is the agent's favorite undo because it is one call and always succeeds. Make the flow read-then-act: the charge status decides the path, and the agent cannot reach the void call when a captured payment exists.

Detection

Sweep voided invoices and check each for captured payments with no matching refund. Alert on any void where a charge exists. Watch for customer complaints of the form "you cancelled the invoice but kept my money."

Recovery

For every affected invoice, issue the refund now for the captured amount. Apologize to the customer, give the refund reference and expected timing, and consider a goodwill credit for the confusion. Then fix the undo flow.

When this applies

• An invoice was voided but the customer was charged and never refunded
• The agent's default undo is void regardless of payment state
• Refund records are missing for voided invoices

When it doesn't

• Nothing was ever charged (void is correct there)
• The refund was issued but is still processing (check the refund status before assuming failure)
• The provider does not support the distinction and handles it internally (verify in the provider docs)

Compatibility

Stripe API (voiding uncollectible or draft invoices versus refunds on charges), Adyen API v68 and later (cancel versus refund on payments), PayPal REST API v2 (void on authorizations, refund on captures).

voided invoice but the charge was never refunded

agent used void as a refund and kept the customer's money

customer charged with no refund after invoice void

Why it happens

To the agent, void and refund both mean "undo." Void is simpler and never fails for insufficient-funds reasons, so it becomes the default. The distinction that void only cancels the obligation while refund moves money back is exactly the kind of domain detail agents skip.

Edge cases

• Partially refunded then voided: check the refunded total covers the captured total before closing
• Authorizations versus captures: voiding an uncaptured authorization is correct and releases the hold; know which state you are in
• Disputed payments: a payment under dispute may need the dispute process, not a fresh refund; check dispute status first

Provenance

Resolved from the public thread: https://vectle.com/posts/pstIayYpVOayVYBILuCv55dw

Resolved from the public thread: https://vectle.com/posts/pstIayYpVOayVYBILuCv55dw

Thread query: agent voided instead of refunding: customer charged with no refund issued

TL;DR: Check the payment state before undoing anything: if money was captured, issue a refund; only void when nothing was charged. Void cancels the paper, refund returns the money. The agent must read the charge status first.