Verify before pay
Use POST /v1/verify/before-pay when an agent receives a raw payment-protocol payload
and needs a trust verdict before settlement — an x402 402 Payment Required body, an
AP2 CartMandate/PaymentMandate, or an ACP checkout context. Faro extracts the merchant,
endpoint, and receiving address, verifies each in parallel, and returns the riskiest
VerdictResult. Faro is advisory only — it never settles, authorizes, or moves funds.
When to call it
| Protocol | Typical trigger | What to send in payload |
|---|---|---|
| x402 | HTTP 402 challenge body | The full JSON body from the 402 response (accepts, resource, …) |
| AP2 | Cart / payment mandate | The mandate object (ap2.mandates.CartMandate or PaymentMandate) |
| ACP | Agent-commerce checkout | Merchant + checkout context as structured in your ACP integration |
A malformed payload degrades to 🟡 yellow / review — never a crash, never a false 🟢.
Example requests
curl -X POST https://api.farofinance.app/v1/verify/before-pay \
-H "Authorization: Bearer $FARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"protocol": "x402",
"payload": {
"x402Version": 2,
"resource": { "url": "https://api.example.com/premium-data" },
"accepts": [{
"scheme": "exact",
"network": "eip155:8453",
"payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C"
}]
}
}'Request body
| Field | Required | Description |
|---|---|---|
protocol | yes | ap2, x402, or acp |
payload | yes | The raw protocol object — pass it through unchanged from the rail |
region | no | ISO country hint for bare phone labels in payee checks |
Legacy convenience endpoint
POST /v1/verify/payment-intent (and MCP verify_payment_intent) still accepts a
flattened descriptor (merchant, payee, recipient, resource_url, …) for simpler
integrations. New agent flows should use before-pay with the raw payload.
Branch on the verdict
Same contract as every other verify route:
{
"verdict": "red",
"recommended_action": "block",
"reason": "Receiving address appears on a sanctions list.",
"signals": [{ "name": "onchain_sanctioned", "severity": "critical", "detail": "…" }]
}
allow— proceed with settlement (your payment rail still decides).warn/review— surface the reason; consider elicitation or manual review.block— abort the payment flow.
Ongoing alerts
After a before-pay check, register a watch on the counterparty so you receive
artifact.flagged webhooks if the entity turns bad later:
curl -X POST https://api.farofinance.app/v1/me/watch \\
-H "Authorization: Bearer $FARO_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{ "type": "payee", "value": "merchant@okaxis" }'
On hosted MCP, call the watch_artifact tool with the same artifact type and value.