Fini for disputes and chargebacks

Fini handles the intake side of card disputes, chargebacks and fraud claims: it identifies the customer and the transaction, collects the dispute details in a structured Form, can freeze a compromised card through your API, opens the case in your dispute system through an Action, and replies with the case reference and the next steps your policy defines. The decision itself (whether the claim is valid, any provisional credit, the chargeback with the card network, and the final outcome) stays with your team and your systems, and Fini is configured so it never states or implies an outcome. That split, intake versus decision, is the design principle for this use case. Intake is repetitive, structured and time-sensitive, which suits a deterministic Intent Rule. Decisions carry financial, regulatory and customer-rights consequences, which belong to your dispute operations team and the policies your compliance team approves.

What Fini handles and what it hands to your team

Fini handles (intake)	Your team handles (decision)
Explaining how disputes work, what information is needed and what happens next, from Knowledge articles your compliance team approves.	Deciding whether the dispute or fraud claim is valid.
Identifying the customer and listing their recent transactions (User Attributes).	Provisional credit decisions and timing.
Working out which transaction the customer means, and asking when it’s ambiguous.	Filing and managing chargebacks with the card network, and any merchant representment.
Collecting the dispute reason, the date the customer noticed, and a description, as a typed Form submission.	Communicating the outcome of the investigation to the customer.
Freezing a card the customer reports as compromised, through your card API.	Anything involving suspected identity theft or account takeover, by your Escalation Topics.
Opening the dispute case through an Action and confirming the case reference.	Customers who disagree with an outcome, complaints, and regulator or ombudsman references.

How it works in Fini

Dispute intake uses the same building blocks as the Card replacement walkthrough, which is the closest end-to-end recipe: a chained User Attribute, a Form for structured input, chained Tools, and a Reply Rules gate for risk.

Building block	What it does for disputes	Where
Tags	A custom tag group (the example uses `Topic`) with Tag Group available in Rulebooks on and separate tags for `disputes` (the customer contests a transaction) and `fraud_claim` (the customer says they didn’t make it). Default groups such as Type of Issue have a locked tag list, so they can’t take a tag like `fraud_claim`. The “when not to apply” section of each tag matters: a refund request for a known purchase is not a dispute.	Tags
User Attributes	A `Customer Identity` attribute with two chained Data Collection Steps: look up the customer (`account_id`, `account_status`, `is_high_risk`), then list recent transactions (`recent_transactions`). Turn on Visible to AI for the transaction list so the agent can ask which one the customer means; keep risk flags off it.	Attributes
Actions	`Create Dispute Case` (writes to your dispute or case-management system), and for fraud claims, `Freeze Card`. Mark inputs `required` so the Tool node can’t fire without them.	Actions
Intent Rule	Gates on intent and account state, resolves the transaction, renders the Form, opens the case and confirms the reference.	Intent Rules
Form	Collects typed, validated fields (field types such as `String`, `Number` and `Date` drive input validation). The submission appears in the transcript as a structured record of what the customer provided.	Intent Rules
Reply Rules	Internal Comment with `Topic Equals disputes`, so the confirmation is reviewed before the customer sees it. Or No Reply for dispute types you want handled only by humans.	Reply Rules
Prompts	The Planning Prompt’s Escalation Topics for patterns that should go straight to a human (“fraud dispute” is a documented example), and Predefined Replies in Main Guidelines for wording your compliance team requires verbatim.	Prompts
Guardrails	A Custom rule that fails any reply implying a dispute outcome, a refund, or a timeline the rule output didn’t provide. Confidential attributes for fields such as internal case notes.	Guardrails

Example behavior tree

This is an example to adapt. Field names, tag values and the Form fields depend on your dispute system and the information your team needs to open a case.

Steps  (root)
├── Check: Topic Equals disputes
├── Check: account_status Equals active
├── Read:  resolve `transaction_id` (String) from the message and recent_transactions
├── Form:  "Tell us about this transaction"
│     ├── Field: dispute_reason (String, required)
│     ├── Field: date_noticed (Date, required)
│     ├── Field: contacted_merchant (String, required)
│     ├── Field: description (String, required)
│     └── Form Error: description fewer than 20 characters
├── Tool:  Create Dispute Case
│     in:  account_id, transaction_id, dispute_reason,
│          date_noticed, contacted_merchant, description
│     out: case_id, next_steps_summary
└── Reply: confirm case_id; explain next_steps_summary;
           do not promise an outcome, a credit or a date

How it runs:

Two Checks gate the rule on intent and on an active account before anything is written.
The Read picks the transaction the customer described from recent_transactions. If it can’t pick exactly one, wrap the rest of the tree in a Fallback whose second child is a Reply listing the candidates, the disambiguation pattern from the Card replacement walkthrough.
The Form collects the details as typed fields, with Form Error children for validation. Forms render in the widget; on email-only channels, replace the Form with a sequence of Reads and Replies, as the card replacement walkthrough’s channel notes describe.
Create Dispute Case opens the case in your system and returns its reference. next_steps_summary comes from your system, so the agent describes the next steps your team defined rather than composing its own.

For fraud claims, a separate rule (or a sibling branch under a Fallback root) gates on fraud_claim, calls Freeze Card first, and then tells the customer the card is frozen and a specialist will follow up. The card replacement walkthrough explains why freezing is a safe first step: it’s reversible, and it stops further use while your team investigates.

What you need

What	Why	Where
An authenticated channel	Disputes act on a payment instrument. Identify the customer with a signed JWT in the widget, or through the helpdesk’s authenticated user. On unauthenticated channels, add an identity check before any Tool fires (see the identity verification note in the Card replacement walkthrough).	Widget
Customer and transaction lookup endpoints	Read-only. Feed the `Customer Identity` attribute.	Your core banking, ledger or card processor API
A case-creation endpoint	Writes the dispute case and returns a reference and next-step text. Should accept an idempotency key so a repeated message doesn’t open two cases.	Your dispute or case-management system
A card freeze endpoint (fraud claims)	Freezes the card and returns a confirmation id.	Your card processor or card-management API
Credentials scoped to these operations	Stored in the Data Step Headers JSON (for example an `Authorization` header). Endpoints you build should follow the API contract.	Actions
Approved dispute articles and wording	The agent explains the process from Knowledge; compliance-required phrases go in Predefined Replies.	Knowledge, Prompts
A sandbox	Test Suite runs don’t dry-run your Actions, and Execute live actions calls your real systems, including case creation and card freezes. Use Simulate rule execution, or point the Actions at a sandbox.	Test Suite

Guardrails and escalation

Disputes are where you should choose the most conservative pattern your team can operate, and loosen it once you have evidence from production.

Pattern	What happens	When to use it	How to configure it
Intake, then hand off	The rule opens the case, and the reply tells the customer a specialist will follow up.	Most card disputes. The customer gets a reference immediately; your team owns the decision.	The example tree, with a Reply that says the team will follow up.
Draft for review	The rule runs and opens the case, but the reply posts as an internal note. A human sends the customer-facing message.	When every customer-facing dispute message must be reviewed.	Internal Comment card: `Topic Equals disputes`.
Human only	The agent doesn’t engage on the conversation.	Dispute types your policy reserves for people, or high-risk customers.	No Reply card, for example `Topic Equals fraud_claim` AND `is_high_risk Equals True`, or an Escalation Topics entry in the Planning Prompt.
Hold the write itself	The rule collects details and posts an internal note; a human opens the case.	When opening a case is itself a step your team must authorize.	Split into two rules, the pattern described under “Holding the destructive Action itself” in the Card replacement walkthrough.

Reply Rules don’t stop Tools. An Internal Comment rule changes who sees the reply. The Tools in the Intent Rule (case creation, card freeze) still run. If a step must not happen without a human, keep it out of the automated tree.

Regulated steps

Card and electronic-payment disputes are often subject to regulated timelines and notice requirements, which vary by jurisdiction, product and card network. Fini doesn’t know or apply those timelines on its own. Your compliance team defines them; you encode the customer-facing parts in approved Knowledge articles and Predefined Replies, and keep timeline-bearing decisions (acknowledgment, provisional credit, final outcome) with your team and systems. For regulated steps, use the internal-note or human-only patterns above, and add a Main Guidelines rule such as “Never state whether a dispute will succeed, whether a credit will be issued, or by when, unless the value comes from the rule output.”

To confirm (internal, remove before publish): Can we tell customers that the AI Steps trace and transcript (including the timestamp of the Form submission) are retained and exportable as evidence of when dispute intake happened, and for how long they’re retained? Compliance should review this whole section before publish.

Other escalation signals to configure:

Escalation Topics in the Planning Prompt for identity theft, account-takeover signals and threats of legal action or regulator complaints (the default legal and regulatory trigger already covers the last).
No Reply with Human Agent Assigned Equals True, so the agent doesn’t talk over a specialist who has picked up the case.
Guardrails with a Custom rule for outcome promises, and Banned terms for phrases your team never uses about disputes.

What to measure

Scope Analytics to your dispute and fraud tags with the Tags filter, or to the dispute rule with the Intent rule filter.

Metric	Where	What it tells you
AI resolution rate for the intent	Conversation Status doughnut, share Resolved by AI	How often intake finishes without a human. With the intake-then-handoff pattern, many dispute conversations are expected to end Escalated to Human Team by design, so read this alongside your pattern choice.
AI Resolve Rate and Escalated Rate	Intent rule breakdown row for the dispute rule	Whether the rule reaches case creation or leaks before it.
Human escalation rate	KPI card, with the filter applied	Your team’s dispute workload arriving from the agent.
Escalation reasons	Escalation reason filter	API or System Failure means case creation or lookup failed; Ambiguous or Unclear Input means transaction resolution needs work; Escalation Constraint is your policy.
CSAT	Average CSAT and the CSAT filter	How customers felt about intake, separate from the eventual outcome.

Card replacement

Step-by-step fintech build with chained attributes, a Form, chained Tools and a Reply Rules risk gate.

Reply Rules

Internal Comment and No Reply for sensitive intents, and the priority order.

Prompts

Escalation Topics in the Planning Prompt and Predefined Replies in Main Guidelines.

Guardrails

Reply checks that rewrite or escalate replies before delivery.

Escalation and handoff

How the handoff reaches your team on each surface, and what context comes with it.

Refunds and returns

For refund requests on purchases the customer recognizes.

For a comparison of AI platforms for fintech dispute handling, see the guide on usefini.com.

Use cases

Walkthroughs

Industry setup

How-tos

Fini for disputes and chargebacks

What Fini handles and what it hands to your team

How it works in Fini

Example behavior tree

What you need

Guardrails and escalation

Regulated steps

What to measure

Card replacement

Reply Rules

Prompts

Guardrails

Escalation and handoff

Refunds and returns

​What Fini handles and what it hands to your team

​How it works in Fini

​Example behavior tree

​What you need

​Guardrails and escalation

​Regulated steps

​What to measure

​Related

Card replacement

Reply Rules

Prompts

Guardrails

Escalation and handoff

Refunds and returns

What Fini handles and what it hands to your team

How it works in Fini

Example behavior tree

What you need

Guardrails and escalation

Regulated steps

What to measure

Related