Warddocs
Capabilities

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_dispute or merchant_fraud.
  • candidates: every code the claim could fall under on the network, with fit (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).