Finic
ContactTry the API
Recipes

Classify card disputes and detect friendly fraud

Grayson classifies card disputes as friendly fraud, account takeover or stolen card from authentication, logins and past disputes, and recommends a resolution.

Grayson checks a cardholder's unauthorized-transaction claim against how the transaction was authenticated, the logins and devices around it, and the cardholder's merchant and dispute history. It returns how likely the cardholder authorized the transaction, whether it looks like first-party (friendly) fraud, account takeover, a stolen card or an authorized purchase, and whether to approve, give provisional credit or deny, for about $0.06 per 1,000 decisions.

  • Decides: Classify unauthorized-transaction claims and choose provisional credit, approval or denial.
  • Call it: When a cardholder files an unauthorized-transaction claim
  • Questions: 2 choice, 1 score, 1 yes/no
  • Cost: $0.000060 per decision, $0.06 per 1,000, for this example's 1,688 input tokens
  • Latency: 219 ms for this example, the median of 5 calls through api.finic.ai from US-West

Example

A member disputes a $1,149 online electronics purchase that passed a one-time code sent to their phone, came from their home IP address and shipped to their home, though their card number was exposed in an unrelated breach about two weeks earlier.

Open in PlaygroundEdit and run this request in the Finic portal.
QuestionGrayson's answer
claim_typefirst_party, 73%
authorized_likelihoodVery likely (over 90%), 71%
records_contradict_claimYes, P(yes) 97%
resolutiondeny, 93%

Each percentage is Grayson's probability for the answer shown; for a yes/no question it's the probability of yes. A multiple-choice answer lists the options at 50% or more.

  • claim_type routes the case: first-party and authorized purchases to an investigator, account takeover to account security, stolen cards to chargeback and reissue.
  • authorized_likelihood: add "Likely" and "Very likely"; approve below a low cutoff, and have an investigator confirm a denial above a high one.
  • resolution: approve automatically only when the approve probability is high and the records don't contradict the claim; have a person review every denial.

Call it from your code

Save request.json and send it with your API key in GRAYSON_API_KEY:

curl https://api.finic.ai/v1/decide \
  -H "Authorization: Bearer $GRAYSON_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

The problem

An unauthorized-transaction claim can be third-party fraud, or first-party fraud by a cardholder who made the purchase and disputes it anyway. Rules handle the simple cases, such as chip and PIN with the card in the cardholder's hand, but miss the ones where the claim and the records disagree, such as a correct one-time code entered from the cardholder's home internet connection.

What to send

Send the claim with the records an investigator would pull:

  • How the transaction was authenticated. Chip and PIN or a 3-D Secure code narrows who could have made it.
  • Device, IP and shipping address from checkout. A match with the cardholder's banking sessions or home points to their household.
  • Logins and profile changes around the transaction. A reset, new device or contact change just before points to account takeover.
  • Merchant and dispute history. Undisputed earlier purchases, or repeated claims at merchants they keep using, point to the cardholder.
  • Compromise and testing signals. A breach alert or small test charge makes third-party fraud plausible, not proven.
  • The claim in the cardholder's words. Grayson reads it against the records; contradictions are what investigators look for.

Add your own criteria

Institutions draw the line for denying a claim at intake differently, and examiners expect you to follow your own written procedure, so put it in the request. This one allows a denial at intake only with strong authentication, confirmed delivery to the address on file, and no compromised-account alert on the card in the 180 days before the transaction.

Your intake denial policy adds this to the context:

{
  "disputes_procedure": "Debit card unauthorized-transaction claims, intake (procedure DC-7, rev. 2026-06). An intake analyst may deny a claim without provisional credit only when all three of these hold: (1) the transaction was authenticated with something only the member controls, meaning chip and PIN with the card in the member's possession, or a 3-D Secure challenge sent to a phone number unchanged for at least 30 days; (2) for goods shipped to an address, we hold the merchant's carrier delivery confirmation to the member's address on file; (3) the card has not appeared in a card network compromised-account alert in the 180 days before the transaction. If any of the three is not met, give provisional credit within 10 business days of the claim, request the merchant's evidence, and assign the case to an investigator, who makes the final decision. Never approve at intake a claim that our records contradict."
}
QuestionWithoutWith your intake denial policy
claim_typefirst_party, 73%first_party, 69%
authorized_likelihoodVery likely (over 90%), 71%Very likely (over 90%), 33%
records_contradict_claimYes, P(yes) 97%Yes, P(yes) 85%
resolutiondeny, 93%provisional_credit, 94%

Only the authentication condition holds (there's no delivery confirmation yet, and the card was in a compromised-account alert 17 days before the purchase), so the policy calls for provisional credit and an investigator's decision instead of a denial at intake.

Where to call it

  • At intake, while the cardholder is still on the phone, so the agent can see the answers and ask follow-up questions.
  • Send uncertain cases to an analyst with the answers attached, and give provisional credit if the investigation will run past 10 business days.
  • Call it again when the merchant's evidence arrives, with that evidence added to the context, before the final decision.

Cost and latency

This example is 1,688 input tokens, so a decision costs $0.000060: $0.06 per 1,000 decisions, or $60.00 per million. You pay only for input tokens, at $0.035 per million, and each request is rounded up to the next millionth of a dollar. A larger context costs proportionally more; every response reports its size in usage.input_tokens.

Grayson answered this example in 219 ms, the median of 5 calls through api.finic.ai from US-West. Latency grows with the number of input tokens. Add your own network time to api.finic.ai.

Evaluate on your own data

Score Grayson on your own past cases before you use it: a CSV with one row per case and a column with the right answer to each question. Every other column is sent as the case.

pipx install https://docs.finic.ai/downloads/grayson_cli-0.2.2-py3-none-any.whl
grayson eval my-cases.csv --questions https://docs.finic.ai/recipes/card-dispute-classification/questions.json --label claim_type=<column> --label authorized_likelihood=<column> --label records_contradict_claim=<column> --label resolution=<column>

Each --label names the column with that question's right answer:

  • claim_type: first_party, account_takeover, stolen_card, authorized_or_merchant
  • authorized_likelihood: a level, such as "Very likely (over 90%)"
  • records_contradict_claim: true or false
  • resolution: approve, provisional_credit, deny

Or run grayson on its own to set up your questions step by step. You get each question's accuracy and a CSV with Grayson's answer next to yours for every case.

Evaluate on your own data

How it works, what you get, and every option.

FAQ

Can Grayson tell friendly fraud from a genuine fraud claim?

It weighs the evidence an investigator uses: whether the authentication relied on something only the cardholder controls, whether the device and IP match their banking sessions, whether they've bought from the merchant before, and whether their statement fits those records. When the records conflict, as when a card number was exposed in a breach but the purchase passed a code sent to the cardholder's phone, the probabilities spread out, and that's the case to send to a person.

Does this replace a Regulation E investigation?

No. Regulation E requires a reasonable investigation of each claim and, when you find no error, a written explanation and the cardholder's right to the documents you relied on. Use Grayson to triage at intake, point investigators at the evidence and keep decisions consistent, and keep a person responsible for denials.

Does it work for credit card disputes?

Yes. The classification is the same, but credit card claims fall under Regulation Z, which caps the cardholder's liability for unauthorized use at $50 and lets them withhold payment of the disputed amount while you investigate, instead of requiring provisional credit. Change the resolution options to match your credit card process, or use network reason codes as choice options with descriptions.

Screen card authorizations for fraud in real time

Score card authorizations for fraud and choose approve, step up or decline, next to your existing rules.

Fraud typology classification

Label a fraud claim with a FraudClassifier class, scam type and contributing factors; decide reimbursement.

Recipes

Every use case, with its questions and cost per decision.

Card authorizations

Grayson screens card authorizations for card testing, fallback and card-not-present fraud from recent card activity, and picks approve, step up or decline.

Check deposits

Grayson decides whether a deposited check is counterfeit, altered, stolen or a duplicate, and whether to release funds, place an exception hold or reject it.

On this page

ExampleCall it from your codeThe problemWhat to sendAdd your own criteriaWhere to call itCost and latencyEvaluate on your own dataFAQCan Grayson tell friendly fraud from a genuine fraud claim?Does this replace a Regulation E investigation?Does it work for credit card disputes?Related recipes