How to Investigate Payment Declines with Claude Code

A declined payment can create three queues: one for support, one for operations, and one for engineering. Each team opens a different system to answer the same question. What happened to this transaction?

The customer already gave you a reference. The expensive part is finding the matching records, checking what they mean, and deciding which explanation you can safely share.

This is a guide to building a payment investigation agent with Claude Code or Codex and running it in Runtime. The agent follows your support procedure, gathers the evidence, and prepares a reply. Your team reviews it before anything reaches the customer.

The short answer. Give the agent a transaction reference, tenant-scoped read access, and an approved investigation checklist. Have it compare the processor response with account policy and transaction history, cite the records behind its findings, and save a draft. Keep refunds, limit changes, and customer messages behind separate human approval.

Pick the first queue

Start with one payment rail and one support question. A card authorization decline and a returned bank transfer need different records and different explanations. Combining them in the first version makes the procedure harder to test.

Give each case an owner. A draft left in an unmonitored folder creates another queue, even if the investigation itself is excellent.

Walk through a case

In this illustrative example, TX-8042 was declined. The account policy allows $2,500 of daily spending, while the applicable authorizations including this attempt total $2,684. Those numbers are fictional sample data, not a customer result or a universal processor rule.

The important output is the chain of evidence. A reviewer should be able to see which account was checked, which policy applied, and how the total was calculated. A plausible sentence without those records isn't ready to send.

The stack

Use the systems your support team already checks. These are examples. Confirm each connector, API path, and permission scope during setup.

Job	Example tools
Receive the case	Pylon Zendesk
Read the processor record	Stripe Marqeta
Check account policy and ledger data	A scoped Postgres view or your internal account service
Investigate an application error	Datadog
Store the review and draft	Salesforce
Agent infrastructure	Runtime

Runtime supplies the agent's working environment, scoped credentials, and run record. Your processor and ledger remain the sources of truth. Start from the fintech and payments support solution for the complete workflow.

Step 1: Define access

Write down the boundary before connecting production data. Support access should resolve from the authenticated employee and the customer's account, rather than an account number typed into a prompt.

Enforce those rules in service accounts, database views, and tool permissions. A prompt saying "only read this customer" is useful context, but the underlying data service must also reject an out-of-scope request.

Ask your security team which fields can enter the model context, which may appear in logs, and which must remain in the source system. A link to a restricted record often gives the reviewer enough context without copying the entire record into a ticket.

Step 2: Create the agent with Claude Code or Codex

Start with anonymized examples, your current procedure, and descriptions of the approved tools. Ask Claude Code or Codex to build a specialized payment support agent around those inputs.

Create a payment decline investigation agent. Given an assigned case and transaction reference, identify the tenant from the trusted case context. Read only that tenant's approved processor, account-policy, and ledger records. Return a timeline, an explanation supported by source references, unanswered questions, and a customer reply draft. Stop when records conflict or access is missing. Don't send messages, retry payments, issue refunds, or change settings.

That task brief works as a starting point for either coding agent. The tool definitions, credentials, and permission settings still need to be configured for the chosen runtime. You aren't copying a prompt into an unrestricted session and calling it production.

Anthropic documents Claude Code permission rules. OpenAI documents Codex security controls. Review the applicable controls with whoever owns your deployment.

Ask the coding agent to create small, reviewable helpers for finding an authorization, reading the applicable limit, and assembling the evidence packet. Give those helpers explicit inputs and predictable outputs. Have engineering inspect the queries and test the account boundary before enabling unattended runs.

Step 3: Teach the investigation

An agent needs a method for resolving ambiguity. Start by matching transaction IDs across systems, then compare timestamps, currencies, statuses, and policy versions. Preserve the source value alongside any normalized value.

Use the processor's documented decline meanings. For example, Stripe's decline-code reference distinguishes causes and recommended next steps. Don't turn a generic processor response into a specific explanation without supporting evidence.

Investigate TX-8042 using the approved support procedure. Separate the processor's reported reason from our own account-policy findings. Show the authorization references used in the daily total and the timezone used for that day. If you can't establish the cause, say what remains unknown and which team should investigate next.

In the sample case, the agent should show the $2,500 limit and the authorizations behind the $2,684 total. It should also establish that this is the relevant limit for this transaction. Reading today's policy doesn't necessarily explain yesterday's decline.

Keep customer-facing language separate from internal findings. Security signals, internal risk thresholds, and unrelated account information may be useful to a reviewer without belonging in a customer message. Your approved reply policy decides what can be disclosed.

Step 4: Put it in the queue

Connect the reviewed agent to one eligible ticket category in Runtime. Supply credentials through the approved secrets interface, never in the ticket text or example prompt. Start with draft-only runs and a named reviewer.

Use the case ID and transaction reference to recognize repeated requests. A customer adding a comment should update the existing investigation or start an explicitly linked revision. It should not silently generate several incompatible drafts.

Define how the job ends: draft ready, missing information, unavailable source, or engineering escalation. Each outcome needs an owner and a visible status. A timed-out query should produce an incomplete investigation, not a confident answer assembled from whatever happened to load.

Treat ticket text, attachments, and retrieved pages as untrusted case material. Instructions inside them must not change the agent's access, recipient list, or approved procedure.

Test the difficult cases

Replay historical cases with identifiers and sensitive fields removed or replaced. Include examples your team remembers disagreeing about.

Test the review path too. Can a support lead open every cited record? Does rejecting a draft leave the case assigned? Can the next reviewer tell which version they approved?

What stays human

Your team owns policy exceptions, customer communication, refunds, and changes to account access. Engineering owns defects that require a code or configuration change. The agent can prepare a much better handoff for both.

An operational approval should identify the exact draft or action being approved. If the agent changes the recipient, amount, or explanation afterward, that revision needs another review under your procedure.

For a broader technical-support workflow, see how to cut support escalations to engineering. This payment-specific version adds financial context and tighter disclosure boundaries.

Measure useful work

Track time to a reviewable draft, reviewer minutes per case, evidence completeness, and the share of drafts accepted without factual corrections. Split the results by decline type so easy account-policy cases don't hide poor handling of ambiguous issuer responses.

Keep a separate count of wrong-customer lookups, unsupported explanations, and attempted unauthorized actions. Low investigation time doesn't compensate for a weak access boundary.

Compare against a small reviewed baseline before promising savings. The first milestone is a repeatable, trustworthy investigation. Expand the eligible queue only after reviewers can rely on the evidence.

The point

Give support a way to reach the evidence safely. A good payment agent turns a transaction reference into a reviewable explanation, with the unresolved questions still visible.