Finic
ContactTry the API
Card fraud

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.56 to $0.75 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.00056 to $0.00075 per decision ($0.56 to $0.75 per 1,000) for these examples' 16,070 to 21,435 input tokens
  • Latency: 216 to 232 ms for these examples, the median of 5 calls each through api.finic.ai from US-West

Examples

Three debit card claims, each sent with four months of card authorizations, six months of account activity, 3-D Secure and online banking logs, contact history and the merchant's order details where it has them: a member disputing game-console orders placed from his own phone, a retiree whose card number was tested and used overnight by someone else, and a member disputing orders her ex-partner placed after he moved out.

Open in Playground

Open in Playground

Open in Playground

A yes/no answer is Grayson's probability that it's true. A choice answer is the top option and Grayson's confidence: 0% when every option is equally likely, 100% when one option has all the probability. A score answer is the expected level, numbering the levels in its criteria from 0, with its confidence measured the same way and, when no level reaches 70%, each level's probability. 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, and give provisional credit when the answers are split, as in the ex-partner case.

Call it from your code

Save an example as request.json, such as fraud.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:

  • Card and account history. Months of authorizations (declines included) and account activity show the member's normal pattern, earlier purchases at the merchant and any money pressure.
  • 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.
  • The merchant's order details, where the card network's order-details service has them: the merchant account's email and phone, the ship-to address, delivery and device.
  • 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, and earlier contact notes. Grayson reads them against the records; contradictions are what investigators look for.

Add your own policy

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 when every disputed transaction had strong authentication (chip and PIN, or a one-time-code challenge), confirmed delivery to the address on file, and no compromised-account alert on the card in the 180 days before it.

Your intake denial policy adds this to the state of the obvious example:

{
  "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 every disputed transaction meets all three of these conditions: (1) it 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 (not frictionless) 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 had no card network compromised-account alert (CAMS) in the 180 days before the transaction. If any condition is not met for any disputed transaction, do not deny at intake: 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, confidence 83%first_party, confidence 77%
authorized_likelihood3.92 of 4, confidence 96%3.90 of 4, confidence 95%
records_contradict_claim99% true98% true
resolutiondeny, confidence 96%provisional_credit, confidence 82%

In the game-console case, two of the three orders passed 3-D Secure without a challenge, and the card was in a compromised-account alert 117 days before the first order, so the policy calls for provisional credit and an investigator's decision instead of a denial at intake. The other answers stay the same: the records still point to the member.

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 state, before the final decision.

Cost and latency

ExampleInput tokensPer decisionPer 1,000 decisionsLatency
Obvious20,490$0.00072$0.72227 ms
Legitimate16,070$0.00056$0.56216 ms
Ambiguous21,435$0.00075$0.75232 ms

You pay only for input tokens, at $0.035 per million, and each request is rounded up to the next millionth of a dollar, so a request with a larger state costs proportionally more; every response reports its size in usage.input_tokens. Latency is the median of 5 calls each through api.finic.ai from US-West, and 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.4.0-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.

Fleet fuel cards

Grayson checks a fleet card's fuel authorization against the truck's telematics, its fill history and the station, separates cloned cards and fuel theft from routine fills, and picks approve, alert, decline or block.

On this page

ExamplesCall it from your codeThe problemWhat to sendAdd your own policyWhere 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