Skip to main content

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

​
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

At this stage, ZendFi enforces:
  • merchant-wallet sanctions screening
  • blocked-IP screening
  • pre-create fraud scoring
Hard blocks happen before payment insertion.

​
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)

​
Submit Transaction (standard)

Submission applies:
  • stored fraud-score gate
  • submit-time fraud re-check when customer_wallet is present

​
Submit Gasless Transaction

Uses the same risk gate model as standard submission.

​
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

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

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.