How AI agents help investigate failed payments

Agent Swarm can assemble the context around a failed customer payment: billing status and support history, gathered into an internal brief where every fact links to the record it came from, with a named operations owner making every customer and financial decision. In that flow, agents never retry a charge or move money. They change no financial record. They diagnose no fraud and contact no customer.

That division answers the two questions this page exists for. How can AI agents help investigate failed customer payments across billing and support systems? By collecting what each system already knows and putting it in one place with the source attached. How should operations teams triage failed payments with human review? By handing one named owner the facts and the gaps, with a written decision boundary for what happens next, then letting that owner act.

Limits and when not to use this

Start with the cases where you should not build it.

If your payment platform's built-in dunning and retry tooling already answers the question, use that, along with its recovery flows. Same for a deterministic alert that fires when a charge fails and a customer keeps writing in. Both are cheaper than an agent pipeline and neither can drift. If the only question is whether a charge failed, and the answer is one field in one system, the alert already has it, and an agent adds a reader without adding information.

This page describes a pattern built from documented primitives. It is not a shipped payment integration, a fraud product or a verified customer deployment. Nobody here is claiming a model can decide whether a decline is fraud, or that an internal brief can replace a finance control. The agent reads and writes. The money stays where it is.

The scope is read-only: every source is queried, no payment state changes, and the workflow's only output is a document and a decision raised for a person.

For a managed deployment, use the contact address on agent-swarm.dev. This page covers no cloud specifics.

An illustrative flow

Illustrative means a design assembled from documented primitives, not a customer case or a product feature.

(a) The event arrives. A payment failure comes in through a workflow webhook trigger, and that trigger verifies the request signature only when hmacSecret is set. With the secret configured, the check is HMAC-SHA256 over the raw body. The timestamped form covers providers that sign the timestamp together with the payload, and it rejects timestamps outside its tolerance window. Leave hmacSecret unset and the endpoint accepts unsigned POSTs. When a provider offers no webhook, or when you want one sweep over the last day, a schedule trigger does the same job.

(b) A script collects, deterministically. The payment event triggers one read-only query that an owner approved before the workflow went live, so a caller cannot widen what the run reads. The next node is a swarm-script that fetches each source over HTTP or SQL and emits one JSON payload. No model sits in that step, so the same query and the same transform give the same structure on every run. The facts inside it move between runs. The charge's state and the support thread change, every read timestamp is new, and a payment that recovers changes what the next payload reports. A source that answers arrives with its read time, and an unreachable source arrives as a labelled gap. A step that cannot run fails the run instead of completing it quietly. The reporting playbook behind this pattern keeps the model out of the fetch and has one agent hold the scoped cross-source credentials, which keeps the secret surface small.

(c) An agent writes the brief. From that payload, an agent node writes an internal investigation brief. Every fact carries the record it came from: the charge and its state, the invoice, the plan the account is on, the open support thread and its latest message, and when each of those was last read. Where the payload has no answer, the brief says so instead of filling the gap. Its reader is one person who has to decide, so it can state the disagreement between systems plainly.

(d) The owner decides. A named operations owner verifies the facts in the brief before deciding anything, then chooses the next step: ask finance for a retry, or leave the payment alone. Any message to the customer is a separate step behind a human-in-the-loop gate, which pauses the workflow until a person approves, and which defines what happens on approve and on reject plus a timeout, so a forgotten gate cannot wedge the run. The gate pattern also says to gate only the steps that cannot be undone, which is why retrying a charge never runs behind a poll of the team.

What the brief contains

Four parts, in this order. A summary in two sentences: which payment failed and what each system currently reports about it. The evidence, one line per fact with its source record and the time it was read. The open questions, meaning every gap or disagreement the collection found, including stale reads. And a recommended next step with the reason for it, addressed to the owner by name. Nothing in the brief is a customer-facing draft, because the owner may pick a path that makes a message unnecessary.

Edge cases

Each case below decides whether the pattern survives contact with a real billing system.

Missing or stale source data

Each source in the payload carries the time it was read. If the support system is unreachable, the brief says the source is missing and how old the last successful read is. That is a partial-source gap, and it is not the same as a failed check. It never infers a ticket from a billing record. A brief with a labelled hole is still useful: it records the missing read as not done, never as passed, so the owner knows exactly what is unverified before deciding anything. A check that never ran is the other case: no payload and no brief, and the run reports the failure instead of staying quiet.

Duplicate events

Payment providers resend webhooks, sometimes within seconds. Key the case on the payment id and deduplicate before the agent runs, so one payment produces one case and one brief. A resend that lands mid-investigation updates the case in place rather than opening a second one.

Conflicting status between billing and support

Billing can show a charge as recovered while support holds a thread where the customer says they were billed twice. The brief shows both readings with their timestamps and names no winner. The owner resolves it, usually by opening the payment provider's dashboard, which the agent cannot read by design.

Escalation

Some cases leave the boundary: an amount above the owner's authority, or a pattern that repeats across accounts. The brief names the person it goes to and travels with the case, so the escalation hands over facts instead of a summary of facts.

The no-change case

Sometimes the payment recovered before anyone looked. Then the workflow exits without posting, which is the no-op pattern: silence when nothing changed, so every notification that does arrive means something. That pattern carries the matching obligation. A run that could not complete its check must alert, because "nothing changed" and "the check failed" are different outcomes and get different reports.

What you need to set it up

Read-only access to the billing and support systems, with keys scoped at the provider to the endpoints the collection step needs. Every query is written and approved before the workflow takes its first event, and the event payload carries an identifier, never a query.

One script connection per source, with credentials attached as bindings and injected at network egress so the script never holds a raw secret. The registry takes OpenAPI and GraphQL specs. It also takes an MCP server, or a Postgres DSN queried read-only, and a lead registers the connection.

One custom skill per source, describing the fields the brief uses and the ones it must not guess at.

Workflow configuration: the trigger, the script node, the agent node and the gate. On the webhook trigger, set hmacSecret to the provider's signing secret, as a literal, a ${VAR} reference or a secret.NAME swarm reference. Then set verification.format with its header name, and add timestampKey, signatureKey and toleranceSeconds for the timestamped form. Keep the gate on any external message and on any step a person cannot undo.

A named owner and a named backup, written into the workflow, because a brief addressed to a role rather than a person is a brief nobody reads.

Human review of every brief before anything leaves the building. The pipeline prepares. It does not act.

One honest note on the sources: the reporting playbook reaches Stripe only as a warehouse table joined through PostHog, so there is no shipped Stripe or billing connector behind this design. The collection step is one you write against your provider's own API, which is also why it stays read-only and small.

Decision boundaries

Agent prepares	Person decides
Collect payment status and account context	Retry or refund a charge
Compare the sources, including their timestamps	Issue a credit
Draft the internal brief	Change a financial record
Flag gaps and stale reads	Make any fraud call
	Send any customer message

The table is the whole design in two columns. Everything on the left is repeatable and cheap to check. Everything on the right is irreversible, so it stays with a person who can be asked why.

Triage itself is a queue rather than an alert stream. The owner works the oldest case first and closes it by recording the decision and the reason, so the next investigation of the same account starts from what was decided last time instead of from zero.

Where to go next

The multi-source reporting playbook covers the collection and synthesis pattern this design reuses, including the deterministic fetch step and the secrets boundary. If your team is still deciding which recurring work deserves an agent at all, the field guide for small companies covers the operating model this page sits inside.

References

1. Reports from Multiple Sources, agent-swarm.dev docs. https://docs.agent-swarm.dev/docs/playbooks/reports-multiple-sources
2. Pattern: No-op When Nothing Changed, agent-swarm.dev docs. https://docs.agent-swarm.dev/docs/playbooks/patterns/no-op-workflows
3. Pattern: HITL Gates (Human-in-the-Loop Approval), agent-swarm.dev docs. https://docs.agent-swarm.dev/docs/playbooks/patterns/hitl-gates
4. Workflows, agent-swarm.dev docs. https://docs.agent-swarm.dev/docs/concepts/workflows
5. Script connections, agent-swarm.dev docs. https://docs.agent-swarm.dev/docs/guides/script-connections