> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zendfi.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Fraud Controls

> Endpoint-level fraud and sanctions behavior, status codes, and integration guidance.

# Fraud Controls API Behavior

This page documents how ZendFi fraud and sanctions controls appear at the API layer so your integration can handle risk outcomes deterministically.

For customer-facing policy and operations, see [Fraud and Compliance](/security/fraud-and-compliance).

## Enforcement Stages

ZendFi evaluates risk in multiple request stages:

1. **Payment creation** (`POST /api/v1/payments`)
2. **Checkout transaction build** (`POST /api/v1/payments/{payment_id}/build-transaction`)
3. **Transaction submission**
4. `POST /api/v1/payments/{payment_id}/submit-transaction`
5. `POST /api/v1/payments/{payment_id}/submit-gasless-transaction`

## Endpoint Response Matrix

### Create Payment

```
POST /api/v1/payments
```

At this stage, ZendFi enforces:

* merchant-wallet sanctions screening
* blocked-IP screening
* pre-create fraud scoring

Hard blocks happen before payment insertion.

| Status | When it happens                              | Typical payload shape                             |
| ------ | -------------------------------------------- | ------------------------------------------------- |
| `200`  | Payment created                              | Payment object                                    |
| `402`  | Blocked by sanctions/blocked-IP/fraud policy | `{ "error": { "code": "payment_blocked", ... } }` |
| `400`  | Validation error                             | `{ "error": { "field": "...", ... } }`            |
| `429`  | Merchant limits/rate controls                | Limit/usage error payload                         |

### Build Transaction

```
POST /api/v1/payments/{payment_id}/build-transaction
```

At this stage, ZendFi enforces:

* customer-wallet sanctions screening
* fraud check with payer wallet and request IP (when available)
* customer wallet binding to payment (wallet mismatch returns conflict)

| Status | When it happens                                       |
| ------ | ----------------------------------------------------- |
| `200`  | Transaction build succeeds                            |
| `403`  | Blocked by sanctions or fraud policy                  |
| `404`  | Payment not found                                     |
| `409`  | Payment no longer eligible for build (state conflict) |
| `410`  | Payment expired                                       |

### Submit Transaction (standard)

```
POST /api/v1/payments/{payment_id}/submit-transaction
```

Submission applies:

* stored fraud-score gate
* submit-time fraud re-check when `customer_wallet` is present

| Status | When it happens                                    |
| ------ | -------------------------------------------------- |
| `200`  | Submission accepted for verification               |
| `400`  | Invalid signature payload                          |
| `403`  | Blocked by fraud score/re-check policy             |
| `404`  | Payment not found                                  |
| `409`  | Signature conflict/replay or invalid payment state |
| `410`  | Payment expired                                    |

### Submit Gasless Transaction

```
POST /api/v1/payments/{payment_id}/submit-gasless-transaction
```

Uses the same risk gate model as standard submission.

| Status | When it happens                        |
| ------ | -------------------------------------- |
| `200`  | Submission accepted                    |
| `400`  | Invalid gasless transaction payload    |
| `403`  | Blocked by fraud score/re-check policy |
| `404`  | Payment not found                      |
| `409`  | Signature/state conflict               |
| `410`  | Payment expired                        |

## Integration Recommendations

1. Treat `payment_blocked`, `403`, and `402` as security outcomes, not generic failures.
2. Show user-safe copy and route users to support with payment ID.
3. Do not auto-retry blocked requests without additional customer verification.
4. Log payment ID, endpoint, status code, and request correlation data for support triage.
5. Use idempotency keys on write paths to avoid duplicate operations during retries.

## Merchant Fraud Endpoints

ZendFi provides merchant-scoped fraud read APIs under authenticated dashboard/session routes.

### List Fraud Flags

```
GET /api/v1/merchants/me/fraud/flags
```

Query parameters:

* `resolved` (`true`/`false`) optional
* `severity` (`low`, `medium`, `high`, `critical`) optional
* `resolution_type` (`safe_false_positive`, `confirmed_fraud`, `other`) optional
* `page` (default `1`)
* `limit` (default `25`, max `100`)

Response includes merchant-owned fraud flags with pagination metadata.

### Merchant Fraud Stats

```
GET /api/v1/merchants/me/fraud/stats
```

Response fields include:

* `total_flagged`
* `unresolved_flags`
* `resolved_safe_flags`
* `blocked_payments`
* `false_positive_rate`
* `estimated_fraud_prevented_usd`
* `high_risk_payments_24h`
* `average_fraud_score_24h`

Formula definitions:

* `false_positive_rate = resolved_safe_flags / total_flagged`
* `estimated_fraud_prevented_usd = sum(amount_usd) of fraud-blocked payments`

## Fraud Webhook Events

When a payment fraud score is elevated, ZendFi emits:

* `fraud_flag_raised`

When a payment is blocked by fraud checks, ZendFi emits:

* `fraud_payment_blocked`

The payload follows the standard payment webhook shape and includes payment metadata fields such as:

* `metadata.fraud_score`
* `metadata.fraud_flags`
* `metadata.fraud_review_required`

These events are emitted in addition to payment lifecycle events.

## Safe Client Messaging

Recommended customer-safe response copy:

> "Your payment needs additional security review. Please contact support with your payment ID."

Avoid exposing internal fraud signals or threshold details in user-facing UI.

## Notes

1. Current sanctions enforcement is at create-payment and build-transaction stages.
2. Current submit-stage enforcement is fraud-based.

## Related Docs

* [Payments](/api-reference/payments)
* [Refunds](/api-reference/refunds)
* [Disputes](/api-reference/disputes)
* [Payment Links](/api-reference/payment-links)
* [Fraud and Compliance](/security/fraud-and-compliance)