Froddy Documentation

Froddy sits before the payout, takes one request, and returns allow, hold, or block before money moves.

Froddy is a pre-payout control layer for automated payouts. It helps stop duplicates, broken limits, and payout logic errors before money leaves. The final action stays with your backend.

What Froddy does

Checks a request before the payout is sent
Returns one of three verdicts: allow, hold, block
Catches duplicates, rule errors, and logic failures
Maintains a single decision log before money moves

What Froddy does not do

does not send money
is not a bank, PSP, or payout rail
does not replace KYC/AML
is not a full anti-fraud replacement

How it works

Your backend sends a request to Froddy before the payout.
Froddy checks the rules and request context.
You receive allow, hold, or block in response.
The final action — send the payout, put it on hold, or stop it — stays on your side.

What to send in a request

Send only the data needed for the decision. By default, Froddy does not require raw PII. In many scenarios, hashed or pseudonymous identifiers are sufficient, along with technical and business fields that help verify duplicates, limits, and rules.

Typically sufficient:

payout or transfer identifier
user, account, or partner identifier
amount and currency
route, method, or destination type
metadata relevant to rule checks
idempotency key or external identifier
event timestamp and related context

What verdicts the API returns

allow — the request can proceed
hold — the request should be stopped for additional review or manual decision
block — the request should be rejected

Use this set of verdicts consistently throughout your integration.

Quick start

Open Demo and review the request and response format.
Create an account and start with the demo.
Add one pre-payout call before sending money.
Handle allow, hold, or block on your side.
Connect webhook notifications if needed.

Endpoint and access

Requests are sent via POST to /v1/evaluate. Authentication is via the X-API-Key header with your API key. The demo tenant works without a key. The endpoint is idempotent: a repeated request with the same event_id returns the original decision without re-evaluation.

Minimum required fields

Required fields: event_id, entity_id, amount. All other fields are optional with defaults: currency — USD, event_type — payout, timestamp — current UTC time, metadata — empty object. The timestamp must not differ from current time by more than 24 hours.

Request example

{
  "event_id": "po_20260306_001",
  "entity_id": "usr_9f1c2a7b",
  "amount": 15000,
  "currency": "RUB",
  "timestamp": "2026-03-06T10:15:00Z",
  "metadata": {
    "partner_id": "partner_42",
    "route": "manual_payout"
  }
}

Response example

{
  "event_id": "po_20260306_001",
  "verdict": "hold",
  "rule_id": "R-CEIL",
  "reason": "Single tx $15,000.00 exceeds hold threshold $10,000.00",
  "evaluated_at": "2026-03-06T10:15:01Z"
}

Errors and response handling

400 — invalid request (e.g. timestamp differs from current time by more than 24 hours)
401 — missing or invalid X-API-Key
429 — rate limit exceeded; retry after a few seconds

Notifications

Froddy supports a webhook-first scenario for notifications about events and changes related to request processing. Use webhook as the primary public way to receive these signals.

Webhook: what to consider

The webhook fires only for hold and block verdicts. Delivery is best-effort with no retries. Payload contains: event_id, verdict, rule_id, reason, amount, entity_id, evaluated_at. The webhook URL is set via PUT /v1/webhook with body {"url": "https://..."}.

Data and decision log

Froddy helps build a decision log before money moves. By default, you can work without raw PII using hashed or pseudonymous identifiers. This simplifies data minimization and audit of payout decisions.

If you need a DPA or a description of data processing, contact us.

What's next

Demo Start free Contact