Warddocs
Capabilities

Payment

One call for every payment: Ward works out who initiated it (cardholder, merchant, account holder or AI agent), routes it to the right engine, and returns a fraud probability and a decision under your cut-offs.

Type: payment · Endpoint: POST /api/v1/assess · Real-time (32K tokens per call)

Request

curl https://api.mandatelabs.ai/api/v1/decide \
  -H "X-API-Key: $WARD_API_KEY" -H "Content-Type: application/json" \
  -d '{"type": "payment", "input": {
        "amount": 249.90, "currency": "USD", "mcc": "5732", "merchant_name": "BESTTECH ONLINE", "country": "USA",
        "initiator": "cardholder",
        "card": {"presence": "card_not_present", "three_ds_result": "Y", "ip_country": "NGA", "device_id": "dv_7f1c"},
        "cardholder": {"profile": {"avg_ticket": 60, "home_country": "USA", "account_opened_at": "2023-04-02"}, "device_known": false},
        "external_ref": "auth_88231"}}'
d = client.decide("payment", {
    "amount": 249.90, "currency": "USD", "mcc": "5732", "merchant_name": "BESTTECH ONLINE", "country": "USA",
    "initiator": "cardholder", "card": {"presence": "card_not_present", "ip_country": "NGA"},
    "cardholder": {"profile": {"avg_ticket": 60, "home_country": "USA"}, "device_known": False},
    "external_ref": "auth_88231"})
const d = await client.decide("payment", {
  amount: 249.9, currency: "USD", mcc: "5732", merchant_name: "BESTTECH ONLINE", country: "USA",
  initiator: "cardholder", card: { presence: "card_not_present", ip_country: "NGA" },
  cardholder: { profile: { avg_ticket: 60, home_country: "USA" }, device_known: false },
  external_ref: "auth_88231" });

Input

Field Required Description
amount yes Transaction amount (> 0)
currency ISO 4217, default USD
rail CARD (default), A2A, WALLET, CRYPTO
initiator cardholder, merchant, accountholder, agent; inferred when omitted
mcc, merchant_id, merchant_name, country Merchant context (country ISO alpha-3)
card Card data elements: presence, pos_entry_mode, eci, three_ds_result, avs_result, cvv_result, bin, stored_credential, device_id, ip_address, ip_country, ip_proxy, billing_country, shipping_matches_billing, account_change_at, …
cardholder From your records: profile (home_country, avg_ticket, account_opened_at, kyc_level, …), recent transactions, device_known, events, earlier disputes (at, outcome, reason). Makes the first call as good as the hundredth
agent_id / agent_did, intent_context, runtime_evidence agent payments The agent, its declared intent and what it did before asking
a2a, crypto for those rails Bank-transfer or on-chain context
account The paying account's recent money in and out: movements (up to 200: at, signed amount, description, counterparty, channel, balance) and profile (customer_type, occupation, monthly_income, expected_monthly_inflow). Read in memory, never stored. With risk lines on, it gives an AML reading on this payment (advisory)
external_ref, idempotency_key, dry_run Your reference; dedupe; check only (records nothing)

How the initiator is decided

A declared initiator wins unless hard evidence contradicts it: an agent identifier or agent evidence (intent, a Verifiable Intent chain, runtime evidence) on a payment declared as a cardholder's, merchant's or account holder's; a merchant declaration on a present card, or with the cardholder in session (3-D Secure, device or IP) and no stored-credential or merchant-initiated flag; a cardholder declaration on a charge marked merchant_initiated_type. Conflicts or no evidence give STEP_UP with the reason: nothing is guessed. Agent payments go through the agent engine (intent_context required); cardholder and merchant payments through the card analyzer; rail: "A2A" through the bank-transfer analyzer.

Result

Field Meaning
risks.sanctions.match, .detail On a bank transfer with a sanctions hit: the listed party, the name or alias that matched, the list and the score, and the explanation
initiator, pipeline Who initiated and which engine decided, with how it was decided (declared / inferred, evidence, conflicts)
assessment.fraud_probability Fraud vs genuine (sums to 1 with legit_probability)
assessment.score_kind calibrated, heuristic, engine or unavailable
assessment.evidence_tier, advisory Claim ladder: STRUCTURE_ONLY → DISCRIMINATION → CALIBRATION
assessment.vectors Share of the evidence pointing at each typology
assessment.thresholds The cut-offs applied and their source (client or platform)
signals, typologies, notes What fired and why
first_party_misuse When enabled for your account: advisory chance this cardholder later disputes the purchase as fraud although they made it (answer yes / no / insufficient_data, probability, top_reasons). Trained on synthetic cases only; never changes the decision. Needs at least 5 earlier transactions or disputes

Decision: STEP_UP at fraud_probability ≥ 0.40, DECLINE ≥ 0.80 by default; set your own with PUT /api/v1/thresholds (assess_step_up_at, assess_decline_at). No score means STEP_UP.

Bank transfers: sanctions and jurisdiction are judged apart from fraud_probability. A strong payee match declines. A potential match, sanctions lists that could not be read, or a payee in a FATF call-for-action country keep the transfer at STEP_UP or above, listed in review_floors. A transfer that every signal together would have declined before Ward 1.5.1 still declines, with decline_kept: true.

Scams paid over several transfers (Ward 1.5.8): send a2a.payer_ref so Ward can see the payer's history. With it, Ward flags payments rising toward a payee first paid in the last 120 days (romance and investment scams average several payments each), a payer's first payment to a crypto exchange (set a2a.payee_type: "crypto_exchange"), and an account idle for 90 days or more that suddenly pays out half its balance to a new payee. Without payer_ref, each payment is judged alone.

Risk lines on a payment (beta)

Where enabled for your account, a payment answer adds risks:

  • risks.fraud: the fraud line. raw_score is the analyzer's score. On card payments it is also read as a probability through Ward's reference map (score_kind: reference_calibrated, p at your base rate, interval, calibration), and outcome gives a probability per option with confidence. typology walks the catalogs: domain, family, typology. On bank transfers the fraud line lists fraud signals only. Since Ward 1.5.8 it is read through a reference map too: one for transfers that carry a2a.payer_ref (Ward reads the payer's history) and one for single payments without it, so both give a probability at your base_rates.transfer (default 0.005, an assumption).
  • risks.aml: send account.movements (10 or more credits and debits over 30 days or more) and Ward reads AML over that window ending at this payment: priority (clear, monitor, alert, escalate) and with_this_payment, the signals the payment itself brings. Advisory. Without movements, AML is listed in not_assessed.
  • risks.sanctions: the payee screening on bank transfers, with hard_stop and review_floors.
"risks": {
  "fraud": {"status": "final", "raw_score": 0.67, "p": 0.067, "interval": [0.052, 0.085],
            "score_kind": "reference_calibrated", "advisory": true,
            "outcome": {"type": "choice", "choice": "STEP_UP",
                        "probabilities": {"APPROVE": 0.0, "STEP_UP": 0.85, "DECLINE": 0.15}, "confidence": 0.77},
            "gates": true},
  "aml": {"status": "final", "raw_score": 0.87, "gates": false,
          "priority": {"type": "score", "level": "escalate", "score": 3.0}}
}

The numbers above show the shape only. p is small at real base rates: a reference probability of 0.60 reads about 0.04 when 1% of payments are fraud. Set your own base rates with PUT /api/v1/ward/thresholds ({"base_rates": {"card": 0.004}}).

Calibration

POST /api/v1/assess/calibrate fits the probability to your own labelled card outcomes (at least 200 labels with 30 of each class), never pooled with other clients. Report outcomes with POST /api/v1/assess/{assessment_id}/outcome or decision feedback.