API DOCUMENTATIONVERSION 1.0REST

Integration reference for partner teams

End-to-end reference for init-auth, hosted verification, callback handling, and signature consumption. Designed for security-first integration.

Developer PortalRun Test FlowHome
Quick Start Guide
Six implementation milestones from setup to production.
1

Get Your Credentials

Contact the FraudShield team to receive your partnerId and API key. You'll get separate keys for test and live environments.

2

Enroll Users in Admin Panel

Open /admin, register/login, and create visual profiles for each user: choose 4 secret images, 2 secret letters, formula mode, and salt value.

3

Integrate init-auth in Your Backend

After your existing username/password login succeeds, call POST /api/product/v1/init-auth with partnerId, userId, callbackUrl, and a random state nonce.

4

Redirect User to Verification

Use the verifyPath from the init-auth response. Either redirect the user or open it in a popup window.

5

Handle the Callback

When the user completes (or fails) verification, we redirect to your callbackUrl with result, signature, and state parameters.

6

Validate with consume-result

Your backend calls POST /api/product/v1/partner/consume-result with the signature. If result is PASS, create your app session. Otherwise, deny login.

Redirect Flow

User clicks login on partner site → partner validates username/password.

Partner backend calls init-auth → gets verifyPath.

Partner redirects user to FraudShield: 302 → /verify/:sessionToken.

User solves visual challenge on FraudShield hosted page.

FraudShield redirects back to callbackUrl with result + signature + state.

Partner backend calls consume-result to validate → creates session on PASS.

Pros: Simple, works everywhere. No popup blocking issues.
Cons: User leaves partner site briefly.

Popup Flow

User clicks login on partner site → partner validates username/password.

Partner backend calls init-auth → gets verifyPath.

Partner frontend opens popup: window.open(verifyPath, ...).

User solves visual challenge in popup.

Popup sends postMessage to opener with result + signature.

Partner frontend receives message, calls backend to consume-result.

Pros: User stays on partner site. Seamless UX.
Cons: Popup may be blocked by browser. Need fallback to redirect.

Endpoints

POST/api/product/v1/init-auth
Partner Backend → FraudShield

Start a visual verification session after the user has logged in on the partner site.

Headers

Content-Type: application/json
x-api-key: YOUR_API_KEY

Request Body

{
  "partnerId":   "hdfc_bank",          // Your partner ID (assigned during onboarding)
  "userId":      "customer-001",       // The user's ID in YOUR system
  "callbackUrl": "https://yoursite.com/auth/visual/callback",  // Where we redirect after verification
  "state":       "random-nonce-abc123" // CSRF nonce (you generate, we echo back)
}

Response Body

{
  "sessionToken": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "verifyPath":   "/verify/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "expiresAt":    "2026-02-16T12:05:00.000Z"
}

Important Notes

  • callbackUrl must be in the partner callback allowlist (configured server-side).
  • callbackUrl must use HTTPS in production.
  • state must be a unique random value per request — used for CSRF protection.
  • Response status: 201 Created.

Code Examples

init-auth and consume-result snippets by backend language.

init-auth

// Node.js — Start visual verification
const res = await fetch(
  `${process.env.FRAUDSHIELD_URL}/api/product/v1/init-auth?mode=live`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.FRAUDSHIELD_API_KEY,
    },
    body: JSON.stringify({
      partnerId: "your_company",
      userId: "user@example.com",
      callbackUrl: "https://yoursite.com/callback",
      state: crypto.randomUUID(),
    }),
  }
);
const { sessionToken, verifyPath } = await res.json();
res.redirect(verifyPath);

consume-result

// Node.js — Validate result
const res = await fetch(
  `${process.env.FRAUDSHIELD_URL}/api/product/v1/partner/consume-result?mode=live`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.FRAUDSHIELD_API_KEY,
    },
    body: JSON.stringify({ signature }),
  }
);
const { result, userId } = await res.json();
if (result === "PASS") createSession(userId);
HTTP Status Codes
Response mapping for integration and retry logic.
201

Session created (init-auth)

200

Request successful

400

Bad request — missing or invalid parameters

401

Unauthorized — invalid API key or expired token

403

Forbidden — callback URL not in allowlist or wrong API key

404

Not found — user not enrolled or session not found

409

Conflict — session already verified

410

Gone — session expired

423

Locked — too many failed attempts

429

Rate limited — too many requests

Security Controls
Built-in protections and partner-side best practices.

State Nonce (CSRF Protection)

Generate a unique random state for every init-auth call. On callback, verify it matches. This prevents cross-site request forgery.

Server-Side Validation

Never trust callback query parameters alone. Always call consume-result from your backend to cryptographically verify the signature.

API Key Security

Your API key must only exist in your backend environment variables. Never expose it in frontend code, mobile apps, or public repositories.

HTTPS Only

In production, callbackUrl must use HTTPS. Our API enforces this automatically.

Device Fingerprinting

The challenge must be solved on the same device/browser that loaded it. This prevents session hijacking and proxy attacks.

Session Expiry

Sessions expire after 5 minutes by default. Expired sessions cannot be verified.

Anti-Screenshot

Our verification page blocks screenshots, screen recording, and screen sharing. Visual secrets never appear in captured images.

Honeypot Detection

If a user enters the original (unmodified) number instead of the salted result, we flag it as a potential phishing relay.

Environment Configuration
Use separate keys for test and live environments.
# FraudShield integration
FRAUDSHIELD_BASE_URL=https://fraudshield.example.com
FRAUDSHIELD_API_KEY=pk_live_your-api-key-here
FRAUDSHIELD_PARTNER_ID=your_company_id
APP_BASE_URL=https://your-app.example.com

# Sandbox (optional, for ?mode=test)
FRAUDSHIELD_SANDBOX_URL=https://sandbox.fraudshield.example.com
FRAUDSHIELD_SANDBOX_API_KEY=pk_test_your-sandbox-key

# Next.js frontend proxy (if using our starter template)
BACKEND_API_BASE_URL=http://localhost:3000/api
PARTNER_SERVER_API_KEY=dev-partner-key-change-me