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_scoreis the analyzer's score. On card payments it is also read as a probability through Ward's reference map (score_kind: reference_calibrated,pat your base rate,interval,calibration), andoutcomegives a probability per option withconfidence.typologywalks 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 carrya2a.payer_ref(Ward reads the payer's history) and one for single payments without it, so both give a probability at yourbase_rates.transfer(default 0.005, an assumption).risks.aml: sendaccount.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) andwith_this_payment, the signals the payment itself brings. Advisory. Without movements, AML is listed innot_assessed.risks.sanctions: the payee screening on bank transfers, withhard_stopandreview_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.