Commerce Protection

Verify a buyer with blended IP, email, behavior, and velocity signals and get an allow, review, or block decision before you capture the payment. One POST /v1/commerce/verify returns a calibrated risk score and a decision, with the per-signal breakdown behind it.

Chargebacks land weeks after checkout, by which time the product has shipped and the fee and dispute are yours to eat. By the time your processor flags a card as fraud, the order is already gone. Commerce Protection moves the decision earlier — to the moment of checkout, before you authorize or capture — so you can stop the obvious fraud while it can still be stopped.

When to use it

Use Commerce Protection at checkout on high-risk flows — physical goods that ship, digital goods that are instantly redeemable, stored-value top-ups, anything where a chargeback weeks later is yours to eat. Call it server-side after the buyer submits the order and before you authorize or capture the payment, then act on the decision: let clean buyers through, route the gray zone to manual review or step-up verification, and block the obvious fraud before it ever reaches your processor.

It complements your payment processor rather than replacing it. Your processor scores the card and the transaction; Commerce Protection blends the signals your processor never sees — IP reputation, email reputation, on-page behavior from the FormShield beacon, and order velocity — into one decision you control.

How it works

1. Send buyer details at checkout

   POST /v1/commerce/verify with the buyer’s email, IP, order amount, and any FormShield beacon token before you authorize or capture the payment. No PII beyond what you already collect at checkout is required.

2. FormShield blends the signals

   One call fuses IP reputation (datacenter, VPN, proxy, residential proxy), email reputation (disposable, domain age, deliverability), behavioral telemetry from the beacon, and velocity across recent orders into a single calibrated risk score.

3. Act on the decision

   You get a 0.0–1.0 score and an allow, review, or block decision, plus the per-signal breakdown. Allow clean buyers through, route the gray zone to manual review or step-up verification, and block the obvious fraud before it costs you a chargeback.

Quickstart

Send the order and the buyer’s email and IP from your backend with a Bearer API key, then read the decision off the response. Replace YOUR_API_KEY with your secret key.

curl -X POST https://api.formshield.dev/v1/commerce/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_5821",
    "amount": 249.00,
    "currency": "USD",
    "buyer": {
      "email": "buyer@example.com",
      "ip": "203.0.113.42"
    }
  }'

The response is wrapped in the standard envelope. data.score and data.decision are the verdict; data.signals breaks the score down by source so you can see which tell drove it.

{
  "version": "1",
  "data": {
    "score": 0.81,
    "decision": "block",
    "signals": {
      "ip": { "risk": 0.7, "country_code": "NG", "is_vpn": true, "is_datacenter": false },
      "email": { "risk": 0.6, "disposable": true, "domain": "mailinator.com" },
      "behavior": { "risk": 0.4, "automation": false, "pasted_fraction": 0.9 },
      "velocity": { "risk": 0.8, "orders_24h": 6, "distinct_cards": 4 }
    }
  },
  "error": null,
  "metadata": { "request_id": "req_8f2c0a14", "processing_time_ms": 38, "credits": 30 }
}

Gate on decision for a single allow / review / block, or read signals.*.risk to apply your own thresholds per source.

The signals

The verdict fuses four independent signals so no single tell decides the outcome. Read score and decision for one answer, or inspect each block to see what drove it.

Response fields

Endpoints

Common questions

Next steps