SpendPreflightEvery decision reason
Use decision and flags for control flow; preserve the human-readable explanation.
Live features and staging previews are distinguished. Index coverage is not yet available.
Preflight reason templates
Existing reasons are strings prefixed allow:, hold: or block:, not a universal enum. Values inside braces vary. The three endpoint_* identifiers and invalid_index_rule are prefixes followed by detail. This list covers the deployed gate; unknown future reasons must not be treated as allow.
| Decision | Reason template / prefix | Meaning |
|---|---|---|
| block | no payment options found in input | No usable options; correct the request. |
| hold | could not determine merchant domain | Supply the merchant domain/resource URL. |
| block | domain {domain} is on blocklist | Your policy blocks this merchant. |
| hold | domain {domain} not on allowlist | Strict domain policy needs review. |
| block | merchant name exactly matches an OFAC SDN entry | Verify the possible identity match before proceeding. |
| hold | merchant name possibly matches an OFAC SDN entry | Ambiguous names require a human to disambiguate. |
| hold | domain registered {days} days ago (< {threshold}) | A new domain signal is not evidence of fraud. |
| hold | domain has no DNS A record | No A record observed. DNS errors remain unknown. |
| block | unsupported or malformed payment option | Unsupported scheme, oversized amount or malformed EVM destination. |
| block | invalid payment amount | Negative or nonfinite payment amount. |
| block | network {network} not allowed | Network differs from caller policy. |
| block | asset {asset} is not a known USDC contract | Wrong network/asset pair or another currency. |
| hold | amount could not be priced in USD | No conversion assumption is made. |
| block | amount ${amount} exceeds max ${maximum} | Single-payment budget exceeded. |
| hold | amount ${amount} above hold threshold ${threshold} | Human/policy approval required. |
| block | daily cap ${cap} would be exceeded (spent ${spent}) | Daily budget exceeded using supplied/reserved spend. |
| block | payTo {payTo} is on blocklist | Blocked wallet. |
| hold | payTo {payTo} not on allowlist | Configured wallet allowlist requires review. |
| block | payTo {payTo} is an OFAC SDN-listed address | Public sanctions-list wallet match; verify before acting. |
| hold | payment option has no payTo | Cannot identify the receiving wallet. |
| hold | invalid_index_rule | Invalid category-price configuration. |
| hold | endpoint_price_above_category_median | quote exceeds the configured category median multiple. |
| hold | endpoint_failed_last_3 | three usable failed unpaid checks; not paid-delivery testing. |
| hold | endpoint_payto_changed | payee changed for this network/asset; investigate before paying. |
| allow | all rules passed | No configured rule fired. This is not certification or a guarantee. |
Payee check flags
Risk uses the strongest applicable signal. A name match is not proof the merchant is the listed entity. Address/name data is public OFAC screening, not certification.
| Flag | Risk contribution | Meaning |
|---|---|---|
| sanctioned_address | high | Exact wallet match in the public SDN index. |
| sanctioned_name_exact | high | Exact normalized name/alias match; identity still needs review. |
| sanctioned_name_possible | medium | Fuzzy name match, not proof of identity. |
| invalid_domain | medium | Domain could not be interpreted as a public merchant domain. |
| new_domain | medium | Known domain age below 30 days. |
| domain_age_unknown | unknown | No usable registration date; unknown is not low risk. |
| domain_no_dns | medium | No A record observed. MX is reported separately. |
Request and payment errors
400/405/408/413 reject bad method/input/body before payment. Index lookup may return invalid_url, invalid_method, endpoint_not_listed (404), method_required (409) or index_unavailable (503). receipt_signing_unavailable and facilitator_unavailable are 503 before settlement. settlement_outcome_unknown means a transfer may already have happened: check the original authorization and chain, never automatically create a fresh payment.