Warddocs
Capabilities

Account takeover

A cardholder disputes a transaction. Was the account taken over first, or was it the holder? Ward reads the login and account-change logs before the transaction and answers with a likelihood, the evidence, a timeline and a dispute view.

Type: ato · Endpoint: POST /api/v1/ato/review

Request

curl https://api.mandatelabs.ai/api/v1/decide \
  -H "X-API-Key: $WARD_API_KEY" -H "Content-Type: application/json" \
  -d '{"type": "ato", "input": {
        "disputed": {"occurred_at": "2026-10-30T02:14:00Z", "amount": 1200, "merchant": "GIFTCARDS4U", "device_id": "dv_new_91", "country": "ROU", "known_devices": ["dv_iphone_12"]},
        "logs": [
          {"event_type": "sim_swap", "occurred_at": "2026-10-29T21:02:00Z"},
          {"event_type": "password_reset", "occurred_at": "2026-10-29T21:40:00Z", "device_id": "dv_new_91", "country": "ROU"},
          {"event_type": "new_device_login", "occurred_at": "2026-10-30T02:05:00Z", "device_id": "dv_new_91", "ip_address": "185.220.101.4"}
        ]}}'
d = client.decide("ato", {"disputed": {"occurred_at": "2026-10-30T02:14:00Z", "amount": 1200, "device_id": "dv_new_91"},
                          "logs": [{"event_type": "sim_swap", "occurred_at": "2026-10-29T21:02:00Z"}]})
const d = await client.decide("ato", { disputed: { occurred_at: "2026-10-30T02:14:00Z", amount: 1200, device_id: "dv_new_91" },
  logs: [{ event_type: "sim_swap", occurred_at: "2026-10-29T21:02:00Z" }] });

Input

Field Description
disputed (required) occurred_at, and optional amount, merchant, device_id, country, known_devices
logs[] Up to 90 days before: event_type, occurred_at, device_id, ip_address, country
cardholder_ref Also read the events already sent to POST /api/v1/assess/events
prior_undisputed_with_merchant Earlier purchases at the merchant that were not disputed
disputed.ip_address, account_login, shipping_address, email, phone, billing_address, mcc, recurring Optional: compared with earlier purchases for the first-party misuse answer
prior_purchases[] Earlier purchases on the card: occurred_at, merchant, amount, disputed, and the same identifiers
dispute filed_at, reason (fraud, unrecognized, not_received, not_as_described, cancelled_recurring, other), merchant_contacted, delivery_status (delivered, not_delivered, returned, in_transit, unknown; for digital goods and travel, whether the service was used) or the older delivered, delivered_at, cancelled_at (when the cardholder asked to cancel), cancellation_checked (you checked your cancellation records, even when there was none). Leave out what you do not know: unknown is not read as no
cardholder_disputes[] The cardholder's earlier disputes: at, outcome, reason

Event types: login_success, failed_login, new_device_login, password_reset, credential_change, contact_change, mfa_change, sim_swap, otp_to_new_number, payee_added, wallet_provisioned, card_replacement, session. Device ids are hashed per client before comparison; nothing is stored by the endpoint.

What it weighs

Points to a takeover Weight
SIM swap within 72 h 0.55
Code sent to a newly added number within 24 h 0.45
Contact or two-factor change within 7 days 0.35
Password reset or credential change within 72 h 0.30
New-device login within 24 h; disputed transaction from that device 0.30; +0.25
New payee or wallet token within 24 h 0.30
5+ failed logins in 24 h 0.25
Points to the holder in control Weight
Disputed transaction from a long-used device 0.30–0.45
Earlier undisputed purchases at the merchant 0.30
No account change in 30 days 0.25

likelihood = takeover × (1 − 0.5 × holder), each a noisy-OR.

First-party misuse (advisory)

When enabled for your account, the review adds first_party_misuse: the chance the cardholder made the purchase they now dispute (answer yes / no, probability, top_reasons), with network_evidence:

  • ce3_qualifying, ce3_met: earlier undisputed purchases at the merchant, 120 to 365 days before the dispute, sharing at least two of IP, device, login and delivery address, one of them IP or device (two are needed, as in Visa Compelling Evidence 3.0).
  • fpt_categories, fpt_met: matches in the device, delivery and identity groups (all three, as in Mastercard First-Party Trust).

It also reads delivery or service-used evidence, whether the merchant was contacted first, a cancellation before the charge, the cardholder's earlier disputes and the takeover likelihood above (a takeover points to a third party). Identity credit needs an IP or device match, as both network rules do: a login without the account's device or IP is the takeover pattern, and an IP alone on a new device is a shared network.

answer is yes only when the evidence that separates first-party misuse from its look-alikes is there: an earlier purchase on the same device or IP; account events (or CE3.0-level device/IP evidence) so a takeover could have shown; delivery or service-used evidence; and for subscriptions a checked cancellation record. Otherwise the answer is insufficient_data, with needs listing what to send. Fewer than two of IP, device, login and delivery address need a probability of 0.70 for a yes. coverage shows how many identifiers and account events were read.

Identifiers are compared only as keyed hashes and are not stored. The model is trained on synthetic cases only, so it is advisory: it never changes decision. Use it to decide which disputes to contest with compelling evidence.

Calibrated takeover answer (advisory)

When enabled for your account, the review adds takeover_model: the probability that the purchase was made after an account takeover (answer yes / no, or insufficient_data when no account events were sent, with needs), with top_reasons and readings. It reads the evidence above plus new-device logins and failed logins over 7 days, how new the purchase's device is, and whether account changes came from the account holder's own devices. It is trained on synthetic cases only and is advisory: likelihood and decision are unchanged.

Result and decision

likelihood, evidence, timeline (relative to the transaction), dispute_view (third-party fraud vs first-party misuse, with the usual scheme categories such as Visa 10.4 and Mastercard 4837), needs and typologies.

Likelihood Decision Meaning
≥ 0.60 DECLINE Takeover likely: secure the account, accept the fraud claim
≥ 0.30 STEP_UP Possible takeover: review
holder evidence ≥ 0.50 STEP_UP First-party indicators: review before accepting a fraud claim
otherwise APPROVE No takeover evidence

Here DECLINE means "takeover likely: accept the customer's claim", the opposite of what it means for a payment. Read outcome (beta, where risk lines are enabled): likely_account_takeover, possible_account_takeover, first_party_indicators or no_takeover_evidence. With model: "ward-2", takeover likely answers STEP_UP with that outcome, and decision_ward_1 keeps the ward-1 answer. The calibrated takeover and first-party answers also appear under answers as Nouls (noul: probability of yes).