Event Endpoints

Submit non-monetary events — onboarding steps, banking-detail changes, terminal activations, settlement-configuration changes, support contacts — for ingestion and, where enabled, risk screening.

Events let rules react to behaviour that has no transaction attached. A merchant changing its settlement account shortly after a spike in refunds is invisible to transaction monitoring, but visible here.

Not to be confused with webhook event types. This endpoint is how you send events into Orca. The event field values in Webhooks are outbound notifications Orca sends to you. The two vocabularies are unrelated: type here is free-form and defined by you.

Submit Event

Endpoint


POST /v1/event

Request Schema

Field	Type	Required	Description
`id`	string	Yes	Your unique identifier for this event. Must be non-empty
`type`	string	Yes	Event type. Free-form and defined by you, for example `onboarding_submitted`, `bank_details_changed`, `terminal_activated`, `settlement_updated`. Must be non-empty
`merchantId`	string	Conditional	Identifier of the merchant the event concerns. Provide `merchantId` or `merchant`, not both
`merchant`	object	Conditional	A full merchant object to create or update the merchant inline, as an alternative to `merchantId`. See Merchant for the object shape
`userId`	string	Conditional	Identifier of the user the event concerns. Provide `userId` or `user`, not both
`user`	object	Conditional	A full user object to create or update the user inline, as an alternative to `userId`
`timestamp`	number	No	When the event happened, in Unix epoch milliseconds. Defaults to the time of the request
`reference`	string	No	Your own reference for the event, if it relates to something trackable in your system. Must be non-empty if sent
`method`	string	No	How the event occurred, for example `web`, `mobile`, `ussd`, `api`. Must be non-empty if sent
`source`	string	No	Where the event originated, for example a service or channel name. Must be non-empty if sent
`metadata`	object	No	Free-form key/value object for anything else you want available to rules
`paymentInstrumentId`	string	No	Identifier of a payment instrument, such as a bank account, the event concerns. Must be non-empty if sent
`groupingId`	string	No	Identifier that groups related events together, so a series of events about the same subject or case can be correlated. Must be non-empty if sent

Timestamps

timestamp is when the event occurred, not when you sent it. Omit it for live traffic. Send it whenever the event is not being reported live, i.e. on any backfill or replay.

Note: type and method are lowercased when stored, so LOGIN and login are the same event type. Rules and event-window aggregations match on the lowercased value.

Subject is required

An event must be about someone. Provide a subject as an id (merchantId or userId) or as an inline object (merchant or user) — at least one is required, and a request with none is rejected with a VALIDATION_ERROR and nothing is stored. For a given subject, send the id or the object, not both: merchantId with merchant, or userId with user, is rejected. An inline merchant or user object is created or updated as part of the request. For B2B integrations merchantId is the normal key; userId is available where the event concerns an individual, such as a merchant’s authorised operator.

Example Request


{
  "id": "EVT123456",
  "type": "bank_details_changed",
  "merchantId": "MERCH123456",
  "timestamp": 1734167723000,
  "method": "web",
  "source": "merchant-portal",
  "reference": "change_req_9f2c1a",
  "paymentInstrumentId": "PINST987654",
  "groupingId": "MERCH123456",
  "metadata": {
    "previousBankName": "Test Bank",
    "newBankName": "Example Bank",
    "changedBy": "merchant_admin"
  }
}

To create or update the subject inline, send a merchant object instead of merchantId (see Merchant for the full shape):


{
  "id": "EVT123457",
  "type": "onboarding_submitted",
  "merchant": {
    "id": "MERCH123456",
    "name": "Example Trading Co",
    "timestamp": 1734167723000
  },
  "timestamp": 1734167723000,
  "method": "web",
  "source": "merchant-portal"
}

Response

The response depends on whether event rules are enabled for your client.

With event rules enabled

You receive a risk assessment synchronously, and an event.screened webhook is delivered.

Field	Type	Description
`id`	string	The event identifier you submitted
`riskLevel`	enum	Risk assessment: `low`, `medium_low`, `medium`, `high`, `very_high`, `n/a`
`recommendedAction`	enum	Suggested action: `ALLOW`, `REVIEW`, `BLOCK`, `STEP_UP_AUTH`, `STEP_UP_KYC`, `STEP_UP_ID`, `FLAG_FOR_MONITORING`, `REPORT_SUSPICIOUS`, `MESSAGE_USER`, `MESSAGE_MERCHANT`
`triggered`	array	Rules that triggered, empty if none
`timestamp`	number	Unix epoch milliseconds


{
  "id": "EVT123456",
  "riskLevel": "high",
  "recommendedAction": "REVIEW",
  "triggered": [
    {
      "id": "TRIG123456",
      "name": "Settlement account changed after refund spike",
      "level": "high",
      "reason": "Merchant changed banking details within 7 days of an elevated refund rate",
      "recommendedAction": "REVIEW"
    }
  ],
  "timestamp": 1734167723000
}

With event rules disabled

The event is stored and acknowledged, with no assessment.


{
  "id": "EVT123456",
  "status": "success"
}

Note: Event rules are enabled per client. Contact support@orca-fraud.com to turn on event screening and receive risk assessments from this endpoint.

Responses

200: Event ingested, and screened if event rules are enabled
400: Validation failed, including a request with no subject (none of merchantId, merchant, userId, user), a subject sent as both an id and an object, or a timestamp that is not an integer, is in the future, or is more than a year old. See Error Reference
401: Unauthorized
500: Internal server error

Example Validation Error


{
  "error": {
    "type": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      "/: Expected union value"
    ]
  },
  "timestamp": 1734167723000
}