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

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.
StatusWhen it happensTypical payload shape
200Payment createdPayment object
402Blocked by sanctions/blocked-IP/fraud policy{ "error": { "code": "payment_blocked", ... } }
400Validation error{ "error": { "field": "...", ... } }
429Merchant limits/rate controlsLimit/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)
StatusWhen it happens
200Transaction build succeeds
403Blocked by sanctions or fraud policy
404Payment not found
409Payment no longer eligible for build (state conflict)
410Payment 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
StatusWhen it happens
200Submission accepted for verification
400Invalid signature payload
403Blocked by fraud score/re-check policy
404Payment not found
409Signature conflict/replay or invalid payment state
410Payment expired

​
Submit Gasless Transaction

POST /api/v1/payments/{payment_id}/submit-gasless-transaction
Uses the same risk gate model as standard submission.
StatusWhen it happens
200Submission accepted
400Invalid gasless transaction payload
403Blocked by fraud score/re-check policy
404Payment not found
409Signature/state conflict
410Payment 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

​
Webhook Event: FraudFlagRaised

When a payment fraud score is greater than 50, ZendFi emits an additional webhook event:
  • fraud_flag_raised
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
This event is emitted in addition to payment_created.

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