Chargeback
Availability: turned on per API deployment; until then these endpoints answer 404. Ask Mandate to enable it for your account.
A cardholder disputes a transaction. Which Visa or Mastercard reason code applies, is it within the time limit, what is missing, and what documents do you need? Ward reads the cardholder's claim (structured, or their own words in English or Spanish) and the transaction's facts, and answers by the networks' rules. For fraud codes it adds a friendly-fraud check before you file.
Type: chargeback · Endpoint: POST /api/v1/chargeback/classify · Visa and Mastercard card disputes, issuer side
Request
curl https://api.mandatelabs.ai/api/v1/decide \
-H "X-API-Key: $WARD_API_KEY" -H "Content-Type: application/json" \
-d '{"type": "chargeback", "input": {
"network": "mastercard",
"claim": {"text": "No reconozco este cargo, nunca compré en esa tienda"},
"transaction": {"amount": 640, "currency": "USD", "transaction_date": "2026-10-20",
"card_present": false, "three_ds": "none"},
"original": {"reference": "ord_88231"}}}'
d = ward.decide("chargeback", {"network": "mastercard", "claim": {"type": "duplicate"},
"transaction": {"transaction_date": "2026-10-20", "other_transaction": "rrn 612345678901"}})
/decide infers the type from network with claim or reason_code.
| Field | What it is |
|---|---|
claim.type |
not_authorized, not_recognized, duplicate, amount_differs, paid_by_other_means, late_presentment, currency, atm_cash_not_dispensed, not_received, not_as_described, counterfeit_goods, credit_not_processed, cancelled_recurring, cancelled_services, no_show, addendum, transaction_did_not_complete, misrepresentation, installment, credit_posted_as_purchase, authorization, questionable_merchant, other |
claim.text |
The cardholder's own words, read when type is not sent |
transaction |
transaction_date, processing_date, amount, currency, card_present, entry_mode (chip, contactless, magstripe, fallback, keyed, ecommerce), chip_card, three_ds (authenticated, attempted, none), card_status (active, counterfeit, lost_stolen, never_received), authorization (approved, declined, none, stand_in), merchant_contacted, expected_delivery_date, delivery_date, returned, credit_expected_date, cancelled_at, agreed_amount, other_transaction, presentment_date, merchant_listed |
reason_code |
A code you already chose: Ward says whether it fits (code_check) |
as_of |
The date to count time limits from (default today) |
original, disputed, prior_purchases, logs, dispute |
Optional, for fraud codes: Ward's record of the authorisation and the evidence for the friendly-fraud check |
Answer
The decision is whether to file:
| Decision | Means |
|---|---|
APPROVE |
A reason code applies and can be filed now |
STEP_UP |
A code may apply but facts are missing, a waiting period runs, friendly-fraud indicators were found, or no code fits the claim as described |
DECLINE |
No chargeback right: 3-D Secure authenticated or chip read (fraud), time limit passed, under your minimum amount, or the cardholder has not tried the merchant |
{"type": "chargeback", "decision": "APPROVE", "reason_code": "4863", "category": "third_party_fraud",
"sub_reason": "Cardholder does not recognize: potential fraud", "deadline": "2027-02-17",
"result": {"version": "chargeback-2", "claim": {"type": "not_recognized", "source": "text", "matched": "no reconozco"},
"reason": "Mastercard 4863 (Cardholder does not recognize: potential fraud) applies; file by 2027-02-17.", "days_left": 96,
"candidates": [{"network": "mastercard", "code": "4863", "category": "third_party_fraud", "time_limit_days": 120,
"clock_start": "transaction processing date", "conditions_met": ["card not present", "cardholder not recognized"],
"conditions_missing": [], "blocked_by": [], "fit": "applies",
"documents": ["Cardholder affidavit: ...", "Authorization record and transaction logs for the disputed transaction"]}],
"claim_assessment": {"version": "chargeback-1", "classification": "third_party_fraud", "first_party_score": 0.15}}}
category:third_party_fraud,authorization,processing_error,consumer_disputeormerchant_fraud.candidates: every code the claim could fall under on the network, withfit(applies, possible, blocked), the conditions met and missing, the time limit, its clock and deadline, a waiting period (wait_until) where one applies, and the documents to gather.claim_assessment(fraud codes): the account takeover review and the networks' compelling-evidence rules (Visa CE3.0, Mastercard First-Party Trust). When earlier undisputed purchases share the cardholder's device or IP, filing goes to an analyst first: the merchant can likely defeat it.
Time limits follow the networks: Mastercard 120 days (90 for 4808 and some 4834 conditions), Visa 120 days (75 for 11.x), 13.1 up to 540 days from the transaction; credit not processed waits 15 days after the expected credit.
Your filing rules
PUT /api/v1/ward/thresholds with {"chargeback": {"min_amount": 50, "currency": "USD"}}: claims under the amount answer DECLINE.
Outcomes and learning
Report the dispute's result as an outcome: chargeback_lost_by_merchant (filing was right) or chargeback_won_by_merchant (the merchant proved the cardholder made it).