URL: /products/commerce-protection

---
title: Commerce Protection
description: "Chargeback prevention API for checkout. Verify buyers with blended IP, email, behavior, and velocity signals to block fraud before it hits your account. Coming soon."
---

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.

<Warning>
  Commerce Protection is **coming soon** and not live yet — `POST /v1/commerce/verify` is on the waitlist. The request and response shapes below show the planned contract and may change before launch. [Join the waitlist](https://formshield.dev/app) for early access, the final schema, and pricing.
</Warning>

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

```bash
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](/api-reference/introduction#response-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.

```json
{
  "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.

<CardGroup cols={2}>
  <Card title="IP reputation" icon="globe">
    Flags datacenter, VPN, proxy, Tor, and residential-proxy traffic via our own ipatlas data, plus ASN and geo so you can catch a buyer hiding their real origin or mismatching their billing country.
  </Card>
  <Card title="Email reputation" icon="envelope">
    Disposable-domain detection, domain age, MX and deliverability checks, and host detection. Brand-new throwaway addresses on a fresh order are a common chargeback tell.
  </Card>
  <Card title="Behavior and velocity" icon="clock">
    When the FormShield beacon is on your checkout, it adds behavioral signals (typed vs pasted vs autofilled fields, automation tells) and counts repeat orders from the same buyer, card, IP, or device across a short window.
  </Card>
  <Card title="One blended decision" icon="scale-balanced">
    The signals fuse into a single calibrated score and an `allow` / `review` / `block` decision with a per-signal breakdown, so you can tune your own thresholds instead of wiring four vendors together yourself.
  </Card>
</CardGroup>

## Response fields

<ResponseField name="score" type="float">
  Calibrated risk in `[0,1]`. `0.0` is a clean buyer; `1.0` is almost certainly fraud. Fold it into your own threshold, or use `decision` for a coarser read.
</ResponseField>

<ResponseField name="decision" type="string">
  The verdict: `allow`, `review`, or `block`. Derived from `score` against thresholds you tune for your traffic.
</ResponseField>

<ResponseField name="signals.ip" type="object">
  IP reputation: `risk`, `country_code`, `is_vpn`, `is_datacenter`, and related flags from our own ipatlas data.
</ResponseField>

<ResponseField name="signals.email" type="object">
  Email reputation: `risk`, `disposable`, `domain`, and deliverability tells.
</ResponseField>

<ResponseField name="signals.behavior" type="object">
  Behavioral telemetry from the FormShield beacon: `risk`, `automation`, and `pasted_fraction`. Present when the beacon is on your checkout.
</ResponseField>

<ResponseField name="signals.velocity" type="object">
  Order velocity across a short window: `risk`, `orders_24h`, `distinct_cards`, and related repeat-order counts.
</ResponseField>

## Endpoints

<ParamField path="POST /v1/commerce/verify" type="endpoint">
  Verify a buyer at checkout: blends IP, email, behavior, and velocity into a calibrated score and an `allow` / `review` / `block` decision. **Coming soon** — on the waitlist. Each call costs 30 credits.
</ParamField>

## Common questions

<ParamField path="How do I add a chargeback prevention API to my checkout?" type="question">
  Commerce Protection is coming soon. When it ships, you make one `POST` to `/v1/commerce/verify` with the buyer's email, IP, and order amount before you capture the payment, then act on the `allow`, `review`, or `block` decision it returns. Join the waitlist to get early access and the final request schema.
</ParamField>

<ParamField path="How is this different from my payment processor's fraud tools?" type="question">
  Your processor scores the card and the transaction. Commerce Protection blends signals your processor doesn't see — IP reputation, email reputation, on-page behavior from the FormShield beacon, and order velocity — into one decision, so you can stop a fraudulent order before it ever reaches authorization.
</ParamField>

<ParamField path="What does a verify cost and when is it available?" type="question">
  Each call to `/v1/commerce/verify` costs 30 credits and is metered like every other FormShield endpoint. The product is not live yet; it's in waitlist. Join the waitlist for launch updates and pricing.
</ParamField>

## Next steps

<CardGroup cols={2}>
  <Card title="IP Intelligence" icon="globe" href="/products/ip-intelligence">
    The IP reputation that feeds the IP signal — VPN, proxy, datacenter, and residential-proxy detection.
  </Card>
  <Card title="Email Intelligence" icon="envelope" href="/products/email-intelligence">
    The email reputation that feeds the email signal — disposable, deliverability, and domain age.
  </Card>
  <Card title="Voight" icon="fingerprint" href="/products/voight">
    The behavioral and proof-of-work capture that feeds on-page behavior.
  </Card>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    The response envelope, authentication, and error codes shared by every endpoint.
  </Card>
</CardGroup>