Warddocs
Cookbooks

Classify a chargeback

An issuer's disputes team receives cardholder claims every day: "I don't recognise this", "they charged me twice", "it never arrived". For each one it must pick the right reason code, check the time limit and gather the right documents before filing.

d = ward.decide("chargeback", {
    "network": "mastercard",
    "claim": {"text": claim.description},                       # the cardholder's own words
    "transaction": {"transaction_date": tx.date, "amount": tx.amount, "currency": tx.currency,
                    "card_present": tx.card_present, "entry_mode": tx.entry_mode, "three_ds": tx.ucaf,
                    "merchant_contacted": claim.contacted_merchant, "expected_delivery_date": order.eta},
    "original": {"reference": tx.order_id},
})

if d.decision == "APPROVE":          # a code applies: file it before the deadline
    file_chargeback(d.reason_code, deadline=d.result["deadline"], documents=d.result["candidates"][0]["documents"])
elif d.decision == "STEP_UP":        # missing facts, a waiting period, or friendly-fraud indicators
    send_to_analyst(d.id, d.result["reason"])
else:                                # no chargeback right: tell the cardholder why
    close_claim(d.result["reason"])

Set your minimum once: PUT /api/v1/ward/thresholds with {"chargeback": {"min_amount": 50, "currency": "USD"}}.

When the dispute closes, report the result so Ward learns from it:

ward.report_outcome("chargeback_lost_by_merchant", closed_at, decision_id=d.id)   # JS: ward.reportOutcome({...})

See Chargeback and Outcomes.