Where to Integrate

Mubeen scores risk on the actions users take in your product. Each integration point is a place in your flow where you call the Mubeen API — from your backend, with the device ID collected client-side by the SDK. This page maps the most common user flows to the event type you should send and the exact moment to fire it.

Rule of thumb

Instrument every flow where a user proves who they are, creates an account, changes account details, or moves money. Each flow maps to one event_type — if your flow isn't listed, agree the mapping with Mubeen (see below); the schema is flexible and Mubeen adapts it to your data.

Integration Points at a Glance

User Flow	Event Type	When to Fire	Category
Sign-in	signin	On sign-in attempt, before granting a session	Non-monetary
Registration / Sign-up	registration	On account-creation attempt, before the account is activated	Non-monetary
Change email	email_change	When the user submits the new email	Non-monetary
Change phone number	phone_change	When the user submits the new phone number	Non-monetary
Change password (authenticated)	password_change	When the user submits the new password	Non-monetary
Change security settings (2FA, trusted devices, recovery)	security_settings_change	When the user submits the setting change	Non-monetary
Checkout / cart completion	checkout	At the point of purchase, before payment processing	Monetary
Payment	payment	When a payment transaction is executed	Monetary
Money transfer	transfer	When a transfer between accounts is submitted	Monetary
Refund	refund	When a refund is processed	Monetary
Deposit / top-up	credit	When funds are credited to an account	Monetary
Publish a listing	listing	When a listing is created	Non-monetary

note

Only monetary events (checkout, payment, transfer, refund, credit) carry a transaction_amount — send it together with a currency (ISO 4217, e.g. USD). For non-monetary events the amount can be omitted or 0. See Event Type Examples for full payloads.

Flows without a dedicated event type yet

Some flows — forgot-password / password-reset requests and adding a payment method — do not have a dedicated event type in the public schema. Your Mubeen schema is adapted on our side, so contact your account manager to agree the mapping (and any custom fields) before wiring these flows.

Flow-by-Flow Guide

Sign-in

Trigger: the moment the user submits credentials — before you decide to grant a session.

• Send event_type: "signin" with the submitted email/phone, the device_id from the SDK, and the client IP. Include user_id (required when the account is known) — it anchors the request to the customer.
• Act on the decision: log → record and let the request through; allow → create the session; challenge → step-up (OTP, captcha); review → hold the sign-in in a pending/limited state until Mubeen's callback delivers allow or block; block → reject or throttle.
• Report the outcome via the feedback endpoint (success, fail, fraud, rejected) so the model learns from real sign-in results.
• Catches: credential stuffing, brute force, account takeover.

Example payload: signin event

Registration / Sign-up

Trigger: on account-creation attempt — before the account is activated or the first session is granted.

• Send event_type: "registration" with the new user's email, name, phone, and the device_id from the SDK.
• A device that has already created several accounts is a strong fraud-farm signal — device_id is what links them.
• Act on the decision as above (log, allow, challenge, review, block) — for review, create the account in a pending state until the callback resolves it.
• Feedback outcomes: success, fail, fraud, rejected.
• Catches: fake account creation, bot sign-ups, fraud farms.

Example payload: registration event

Account Detail Changes (Email / Phone / Password / Security Settings)

Trigger: when the user submits the change — one event per change type.

• Four dedicated event types keep account-takeover signals separate so fraud rules can treat them differently:
  • Email change → event_type: "email_change" — include new_user_email
  • Phone change → event_type: "phone_change" — include new_phone_number
  • Password change (authenticated) → event_type: "password_change" — password changes made through a forgot-password flow are a different signal; agree that mapping with Mubeen first
  • Security settings (2FA, trusted devices, recovery options) → event_type: "security_settings_change"
• Always include user_id (required) to anchor the request to the account being changed, plus the device_id and ip_address.
• An attacker who already has a session will often change the email or phone, or disable 2FA, to lock the real owner out — this is your best chance to catch account takeover after sign-in. Separate event types let rules weight a 2FA disable from a new device far higher than, say, a phone correction.
• Feedback outcomes: success, fail, fraud, rejected.

Example payloads: email_change · phone_change · password_change · security_settings_change

Checkout / Cart Completion

Trigger: at the point of purchase — before payment processing.

• Send event_type: "checkout" with the order details, transaction_amount and currency, payment fields, and the device_id.
• Act before the charge: log → proceed and record; allow → proceed; challenge → step-up authentication; review → authorize but do not capture (or hold the order in a pending_review state) until Mubeen's callback delivers allow or block; block → refuse the order.
• Feedback outcomes include the monetary ones: dispute, chargeback, refund — report them when they happen later.
• Catches: stolen-card purchases, reshipping fraud, bad-agent purchases.

Example payload: checkout event

Payment

Trigger: when the payment transaction is executed.

• Send event_type: "payment" with transaction and payment-instrument data plus transaction_amount and currency.
• Use this instead of (or alongside) checkout when the payment happens outside a cart flow — e.g. one-click purchases, subscription charges.

Example payload: payment event

Other Monetary Flows

• Money transfer → transfer: P2P or between-account transfers, submitted amount and beneficiary context.
• Refund → refund: send a refund validate event when you process a refund (distinct from the refund feedback outcome on the original payment) — patterns across refunds expose refund abuse.
• Deposit / top-up → credit: money-in flows such as wallet top-ups.

Examples: transfer · refund · credit

Listing / Content Publishing

Trigger: when a listing or publication is created.

• Send event_type: "listing". Marketplace spam and scam listings cluster on reused devices and IPs.

Example payload: listing event

Common Patterns

Client-side collection, server-side validation

Every flow above follows the same shape — the SDK runs in your frontend, the decision happens on your backend:

┌──────────────┐   device ID + form   ┌──────────────┐      validate      ┌──────────┐
│   Browser    │ ───────────────────▶ │   Backend    │ ─────────────────▶ │  Mubeen  │
│  (SDK)       │ ◀─────────────────── │              │ ◀───────────────── │    API   │
└──────────────┘      response        └──────────────┘      decision      └──────────┘

1. The JavaScript SDK (or Android / iOS SDK) collects the device ID on the page where the flow happens — sign-in form, registration form, checkout page.
2. Your frontend passes the device_id to your backend along with the form submission.
3. Your backend calls POST /api/v1/generic/validate with the full risk-context payload.
4. Your backend applies the decision and optionally reports the outcome to the feedback endpoint.

Feedback closes the loop

After each flow completes, report what actually happened — both successes and failures — via the feedback endpoint. This is optional but strongly recommended: it is how the models learn your traffic and get sharper over time.

What's Next

1. Collect the device ID — Client-Side Integration (HTML), React, Android, or iOS
2. Send your first validation — Server-Side Integration
3. Copy full request/response examples — Event Type Examples