Radar API Reference

Full reference for the Radar Event API endpoint, request payload, and response schema.

Back to: Radar Event API Overview · Integration Guide

POST/event

Create Event

Record any user, business, or financial event. The API automatically routes the event to the appropriate processing queue based on the event field and returns a risk score with a recommended action.

Endpoint

POST https://sandbox-api.nearpay.io/radar/v1/event

Required header

Header Name	Value
`api-key`	Your Radar API key

Request

POST

/event

{
  "event_id": "b245f5e1-3a6a-4c9c-8a30-20bd8a590f34",
  "event_timestamp": 1715969600,
  "user": {
      "id": "1d5a2d25-1ac9-455b-9a5a-aa4027356ce5",
      "email": "[email protected]"
  },
  "device": {
      "id": "d087ea4e-2d85-4e8d-9a49-fb7cf1c5fa3b",
      "os": "iOS",
      "brand": "Apple",
      "model": "iPhone 14",
      "os_version": "17.1",
      "sim": {
          "carrier": "STC",
          "country": "SA"
      },
      "trust": {
          "rooted": false,
          "tempered": false,
          "hooked": false,
          "debuggable": false,
          "emulator": false,
          "virtual": false,
          "malware": false
      }
  },
  "browser": {
      "name": "Safari",
      "version": "16.0",
      "user_agent": "Mozilla/5.0",
      "accept_language": "en-US",
      "content_language": "en",
      "timezone": "Asia/Riyadh"
  },
  "location": {
      "latitude": 24.6555,
      "longitude": 24.6555,
      "mocked": true
  },
  "request": {
      "id": "ebd6e0b5-3c9f-4a8a-9400-bc821cbd5c88",
      "card_present": true, // false when it e-commerce
      "channel": "pos", // "e-commerce" | "pos" | "softpos" 
      "entry_mode": "tapped", // "swiped" | "dipped" | "tapped" | "entered"
      "created_at": "2025-05-13T08:30:00.000Z",
      "amount": 15075,
      "is_3ds": true,
      "currency": "SAR",
      "is_authenticated":true, 
      "currency_exponent": "2",
      "card": {
          "id": "6f7e74c3-0c87-4e88-85d0-49b497ce0fdd",
          "pan": "4111111111111111",
          "brand": "Visa",
          "last4": "1111",
          "exp_month": "12",
          "exp_year": "29",
          "verification": "cvv" // "cvv" | "cvc" | "none"
      },
      "merchant": {
          "id": "e85c33f5-5bd5-41ce-bf57-e2a875f9f107",
          "business_id": "57c53b63-1087-48e8-8615-4b494d2d98c3",
          "mcc": "3444"
      },
      "cardholder": {
          "ip": "192.168.1.100",
          "verification": "3ds" // "signature" | "otp" | "pin" | "none" | "3ds"
      }
  }
}

Success Response

Response 201

{
  "action_id": "string",
  "action": "allow" | "block" | "unknown",
  "state": "normal" | "monitored" | "paused" | "blocked" | "unknown"
}

Field	Type	Description
`action_id`	string	Unique identifier for the action taken on this event.
`action`	string	Recommended action. `allow` to proceed, `block` to reject (risk score ≥ 80), `unknown` if undetermined.
`state`	string	Current entity state: `normal`, `monitored`, `paused`, `blocked`, or `unknown`.

Event Types

Events related to user authentication, session management, and account activities.

Event Type	Description
`login_succeeded`	User successfully logged in
`login_failed`	User login attempt failed
`logged_out`	User logged out
`registration_succeeded`	New user registration completed
`registration_failed`	User registration attempt failed
`password_reset_requested`	User requested a password reset
`password_updated_successfully`	User successfully updated their password
`email_update_requested`	User requested an email change
`email_update_failed`	Email update attempt failed
`email_updated`	User email successfully updated
`mobile_updated`	User mobile number updated
`mobile_update_requested`	User requested a mobile number change
`mobile_update_failed`	Mobile update attempt failed
`mobile_otp_requested`	Mobile OTP verification initiated
`mobile_otp_verified`	Mobile OTP successfully verified
`mobile_otp_failed`	Mobile OTP verification failed
`email_otp_requested`	Email OTP verification initiated
`email_otp_verified`	Email OTP successfully verified
`email_otp_failed`	Email OTP verification failed
`session_refreshed`	User session was refreshed
`session_created`	New user session created
`session_expired`	User session expired
`session_revoked`	User session was revoked

Request Schema

Field	Type	Required	Description
`event_id`	UUID v4	No	Unique identifier for the event. Auto-generated if not provided.
`event`	string	No	The event type. Must be one of the valid event types.
`event_timestamp`	number	Yes	Unix timestamp (milliseconds) when the event occurred.
`ip`	string	No	Client IP address (IPv4 or IPv6).
`device`	Device	No	Device information.
`browser`	Browser	No	Browser/web client information.
`location`	Location	No	Geographic location data.
`user`	User	No	User information.
`session`	Session	No	Session information.
`business`	Business	No	Business entity information.
`merchant`	Merchant	No	Merchant information.
`terminal`	Terminal	No	Payment terminal information.
`domain`	Domain	No	Domain/website information.
`request`	PaymentRequest	Conditional	Payment request details. Required for financial events.
`response`	FinancialResponse	Conditional	Payment response details. Required for financial events.
`transfer`	TransferRequest	No	Transfer request information.
`withdraw_request`	BasicRequest	No	Withdrawal request information.
`deposit_request`	BasicRequest	No	Deposit request information.